Git/You've created branches, you've named them well, and now you're staring at them in the git branch output. The asterisk is sitting on main, but your feature branch is calling your name. How do you actually move between these parallel universes?
Switching branches is where the magic happens. When you run git checkout, Git doesn't just update a pointer, it transforms your entire working directory. Files appear, disappear, and change content. It's like stepping through a portal into a different version of your project.
The checkout command: your interdimensional teleporter
The basic syntax is beautifully simple:
git checkout feature-loginRun this, and suddenly your working directory reflects the feature-login branch. Files that exist on feature-login but not on main appear. Files that were modified on feature-login show those modifications. The files on your disk literally change to match the branch you're checking out.
Let's see what happens step by step:
# You're on main, let's check
git branch
# Output: * main
# feature-login
# Switch to the feature branch
git checkout feature-login
# Output: Switched to branch 'feature-login'
# Confirm the switch
git branch
# Output: main
# * feature-login ← the asterisk moved!Notice how the asterisk moved? That's your confirmation. Any commits you make now go onto feature-login, not main.
What happens behind the scenes
When you checkout a branch, Git does three things:
- Updates HEADWhat is head?A special pointer in Git that indicates the commit you are currently working on - usually the tip of the active branch.: The HEAD pointer now references your new branch
- Updates your working directory: Files are added, removed, or modified to match the target branch
- Updates the indexWhat is index?A data structure the database maintains alongside a table so it can find rows by specific columns quickly instead of scanning everything.: The staging areaWhat is staging area?A holding zone in Git where you place changes you want to include in your next commit, letting you select exactly which modifications to save. is prepared for the new branch's state
This happens in milliseconds for most projects. You're not copying files, Git is simply updating references and applying the differences.
The shortcut you'll use every day: create and switch
Remember how git branch creates a branch but leaves you where you are? And then you have to run git checkout to switch? That's two commands for a single workflow step.
Meet the flag that will become your best friend:
git checkout -b feature-navbarThe -b flag stands for "branch." This command does both things at once:
# These two commands:
git branch feature-navbar
git checkout feature-navbar
# Are the same as this one command:
git checkout -b feature-navbarThis is the command you'll use most often. When you start working on something new, you don't want to think about the mechanics, you just want to create a branch and get to work.
git checkout -b feature/search first. Before implementing any AI-suggested feature, always create and switch to a new branch. It costs three seconds and saves you from polluting main.Variations you'll encounter
The -b flag has some useful siblings:
# Create and switch, but based on a specific branch
git checkout -b feature-navbar main
# Even if you're currently on a different branch,
# this creates feature-navbar from main and switches to itThis is useful when you want to start fresh from main but you're currently somewhere else.
The danger zone: uncommitted changes
Here's where beginners get burned. You have some changes in your working directory, maybe you edited a file or two, and you try to switch branches:
$ git checkout main
error: Your local changes to the following files would be overwritten by checkout:
index.html
style.css
Please commit your changes or stash them before you switch branches.
AbortingGit just saved you from losing work. If you had switched, those changes would have been overwritten by whatever versions of those files exist on main.
Your options when you have uncommitted changes
You have three ways forward:
| Situation | Command | Use when |
|---|---|---|
| Work is ready | git add . && git commit -m "..." | You want to save changes |
| Work in progress | git stash | You'll come back soon |
| Don't need changes | git checkout -- . | You want to discard everything |
Option 1: CommitWhat is commit?A permanent snapshot of your staged changes saved in Git's history, identified by a unique hash and accompanied by a message describing what changed. your changes
This is the cleanest approach if your work is ready:
git add .
git commit -m "WIP: working on login form styling"
git checkout mainOption 2: Stash your changes
If your work isn't ready to commit but you need to switch branches:
git stash
git checkout main
# Do whatever you need on main...
git checkout feature-login
git stash pop # Get your changes backStashing is like putting your changes in a temporary drawer. We'll cover stashing in detail later, but for now, just know it's your "save for later" button.
Option 3: Discard your changes
If you don't care about the changes:
git checkout -- .
git checkout mainThe -- tells Git to discard changes in your working directory. Use with caution, this deletes your modifications permanently.
The modern way: git switch
Git 2.23 (released August 2019) introduced two new commands that split the overloaded git checkout into clearer, more focused commands:
git switch, For switching branches (what we're learning now)git restore, For restoring files (we'll cover this later)
Here's how git switch compares:
# Old way (still works, but overloaded)
git checkout feature-login
git checkout -b new-feature
# New way (clear and explicit)
git switch feature-login
git switch -c new-feature # -c means "create"Handy git switch tricks
# Switch to the previous branch (toggle between two branches)
git switch -
# Same as git checkout -b, create and switch
git switch -c feature-navbar
# Create from a specific starting point
git switch -c feature-navbar mainThe dash (-) is incredibly useful when you're comparing code between two branches. Switch back and forth with just git switch -, it's like a toggle switch.
git switch is clearer. If you're working on existing projects or reading older tutorials, you'll see git checkout everywhere. Know both, but prefer git switch when you have the choice.A complete workflow example
Let's put it all together in a realistic scenario:
# Start on main, make sure it's up to date
git checkout main
git pull origin main
# Create and switch to a feature branch
git checkout -b feature/contact-form
# Do some work...
echo "<form>..." > contact.html
git add contact.html
git commit -m "Add contact form HTML"
# Realize you need to check something on main
git stash
git checkout main
# Check whatever you needed to check...
# Go back to your feature branch
git checkout feature/contact-form
git stash pop
# Continue working...This workflow, branch, work, stash, switch, restore, is how professional developers move between tasks without losing context.
Quick reference
| Command | What it does | When to use it |
|---|---|---|
git checkout branch | Switch to existing branch | Moving between work |
git checkout -b name | Create and switch | Starting new work (most common) |
git switch branch | Modern switch | Clearer alternative |
git switch -c name | Modern create and switch | Clearer alternative to -b |
git switch - | Toggle last two branches | Quick comparison |
git stash | Save uncommitted changes | Need to switch but not ready |
git stash pop | Restore stashed changes | Back to where you were |
# Switch to a feature branch
git checkout feature-login
# Create and switch to new branch
git checkout -b feature-signup
# Switch back to main
git checkout main
# Modern syntax (Git 2.23+)
git switch feature-branch
git switch -c new-branch