# Git Guide for Sylvi 🌿

Welcome! This guide will walk you through git from the ground up. Git is a version control system that helps you track changes in your projects, collaborate with others, and never lose your work. Think of it as a time machine for your code—you can save snapshots of your project at any point and jump back to them whenever you need.

## Table of Contents

1. What is Git?
2. Initial Setup
3. Understanding File Types in Git
4. Creating Your First Repository
5. The Basic Git Workflow
6. Cloning Repositories
7. Branching & Merging
8. Common Pitfalls & How to Fix Them
9. Using Gitea's Web Interface
10. Quick Reference Cheat Sheet

## 1. What is Git?

Git is a **version control system**. Imagine you're working on a game design document, and you want to try out a new idea for a level, but you're not sure if it'll work. With git, you can save your current version, try the new idea, and if it doesn't work out, you can go back to exactly where you were before. No "final_FINAL_v3_actually_final.txt" nonsense.

Git tracks changes to files over time, creating a history of your project. Every time you "save" (which we call a **commit**), git takes a snapshot of your entire project. You can view any of these snapshots at any time, compare them, or even combine changes from different versions.

## 2. Initial Setup

First, let's configure git with your information. Open your terminal and run these commands:
```bash
# Set your name (this will appear in your commits)
git config --global user.name "Sylvi"

# Set your email (use the email you registered with Gitea)
git config --global user.email "your-email@example.com"

# Set your default text editor (optional, but helpful)
git config --global core.editor "nano"  # or vim, code, etc.

# Check your configuration
git config --list
```

**💡 Why This Matters**

Every change you make in git is tagged with your name and email. This helps everyone (including future you) know who made which changes and when.

## 3. Understanding File Types in Git

When working with git, you'll encounter a few special files and formats. Let's break them down:

### .git Directory

This hidden folder is where git stores all its magic. It contains the entire history of your project, all your commits, branches, and configuration. You'll never need to edit files in here directly—git handles it all. If you delete this folder, you lose all your git history (but not your current files).

### .gitignore File

This file tells git which files or folders to ignore. It's super useful for keeping temporary files, build artifacts, or sensitive data out of your repository.
```
# Example .gitignore file
# Ignore all .log files
*.log

# Ignore the node_modules directory
node_modules/

# Ignore OS-specific files
.DS_Store
Thumbs.db

# Ignore your personal config
config/secrets.json
```

### README.md

Not required by git, but it's a convention to include a README file (usually in Markdown format) that explains what your project is, how to use it, and any other important information. This is the first thing people see when they visit your repository.

### LICENSE

If you're sharing your code, it's good practice to include a license file that specifies how others can use your work. Common options include MIT, GPL, or Creative Commons licenses.

### Common File Formats You'll Work With

- **.md** - Markdown files (like README.md) for documentation
- **.html, .css, .js** - Web development files
- **.json** - Configuration and data files
- **.yml/.yaml** - Configuration files (common in DevOps)
- **.txt** - Plain text files
- **No extension** - Shell scripts, config files (like .gitignore)

**Binary Files:** Images (.png, .jpg), compiled code, videos, etc. Git can track these, but it can't show you the differences between versions like it can with text files.

## 4. Creating Your First Repository

There are two ways to start with git: create a new repository from scratch, or clone an existing one. Let's start with creating one locally.

### Method 1: Local Repository (Command Line)
```bash
# Create a new directory for your project
mkdir my-awesome-project
cd my-awesome-project

# Initialize a git repository
git init

# Check the status (you should see "No commits yet")
git status
```

That's it! You now have a git repository. The `git init` command created that `.git` folder we talked about earlier.

### Method 2: Create on Gitea First (Web Interface)

You can also create a repository through Gitea's web interface, then clone it to your computer. This is often easier when you want to set up a README, license, or .gitignore right away.

1. Log into your Gitea account
2. Click the "+" icon or "New Repository" button
3. Give it a name, description, and choose whether it's public or private
4. Optionally add a README, .gitignore template, and license
5. Click "Create Repository"

