git checkout Command Guide
Switch branches or restore working tree files
Dai Aoki
CEO at init, Inc. / CTO at US & JP startups / Creator of WebTerm
Quick Reference
Branches
git checkout <branch>Switch to branchgit checkout -b <name>Create and switchgit checkout -Switch to previousFiles
git checkout -- <file>Discard changesgit checkout HEAD <file>Restore from HEADgit checkout <commit> -- <file>Get file versionDetached
git checkout <commit>Detached HEADgit checkout <tag>Checkout taggit checkout HEAD~33 commits backDownloadable Image Preview
Basic Usage
The git checkout command switches branches and restores working tree files. It's a versatile command with multiple use cases.
# Switch to an existing branch
git checkout main
# Create and switch to new branch
git checkout -b feature-x
# Discard changes in a file
git checkout -- src/app.jsgit switch for branches and git restore for files. They're clearer alternatives.Switching Branches
# Switch to existing branch
git checkout develop
# Create and switch to new branch
git checkout -b feature/login
# Create branch from specific commit
git checkout -b hotfix abc1234
# Switch to previous branch
git checkout -
# Track and checkout remote branch
git checkout --track origin/feature-xRestoring Files
# Discard changes in working directory
git checkout -- file.js
# Restore file from specific commit
git checkout abc1234 -- file.js
# Restore file from another branch
git checkout main -- src/config.js
# Restore all files in directory
git checkout -- src/
# Restore to HEAD (same as --)
git checkout HEAD -- file.jsgit checkout -- <file> permanently discards uncommitted changes. This cannot be undone if the changes weren't staged.Detached HEAD State
Checking out a commit (not a branch) puts you in "detached HEAD" state:
# Checkout a specific commit (detached HEAD)
git checkout abc1234
# Checkout a tag
git checkout v1.0.0
# Go back N commits
git checkout HEAD~3
# View the detached state warning
# "You are in 'detached HEAD' state..."
# Create a branch to save work in detached HEAD
git checkout -b new-branch-nameDetached HEAD Tips
- • Safe for viewing old code
- • Commits made here can be lost
- • Create a branch to preserve work
- • Return to a branch with
git checkout main
Checkout vs Switch/Restore
Git 2.23 introduced clearer alternatives:
# Old way (checkout does everything)
git checkout main # Switch branch
git checkout -b feature # Create and switch
git checkout -- file.js # Restore file
# New way (separate commands)
git switch main # Switch branch
git switch -c feature # Create and switch
git restore file.js # Restore filePractical Examples
# Start new feature
git checkout -b feature/payment
# Quick switch between main and feature
git checkout main
git checkout - # Back to feature
# Discard all local changes
git checkout -- .
# Get file from main branch
git checkout main -- package.json
# Explore old version without committing
git checkout v1.0.0
# ... look around ...
git checkout main # ReturnFrequently Asked Questions
What is a detached HEAD state?
Detached HEAD means you're not on a branch - you're looking at a specific commit. Any new commits won't belong to any branch and could be lost. Create a branch to save your work.
What is the difference between git checkout and git switch?
They both switch branches, but switch (Git 2.23+) is clearer and safer. checkout can also restore files, while switch only handles branches. For files, use "git restore" instead.
How do I discard uncommitted changes to a file?
Use "git checkout -- <file>" or the newer "git restore <file>". This discards working directory changes - the file reverts to its last committed state.
What does "git checkout -" do?
It switches back to the previously checked out branch. It's like "cd -" in bash - a quick way to toggle between two branches.
Can I checkout a file from another branch?
Yes! Use "git checkout <branch> -- <file>" to get a specific file from another branch without switching branches.
Summary
git checkout is versatile but can be confusing. Consider using git switch and git restore for clarity.
Quick Reference
git checkout <branch>- Switch branchgit checkout -b <name>- Create and switchgit checkout -- <file>- Discard changesgit checkout -- Previous branch
Official Documentation
For authoritative information, refer to the official documentation: