Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Branches and Tags

git checkout command

Reference for git checkout: switch branches, create with -b, detach HEAD, restore files from the index or a commit, and the modern switch and restore replacements.

git checkout does two quite different jobs. With a branch or commit it moves HEAD and updates the working tree to match (the job now done by git switch). With a path it overwrites files in the working tree from the index or from a commit (now git restore).

Since Git 2.23 the split commands are preferred for clarity, but checkout is not deprecated and appears in countless guides and scripts, so you need to know all its forms.

Terminal
git checkout main                # switch branch
git checkout -b topic            # create and switch
git checkout -- file.txt         # discard working-tree changes to a file
git checkout abc1234 -- file.txt # take a file from another commit

Try it

Bash Branch forms

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash File forms: restore from index and from a commit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git checkout [-q] [-f] [-m] [<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 (-p | --patch) [<tree-ish>] [--] [<pathspec>...]
git checkout (--ours | --theirs) [--] <pathspec>...
Name Description
<branch> Switch to this branch. If it does not exist locally but exactly one remote has it, a tracking branch is created.
-b <new> / -B <new> Create (or reset, with -B) a branch and switch to it.
--detach Check out a commit with a detached HEAD.
--orphan <new> Start a branch with no parents.
<tree-ish> -- <paths> Copy these files from a commit or tree into the index and working tree.
-- <paths> Copy these files from the index into the working tree.
--ours, --theirs During a merge, take the version from the current branch or the branch being merged.
-p, --patch Choose hunks interactively.
-f, --force Discard local changes.
-m, --merge Merge local changes into the new branch.
- Shortcut for the previous branch.

Returns: messages on standard error; exit status 0 on success.

Errors: local changes that would be overwritten block a branch switch; an unknown name fails with "pathspec did not match any file(s) known to git".

Usage notes

  • File forms are destructive. git checkout -- file silently throws away unstaged edits, with no undo. Compare with the safer, clearer git restore file.
  • The -- matters. It tells Git the rest are paths, so a file and a branch with the same name are not confused.
  • With a commit and paths, the files are also staged. With only paths, the index is the source and nothing is staged.
  • Detached HEAD: checking out a tag, a remote branch (origin/main) or a hash detaches HEAD. Commits made there belong to no branch; run git switch -c name before leaving to keep them.
  • git checkout <name> is ambiguous when a branch and a file share a name; Git picks the branch unless you give --.
  • --ours and --theirs swap meaning during a rebase: ours is the branch being rebased onto, theirs is your replayed commit.
  • git checkout . restores every modified tracked file in the directory, a common accident.
  • Performance: switching branches touches only differing files, but large trees with many changes can be slow; consider sparse checkout.