Gitea will then show you the commands to clone it to your computer (we'll cover cloning in section 6).

### Practice Exercise #1

Create a new directory called `git-practice` and initialize it as a git repository. Then check its status.

**Solution:**
```bash
mkdir git-practice
cd git-practice
git init
git status
```

You should see a message like "On branch main" (or master) and "No commits yet".

## 5. The Basic Git Workflow

The core git workflow has three main stages, and once you understand these, everything else falls into place:

1. **Working Directory** - Your actual files that you're editing
2. **Staging Area** - Files you've marked to be included in the next commit
3. **Repository** - The committed history of your project

Here's the typical flow:

### Step 1: Make Changes

Create or edit files in your project.
```bash
# Create a new file
echo "# My Awesome Project" > README.md

# Check what's changed
git status
```

Git will show you that `README.md` is an "untracked file." It knows the file exists, but it's not tracking changes to it yet.

### Step 2: Stage Changes

Tell git which changes you want to include in the next commit. This is like packing a box before you ship it.
```bash
# Stage a specific file
git add README.md

# Or stage all changes at once
git add .

# Check status again
git status
```

Now the file shows up under "Changes to be committed." It's in the staging area.

### Step 3: Commit Changes

Create a snapshot of your staged changes with a message describing what you did.
```bash
# Commit with a message
git commit -m "Add README file"

# View your commit history
git log
```

**💡 Writing Good Commit Messages**

Your commit messages should be clear and descriptive. Think of them as notes to your future self (or your collaborators). Good examples:

- ✅ "Add player movement controls"
- ✅ "Fix collision detection bug in level 3"
- ✅ "Update homepage layout with new color scheme"
- ❌ "stuff" (too vague)
- ❌ "fixed bug" (which bug?)

### Step 4: Push to Remote

If you're working with Gitea (or any remote repository), you'll want to push your commits to the server so they're backed up and others can see them.
```bash
# Push your commits to the remote repository
git push origin main

# Or if your default branch is named 'master'
git push origin master
```

**Origin** is the name git gives to your remote repository (the one on Gitea). **Main** (or master) is the name of your primary branch.

**⚠️ First Push Setup**

The first time you push to a new repository, you might need to set up the connection:
```bash
# Add your Gitea repository as the remote
git remote add origin https://your-gitea-instance.com/username/repo-name.git

# Set the default upstream branch
git push -u origin main
```

After this initial setup, you can just use `git push`.

### Step 5: Pull Updates

If you're collaborating with others (or working on multiple computers), you'll need to pull changes from the remote repository before you start working.
```bash
# Fetch and merge changes from the remote
git pull origin main
```

This downloads any new commits from Gitea and merges them into your local repository.

### Practice Exercise #2

In your `git-practice` directory:

1. Create a file called `index.html` with some basic HTML
2. Stage the file
3. Commit it with a descriptive message
4. View your commit history

**Solution:**
```bash
# Create the file (you can use your favorite editor instead of echo)
echo "<!DOCTYPE html><html><body><h1>Hello!</h1></body></html>" > index.html

# Stage it
git add index.html

# Commit it
git commit -m "Add basic HTML homepage"

# View history
git log
```

## 6. Cloning Repositories

Cloning is how you download a copy of an existing repository from Gitea (or GitHub, GitLab, etc.) to your computer. It's like getting a complete copy of someone else's project, including all its history.
```bash
# Clone a repository
git clone https://your-gitea-instance.com/username/repo-name.git

# Clone into a specific directory name
git clone https://your-gitea-instance.com/username/repo-name.git my-local-folder

# Clone and automatically set up remote tracking
git clone https://your-gitea-instance.com/username/repo-name.git
cd repo-name
git remote -v  # Shows your remote connections
```

When you clone, git automatically sets up the remote connection for you (it calls it "origin"), so you can immediately start pushing and pulling.

**💡 HTTPS vs SSH**

You'll see two types of URLs for cloning: HTTPS (`https://...`) and SSH (`git@...`). HTTPS is simpler to start with—you'll just need to enter your username and password when pushing. SSH is more secure and convenient once set up, but requires generating and adding SSH keys to Gitea.

### Practice Exercise #3

Find a repository on your Gitea instance (maybe one of Nicholai's projects, with permission!) and clone it to your computer. Explore the files and check out the commit history with `git log`.

## 7. Branching & Merging

Branches are one of git's most powerful features. They let you work on new features or experiments without affecting the main codebase. Think of them like parallel universes for your project—you can try things out in one branch, and if they don't work, you can just delete that branch without any consequences to your main code.

### Understanding Branches

When you create a new repository, you start on a default branch (usually called `main` or `master`). This is your primary timeline. When you create a new branch, you're creating a copy of the current state that you can modify independently.

### Creating and Switching Branches
```bash
# Create a new branch
git branch new-feature

# Switch to that branch
git checkout new-feature

# Or create and switch in one command
git checkout -b new-feature

# See all your branches
git branch

# The branch with * is your current branch
```

Now any commits you make will be on the `new-feature` branch, not on `main`.

### Merging Branches

Once you're happy with your changes on a branch, you can merge them back into your main branch.
```bash
# Switch back to main
git checkout main

# Merge the new-feature branch into main
git merge new-feature

# Delete the branch if you're done with it
git branch -d new-feature
```

### A Typical Branching Workflow

1. You're working on `main` and want to add a new feature
2. Create a new branch: `git checkout -b add-menu-system`
3. Make your changes and commit them to this branch
4. Switch back to main: `git checkout main`
5. Merge your feature: `git merge add-menu-system`
6. Delete the feature branch: `git branch -d add-menu-system`

**⚠️ Merge Conflicts**

Sometimes, git can't automatically merge branches because the same lines of code were changed in both branches. This is called a **merge conflict**. Don't panic! Git will mark the conflicting sections in your files, and you'll need to manually choose which changes to keep.

Files with conflicts will look like this:
```
<<<<<<< HEAD
Your changes on the current branch
=======
Changes from the branch being merged
>>>>>>> new-feature
```

Edit the file to keep what you want, remove the markers, then stage and commit the resolved file.

### Practice Exercise #4

In your practice repository:

1. Create a new branch called `experiment`
2. Switch to it and make some changes to your HTML file
3. Commit those changes
4. Switch back to `main`
5. Merge the `experiment` branch into `main`

**Solution:**
```bash
git checkout -b experiment
# Edit index.html with your editor
git add index.html
git commit -m "Try experimental layout"
git checkout main
git merge experiment
git branch -d experiment
```

## 8. Common Pitfalls & How to Fix Them

Everyone makes mistakes with git. Here are some common ones and how to recover from them.

### Mistake #1: Committed to the Wrong Branch

If you haven't pushed yet:
```bash
# Create a new branch with your current changes
git branch correct-branch

# Reset the current branch to the previous commit
git reset --hard HEAD~1

# Switch to the correct branch
git checkout correct-branch
```

### Mistake #2: Want to Undo the Last Commit
```bash
# Undo the last commit but keep the changes
git reset --soft HEAD~1

# Undo the last commit and discard the changes (careful!)
git reset --hard HEAD~1

# Undo the last commit and create a new commit that reverses it
git revert HEAD
```

`revert` is safer if you've already pushed, as it doesn't rewrite history.

### Mistake #3: Accidentally Staged the Wrong Files
```bash
# Unstage a specific file
git reset HEAD file-name.txt

# Unstage all files
git reset HEAD
```

### Mistake #4: Need to See What Changed
```bash
# See unstaged changes
git diff

# See staged changes
git diff --staged

# See changes in a specific file
git diff file-name.txt

# See changes between commits
git diff commit1 commit2
```

### Mistake #5: Merge Conflict Panic

If you're in the middle of a merge and want to abort:
```bash
git merge --abort
```

To resolve conflicts properly:

1. Open the conflicting files
2. Look for the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
3. Decide which changes to keep and edit the file
4. Remove the conflict markers
5. Stage the resolved file: `git add file-name.txt`
6. Complete the merge: `git commit`

### Mistake #6: Pushed Sensitive Data (Passwords, Keys, etc.)

**⚠️ Important Security Warning**

If you accidentally commit and push sensitive information (passwords, API keys, etc.), removing it from git history isn't enough—you should consider that data compromised. Change the passwords/keys immediately, then remove them from git history.

This is why .gitignore is so important! Always ignore files with sensitive data.

## 9. Using Gitea's Web Interface

While the command line is powerful, Gitea's web interface can be more convenient for certain tasks.

### Viewing Files and Commits

Browse your repository's files, view the commit history, and see who changed what. Click on any commit to see the exact changes (the "diff").

### Creating and Editing Files

You can create new files or edit existing ones directly in the browser. This is handy for quick fixes or updating documentation.

### Pull Requests

If you're collaborating with Nicholai or others, pull requests (PRs) are how you propose changes. You create a branch, push your changes, then open a PR in Gitea to ask for those changes to be merged into the main branch. Others can review your code and suggest changes before merging.

### Issues

Gitea has a built-in issue tracker for reporting bugs, requesting features, or discussing ideas. Each issue can have labels, assignees, and comments.

### Releases

When your project reaches a milestone, you can create a release—a snapshot of your code at that point, usually with a version number (like v1.0.0).

**💡 Gitea vs GitHub**

Gitea is very similar to GitHub—the interface and workflows are almost identical. If you learn one, you'll be comfortable with the other. The main difference is that Gitea is self-hosted (running on Nicholai's server), while GitHub is a cloud service.

## 10. Quick Reference Cheat Sheet

### Repository Setup
```bash
git init                          # Create a new repository
git clone <url>                   # Clone an existing repository
git remote add origin <url>       # Connect to a remote repository
```

### Basic Workflow
```bash
git status                        # Check what's changed
git add <file>                    # Stage a file
git add .                         # Stage all changes
git commit -m "message"           # Commit staged changes
git push origin main              # Push to remote
git pull origin main              # Pull from remote
```

### Branching
```bash
git branch                        # List branches
git branch <name>                 # Create a new branch
git checkout <branch>             # Switch to a branch
git checkout -b <branch>          # Create and switch to a new branch
git merge <branch>                # Merge a branch into current branch
git branch -d <branch>            # Delete a branch
```

### Viewing History
```bash
git log                           # View commit history
git log --oneline                 # Compact commit history
git diff                          # See unstaged changes
git diff --staged                 # See staged changes
git show <commit>                 # Show details of a commit
```

### Undoing Changes
```bash
git reset HEAD <file>             # Unstage a file
git reset --soft HEAD~1           # Undo last commit, keep changes
git reset --hard HEAD~1           # Undo last commit, discard changes
git revert <commit>               # Create new commit that undoes changes
git checkout -- <file>            # Discard changes to a file
```

### Helpful Commands
```bash
git config --list                 # View your configuration
git remote -v                     # View remote connections
git branch -a                     # List all branches (including remote)
git fetch                         # Download remote changes without merging
git clean -fd                     # Remove untracked files and directories
```

---

## Where to Go From Here

This guide covers the essentials, but git has a lot more to offer. As you get comfortable with these basics, you might want to explore:

- **Git hooks** - Automate tasks when certain git events happen
- **Rebasing** - An alternative to merging that keeps history cleaner
- **Stashing** - Temporarily save changes without committing
- **Submodules** - Include other git repositories within your project
- **Tags** - Mark specific commits as important milestones

The best way to learn git is to use it. Start with small personal projects, make frequent commits with good messages, and don't be afraid to experiment—that's what branches are for! And remember, Nicholai's just a message away if you get stuck.

Happy coding! 🌱