Version Control with Git

Track your changes — learn the version control system that powers modern software development.

INFO

• Time: ~90 minutes
• Difficulty: Beginner-Intermediate
• What you'll learn: Git basics, commits, branches, GitHub collaboration

---

This Page Covers

• Why version control matters
• Core Git concepts: repos, commits, branches
• GitHub Desktop for visual Git
• Basic Git commands and collaboration

---

Why Version Control Matters

The Problem It Solves

You know that folder with files named document_v1.doc, document_v2.doc, document_final.doc, document_final_REAL.doc, and document_final_v2_ACTUALLY_FINAL.doc? We've all been there.

Version control eliminates this chaos. Instead of creating new files every time you make changes, Git tracks every change you make to your files over time. You can see exactly what changed, when it changed, and why it changed.

Even better: if you make a mistake, you can go back to any previous version. Accidentally deleted important code? Just restore it from your history. Broke something that was working yesterday? Jump back to yesterday's version and see what changed.

Benefits for Solo Developers

Complete history of your project: Every change you've ever made is recorded. Six months from now, you can look back and see exactly how your project evolved.

Automatic backup: When you push your code to GitHub, you have a backup in the cloud. If your computer crashes, your work is safe.

Experiment without fear: Want to try a risky change? Create a branch (we'll cover this soon), experiment freely, and if it doesn't work out, just delete the branch. Your main code stays untouched.

Benefits for Teams

Multiple people, one codebase: Two developers can work on the same project at the same time without overwriting each other's work. Git keeps track of who changed what.

Merge changes smoothly: When you're ready to combine everyone's work, Git handles most of the merging automatically. It only asks for help when two people edited the exact same lines.

Code review before merging: Teams can review each other's code before it becomes part of the main project. This catches bugs and helps everyone learn from each other.

---

Core Concepts

Think of Git like a time machine for your code. Here are the key concepts you need to understand:

Repository

A repository (or "repo") is simply a folder that Git is tracking. When you tell Git to track a folder, it creates a hidden .git folder inside that stores all the history and tracking information.

There are two types of repositories:

• Local repository: The version on your computer where you do your work
• Remote repository: A copy stored on a server (like GitHub) for backup and sharing

Most developers work locally, then "push" their changes to the remote repository to back them up and share them with others.

Commit

A commit is a snapshot of your project at a specific moment in time. Think of it like taking a photo of all your files.

Each commit includes:

• All the changes you made since the last commit
• A message explaining what you changed and why
• A timestamp and your identity
• A unique ID (a long string of letters and numbers)

Good commit messages are short but descriptive:

• "Add login button to homepage" (good)
• "Fix bug where prices showed negative values" (good)
• "Updated stuff" (bad - not descriptive)
• "asdfasdf" (very bad)

Branch

A branch is like a parallel timeline for your project. Imagine you could create an alternate universe where you try out a new feature, while the original universe stays exactly as it was.

The default branch is usually called main (older projects might call it master). This is your "production" code - the version that should always work.

When you want to add a new feature or fix a bug, you create a new branch, do your work there, and then merge it back into main when it's ready.

Merge

Merging is combining two branches back together. When your feature is done and tested, you merge it into the main branch.

Most of the time, Git handles merging automatically. It only gets confused when two branches changed the exact same lines of code differently - that's called a "merge conflict," and you'll need to tell Git which version to keep (we'll cover this in troubleshooting).

Push and Pull

These commands sync your local repository with the remote repository:

• Push: Upload your commits to GitHub. "I have new changes, send them to the cloud."
• Pull: Download new commits from GitHub. "Has anyone else made changes I need to get?"

A typical workflow: make changes locally, commit them, then push to GitHub. If you're working with others, pull first to get their latest changes before you start working.

---

GitHub Desktop

GitHub Desktop is a free app that gives you a visual interface for Git. Instead of typing commands, you can click buttons and see your changes visually. It's perfect for beginners.

Installation and Setup

1. Download GitHub Desktop: Go to desktop.github.com and download the app for your operating system (Windows or Mac)

2. Install the app: Run the installer and follow the prompts

3. Sign in to GitHub: When you open the app, it will ask you to sign in to your GitHub account. If you don't have one yet, create a free account at github.com

4. Configure Git: GitHub Desktop will ask for your name and email. This information appears on your commits so people know who made the changes.

Visual Interface Tour

GitHub Desktop has three main areas:

Repository list (left sidebar): Shows all the repos on your computer that GitHub Desktop knows about. Click one to work with it.

Changes view: Shows what files you've modified since your last commit. Green lines are additions, red lines are deletions. This is where you decide what to include in your next commit.

History view: Shows all your previous commits. Click any commit to see exactly what changed in that snapshot. This is your time machine - you can see your entire project history here.

Making Your First Commit

Let's walk through making your first commit:

1. Make some changes: Edit a file in your project (or create a new file)

2. Open GitHub Desktop: You should see your changed files in the "Changes" tab

3. Review your changes: Click each file to see what you modified. Make sure everything looks right.

4. Write a commit message: At the bottom left, you'll see two text boxes:

   • "Summary": A short description (required) - keep it under 50 characters
   • "Description": More details (optional) - use this for longer explanations

5. Click "Commit to main": Your changes are now saved as a commit

6. Push to GitHub: Click the "Push origin" button in the top bar to upload your commit to GitHub

---

Installing and Configuring Git

Before using Git commands, you need to install Git and configure your identity.

Installing Git

Check if Git is already installed:

Open your terminal and run:

git --version

If you see a version number (like git version 2.43.0), Git is installed. If you get an error, you need to install it.

Installing Git:

The easiest way is to install the Xcode Command Line Tools:

xcode-select --install

Or download from git-scm.com/downloads

Configuring Your Identity

Before you can make commits, Git needs to know who you are. This information appears on every commit you make.

Run these commands (replace with your actual name and email):

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Use your real email

Use the same email address you used to create your GitHub account. This links your commits to your GitHub profile.

GitHub Authentication

When you push code to GitHub, you need to prove you have permission. There are two main ways:

Option 1: GitHub Desktop (Recommended for beginners) GitHub Desktop handles authentication automatically when you sign in. This is why we covered it first - it's the easiest path.

Option 2: HTTPS with Personal Access Token When you push from the command line, GitHub will ask for your username and a "password" - but this password is actually a Personal Access Token (PAT) you create in your GitHub settings. Go to GitHub → Settings → Developer settings → Personal access tokens.

Option 3: SSH Keys More secure but requires setup. If you're just starting out, stick with GitHub Desktop or HTTPS.

GitHub Desktop handles this for you

If you use GitHub Desktop for pushing/pulling, you don't need to worry about authentication setup - it's handled when you sign in.

---

Basic Git Commands

While GitHub Desktop is great, knowing basic Git commands is useful. Many AI tools (including Claude) will suggest commands, and some things are faster in the terminal.

git init, add, commit

These three commands create a repo and save your first snapshot:

git init              # Start tracking this folder (creates .git folder)
git add .             # Stage all changed files (the . means "everything")
git commit -m "msg"   # Save a snapshot with a message

What does "staging" mean? When you run git add, you're telling Git "include these changes in my next commit." You can stage some files but not others if you want to commit changes separately.

# Stage specific files instead of everything
git add index.html            # Stage just one file
git add src/                   # Stage an entire folder
git add *.js                   # Stage all JavaScript files

git push, pull

These commands sync with GitHub:

git push              # Upload your commits to GitHub
git pull              # Download new commits from GitHub

Typical daily workflow:

git pull              # Get any changes from teammates (do this first!)
# ... do your work, edit files ...
git add .             # Stage your changes
git commit -m "Add new feature"  # Save snapshot
git push              # Upload to GitHub

git status, log

These commands show you information:

git status            # What files have changed? What's staged?
git log --oneline     # Show commit history (one line per commit)

git status tells you:

• Which branch you're on
• Which files have been modified
• Which changes are staged for the next commit
• Which files Git isn't tracking yet

git log --oneline shows your commit history. Each line has:

• A short commit ID (like a1b2c3d)
• The commit message

Press q to exit the log view.

---

Branching Strategy

Branches are one of Git's most powerful features. Here's how to use them effectively.

Why Use Branches

Branches let you isolate your work. When you're working on a new feature, you don't want half-finished code in your main project. Branches give you a safe space to work without affecting anyone else.

Branches also enable safe experimentation. Want to try a completely different approach? Create a branch and go wild. If it doesn't work out, just delete the branch. No harm done.

Main vs Feature Branches

The main branch is your "source of truth." It should always contain working code. Many teams protect the main branch so you can't push directly to it - you have to go through a pull request (more on this below).

Feature branches are where you do your actual work. The naming convention is usually:

• feature/description for new features (e.g., feature/user-login)
• fix/description for bug fixes (e.g., fix/broken-button)

Creating a branch in GitHub Desktop:

1. Click "Current Branch" in the top bar
2. Click "New Branch"
3. Give it a descriptive name
4. Click "Create Branch"

Merging and Conflicts

When you're done with your feature, you merge it back into main. Most merges are simple - Git automatically combines the changes because they don't overlap.

Conflicts happen when two branches changed the same lines differently. Git can't decide which version you want, so it asks you to choose.

In your file, you'll see something like:

<<<<<<< HEAD
This is the version in main
=======
This is the version in your branch
>>>>>>> feature/my-feature

To resolve it:

1. Delete the lines you don't want (including the <<<<<<<, =======, and >>>>>>> markers)
2. Keep the lines you do want (or combine them)
3. Save the file
4. Commit the merge

Both VS Code and GitHub Desktop have visual tools that make this easier - you can click buttons to accept one version or the other.

---

Collaboration Basics

Cloning Repositories

Cloning means downloading a copy of someone else's repository to your computer. This is how you get existing projects:

git clone https://github.com/username/repository-name.git

Or in GitHub Desktop: File > Clone Repository, then paste the URL.

Clone vs Fork:

• Clone = Download a copy to work on
• Fork = Create your own copy on GitHub (useful for contributing to projects you don't own)

Pull Requests

A Pull Request (PR) is how you propose merging your branch into main. Instead of merging directly, you create a PR that:

• Shows everyone what changes you're proposing
• Allows discussion and feedback
• Lets reviewers approve or request changes
• Documents why the change was made

PR workflow:

1. Push your feature branch to GitHub
2. On GitHub, click "Compare & pull request"
3. Write a description of what you changed and why
4. Request reviews from teammates
5. Address any feedback
6. Merge when approved

Code Review

Code review is when teammates look at your changes before they're merged. This catches bugs, spreads knowledge, and improves code quality.

As a reviewer:

• Look for bugs, typos, and logic errors
• Suggest improvements (but don't be picky about style)
• Ask questions if you don't understand something
• Approve when it looks good

As the author:

• Don't take feedback personally - it's about the code, not you
• Explain your reasoning if you disagree
• Thank reviewers for their time

---

Git Troubleshooting

Things will go wrong. Here's how to fix the most common problems.

"I Committed Secrets!"

This is serious. If you accidentally committed passwords, API keys, or other secrets:

Step 1: Rotate immediately. Assume the secret is compromised. Go to the service (AWS, Stripe, etc.) and generate new credentials. This is more important than cleaning up Git.

Step 2: Remove from history (optional but recommended). The secret is in your Git history forever unless you rewrite history. Tools like BFG Repo-Cleaner can help, but this is advanced. For important secrets, it's worth the effort.

Step 3: Prevent it from happening again:

• Add a .gitignore file that excludes .env files and other secret-containing files
• Use environment variables instead of hardcoding secrets
• Consider tools like git-secrets that block commits containing secrets

Example .gitignore entries:

.env
.env.local
*.pem
secrets.json

Merge Conflicts

Don't panic. Merge conflicts happen when two people edited the same lines. Git is asking you to decide which version to keep.

How to recognize them: Git will tell you there's a conflict, and the file will contain those <<<<<<< markers.

How to resolve them:

1. Open the conflicted file
2. Find the conflict markers
3. Decide what the final version should be:
   • Keep your version
   • Keep their version
   • Combine both
   • Write something completely new
4. Delete all the conflict markers
5. Save, stage, and commit

Tools that help:

• VS Code highlights conflicts and has "Accept Current/Incoming/Both" buttons
• GitHub Desktop shows conflicts visually and guides you through resolution

"I Messed Up" - Recovery Options

Git has multiple "undo" mechanisms:

Save work temporarily with git stash:

git stash              # Save current changes, revert to clean state
git stash pop          # Bring back your saved changes

Useful when you need to switch branches but aren't ready to commit.

Discard changes to a file:

git checkout -- filename.js    # Discard all changes to this file

Warning: This permanently deletes your uncommitted changes to that file!

Undo commits:

git reset --soft HEAD~1    # Undo last commit, keep changes staged
git reset --hard HEAD~1    # Undo last commit, delete changes (dangerous!)

When to just start fresh: Sometimes the easiest solution is to:

1. Save any files you want to keep somewhere else
2. Delete the folder
3. Clone the repository again

This gives you a clean slate matching what's on GitHub.

Common Git Errors

"Not a git repository": You're trying to run Git commands in a folder that isn't tracked by Git. Either cd to the right folder or run git init to start tracking this folder.

"Detached HEAD": You've checked out a specific commit instead of a branch. To fix this, run git checkout main (or whatever branch you want to be on).

"Failed to push" or "Updates were rejected": Someone else pushed changes while you were working. Run git pull first to get their changes, then git push again. If there are conflicts, resolve them first.

---

Key Takeaways

• Version control tracks all changes to your code
• Commits are snapshots with messages explaining changes
• Branches let you work on features without affecting main code
• GitHub Desktop makes Git visual and accessible
• Pull requests enable code review and collaboration