Git Course 0%

git checkout

Intermediate Git CLI Careful ≈ 6 min

Summary: git checkout is the original command for three unrelated jobs: switching branches, restoring files from a commit, and visiting a commit without a branch. Since Git 2.23 the first two have clearer replacements, git switch and git restore.

Careful — git checkout -- <file> silently discards uncommitted changes to that file. The branch-switching forms are safe.

What it does

Depends entirely on its argument, which is the reason it was split:

Form Job Modern equivalent
git checkout <branch> switch branches git switch <branch>
git checkout -b <name> create and switch git switch -c <name>
git checkout -- <file> discard changes to a file git restore <file>
git checkout <commit> -- <file> take a file from a commit git restore --source=<commit> <file>
git checkout <commit> visit a commit (detached HEAD) git switch --detach <commit>
git checkout --ours/--theirs <file> take one side during a conflict (no replacement; still used)

Why it exists

It predates the split. It still works, is not deprecated, and appears in most tutorials, colleagues' instructions and search results, so you need to read it fluently even if you never type it.

When to use it

  • Reading older documentation and translating it.
  • Choosing a side during a conflict: git checkout --ours <file> / --theirs <file> (lesson 11.2).
  • Restoring the conflicted state of a file: git checkout --merge <file>.
  • When a colleague dictates it and you would rather not translate mid-conversation.

When not to use it

  • For switching branches, in new writing: git switch says what it does.
  • For discarding file changes: git restore cannot be confused with a branch operation.

Syntax

Form Meaning
git checkout <branch> Switch
git checkout -b <name> [<start>] Create and switch
git checkout -- <file> Discard uncommitted changes Dangerous
git checkout <commit> Detached HEAD at that commit
git checkout <commit> -- <file> Take that file from that commit
git checkout --ours <file> / --theirs <file> During a conflict, take one side
git checkout --merge <file> During a conflict, restore the markers

Examples

Visiting an old commit, and the message Git prints:

Terminal
$ git checkout HEAD~1
Note: switching to 'HEAD~1'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at 0d9eb38 docs: add map question to FAQ (#9)
Terminal
$ git status
HEAD detached at 0d9eb38
nothing to commit, working tree clean

Returning:

Terminal
$ git switch -
Previous HEAD position was 0d9eb38 docs: add map question to FAQ (#9)
Switched to branch 'main'
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

Choosing a side during a conflict:

Terminal
$ git checkout --theirs docs/images/logo.png
$ git add docs/images/logo.png

Expected result

Branch forms move HEAD and rewrite files. File forms overwrite the named files in the working tree, discarding uncommitted changes to them without asking. Commit forms leave you in detached HEAD.

Common mistakes

  • git checkout -- <file> expecting to unstage. It discards the edit instead; unstaging is git restore --staged <file>.
  • Committing in detached HEAD and switching away. The commit belongs to no branch; git reflog recovers it (lesson 12.5). Create a branch first: git switch -c <name>.
  • Reading old instructions literally. git checkout mybranch is a switch; git checkout -- myfile is a discard. The -- matters.
  • Assuming --ours means your branch during a rebase. The sides are swapped there (lesson 11.5).

How to undo or recover

  • After a branch switch: git switch -.
  • After discarding a file: the uncommitted content is gone; only your editor's undo or IntelliJ's Local History may help. This is why restore exists with a clearer name.
  • After committing in detached HEAD: git reflog, then git branch <name> <hash>.

In VS Code

Everything is under the branch picker and Git: Checkout to…; VS Code never runs the destructive file form without a confirmation dialog labelled Discard Changes.

In IntelliJ IDEA

Checkout in the branches popup; the file form appears as Rollback, with Local History as a safety net.

git switch and git restore are the modern split · git reflog recovers commits made in detached HEAD · git merge for the conflict forms.

Lessons that use this command

Create, switch, rename, delete · HEAD, refs, origin, upstream · Reading conflict markers.

Key terms

Branch HEAD Detached HEAD Restore

Related