Skip to main content

​
Synopsis

git checkout [-q] [-f] [-m] [<branch>]
git checkout [-q] [-f] [-m] --detach [<branch>]
git checkout [-q] [-f] [-m] [--detach] <commit>
git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
git checkout <tree-ish> [--] <pathspec>...
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]

​
Description

git checkout has two main modes:
  1. Switch branches - with git checkout <branch>
  2. Restore a different version of a file - for example with git checkout <commit> <filename> or git checkout <filename>
If a branch is not found but there does exist a tracking branch in exactly one remote with a matching name, Git will automatically create and checkout a new local branch tracking the remote branch.
In modern Git (2.23+), the git switch and git restore commands are recommended as clearer alternatives to git checkout for switching branches and restoring files respectively.

​
Common Usage

1

Switch to an existing branch

git checkout main
2

Create and switch to a new branch

git checkout -b feature-branch
Create from a specific starting point:
git checkout -b feature-branch main
3

Discard changes to a file

git checkout -- file.txt
4

Restore a file from a specific commit

git checkout abc123 -- file.txt

​
Options

Create a new branch and check it out.
git checkout -b feature-branch
If you specify a start point, the new branch will be based on that commit:
git checkout -b hotfix main
Similar to -b, but if the branch already exists, reset it to the start point.
git checkout -B feature main
Check out a commit for inspection and discardable experiments. This puts you in “detached HEAD” state.
git checkout --detach v1.0.0
When switching branches, proceed even if the index or working tree differs from HEAD. This will discard local changes.
git checkout -f main
This will throw away local changes and any untracked files in the way.
When switching branches, if you have local modifications, perform a three-way merge between the current branch, your working tree, and the new branch.
git checkout -m feature-branch
When checking out paths from the index, check out stage #2 (ours) or #3 (theirs) for unmerged paths.
git checkout --ours conflicted-file.txt
git checkout --theirs conflicted-file.txt
During git rebase and git pull --rebase, ours and theirs are swapped:
  • --ours gives the version from the branch being rebased onto
  • --theirs gives the version from your branch being rebased
Interactively select hunks in the difference to apply in reverse to the working tree.
git checkout -p
This allows you to selectively discard edits from your current working tree.
Suppress feedback messages.
git checkout -q main
When creating a new branch, set up upstream tracking configuration.
git checkout -t origin/feature
Create a new orphan branch with no parent commits, starting from the specified start point.
git checkout --orphan gh-pages
This is useful when you want to start a completely new history.

​
Examples

​
Working with files

# Switch to master branch
git checkout master

# Revert a file to two revisions back
git checkout master~2 Makefile

# Restore a deleted file from the index
rm -f hello.c
git checkout hello.c

# Check out all C source files from the index
git checkout -- '*.c'

# Disambiguate when filename matches branch name
git checkout -- hello.c

​
Switching branches with local changes

# Try to switch branches
git checkout mytopic
# error: You have local changes to 'frotz'; not switching branches.

# Use merge option to perform three-way merge
git checkout -m mytopic
# Auto-merging frotz

​
Creating branches

# Create and switch to a new branch
git checkout -b feature-auth

# Create from a specific commit
git checkout -b hotfix-123 v1.0.0

# Create an orphan branch
git checkout --orphan new-history

​
Detached HEAD

When you checkout a commit that is not the tip of any branch, you enter “detached HEAD” state: 
# Checkout a specific commit
git checkout abc123

# Or checkout a tag
git checkout v2.0
In this state:
  • HEAD points directly to a commit, not a branch
  • New commits you create will not belong to any branch
  • When you switch away, these commits may become unreachable
To save work done in detached HEAD state: 
# Create a new branch from current position
git checkout -b new-branch

# Or create without switching
git branch new-branch

# Or create a tag
git tag my-experiment

​
Argument Disambiguation

When you run git checkout <something>, Git tries to determine whether it’s a branch, commit, or file path. If there’s ambiguity, use -- to force Git to treat the parameter as a file: 
# Force checkout of file named 'master'
git checkout -- master
For a clearer interface, consider using:
  • git switch for changing branches
  • git restore for restoring files
These commands were introduced in Git 2.23 to split the functionality of git checkout.
  • git switch - Switch to a branch (modern alternative)
  • git restore - Restore working tree files (modern alternative)
  • git branch - List, create, or delete branches
  • git merge - Join two or more development histories

Build docs developers (and LLMs) love

Get started for freeTalk to us