git checkout & git switch
Switching branches and restoring files with git checkout and the newer git switch command.
What you'll learn
- How to switch between branches with git checkout and git switch
- Restoring files with git checkout -- and git restore
- Creating a new branch and switching to it
- Detached HEAD state and how to avoid it
Concept
Switching Branches
git checkout is the traditional command for switching branches:
git checkout main
git checkout feature-login
Git 2.23 introduced git switch as a clearer, dedicated command for branch switching:
git switch main
git switch feature-login
git switch is preferred for new scripts and learning because it does only one thing (switch branches), while git checkout is overloaded with multiple meanings.
Creating and Switching
# Old way — create and switch
git checkout -b new-feature
# New way — create and switch
git switch -c new-feature
# Create a new branch from a specific commit
git switch -c hotfix abc1234
Restoring Files
git checkout can also restore files to a previous state, which is confusing because the same command does two different things. The newer git restore command is clearer:
# Discard uncommitted changes to a file
git checkout -- style.css
# or:
git restore style.css
# Restore a file from a specific commit
git restore --source=HEAD~1 style.css
Warning: restoring discards your uncommitted changes permanently. There is no undo.
Detached HEAD
If you checkout a commit hash directly (not a branch name), you enter detached HEAD state:
git checkout abc1234
# You are now in 'detached HEAD' state
In this state, any commits you make are not on any branch and can be lost. If you want to explore an old commit and make changes, create a branch first:
git switch -c explore-old-commit abc1234
If you accidentally entered detached HEAD and made commits, you can save them by creating a branch:
git switch -c my-rescued-branch
Checking Out Remote Branches
When you fetch a remote branch, you can switch to it and Git creates a local tracking branch automatically:
git switch origin/feature-remote
# or:
git checkout feature-remote
The Mental Model
Think of git switch as "change where I am" and git restore as "change what my files look like". The old git checkout does both, which is why the Git team split it into two commands.
Example
# Switch to an existing branch
git checkout main
git switch main
# Create a new branch and switch to it
git checkout -b feature-api
git switch -c feature-api
# Switch back to the previous branch (like cd -)
git switch -
# List all branches and switch
git branch -a
git switch feature-login
# Discard changes to a file (restore from last commit)
git checkout -- style.css
git restore style.css
# Restore a file from 2 commits ago
git restore --source=HEAD~2 config.js
# Restore all modified files (be careful!)
git restore .
# Checkout a remote branch (creates local tracking branch)
git switch origin/feature-remote
# or:
git checkout -b feature-remote origin/feature-remote
# If you are in detached HEAD, rescue your commits
git switch -c my-new-branch
# View a file as it was in a previous commit
git show HEAD~3:src/app.js
Covers switching branches, creating and switching, the convenient switch - shortcut, restoring files, checking out remote branches, and rescuing commits from detached HEAD. The modern git switch and git restore commands are clearer than the overloaded git checkout.
Try it
- Code Diff
Compare file versions before restoring them.
- .gitignore Generator
Generate a .gitignore for your new branch.
Common mistakes
The mistake
Checking out a commit hash and making commits in detached HEAD state
The fix
Checking out a commit (not a branch) puts you in detached HEAD. Commits made here are not on any branch and can be lost. If you need to make changes from an old commit, create a branch first: git switch -c new-branch <commit>. If you already committed in detached HEAD, rescue with git switch -c rescue-branch.
The mistake
Using git checkout -- file to discard changes and then realizing you needed them
The fix
git checkout -- file (or git restore file) permanently discards uncommitted changes with no undo. If you might need those changes, stash them first with git stash. Only restore when you are certain the changes are not needed.
Related Resources
Related Cheatsheets
- Git Cheatsheet
checkout, switch, and restore commands.
Practice git checkout & git switch
2 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.