Git Checkout

Updated October 3, 20262 min read

In short

git checkout switches to another branch or commit, or restores files to an earlier version; newer Git splits these jobs into git switch and git restore.

What does git checkout do?

For years, git checkout did two quite different jobs. git checkout feature switches branches: it updates HEAD and replaces the files in your working directory with that branch's version. git checkout -b new-branch creates a branch and switches to it in one step. And git checkout -- file.txt throws away your uncommitted changes to a file, restoring it from the last commit.

Because one command both moved between branches and overwrote files, it was easy to lose work by mistake. Git 2.23, released in 2019, introduced two focused commands: git switch for changing branches, with git switch -c to create one, and git restore for restoring files, with --staged to unstage them. git checkout still works, but the new commands are recommended.

Checking out a specific commit or tag, such as git checkout v2.1.0, puts the repository in a detached HEAD state, which is useful for inspecting old code or building a release. Git refuses to switch branches if uncommitted changes would be overwritten; you can commit them, stash them, or carry them along when they don't conflict.

A common misconception is that checkout downloads anything. It works only with what is already in your local repository; to get new branches from a server, run git fetch first. Also note that restoring a file discards uncommitted changes permanently, since Git never saved them.

Key takeaways

git checkout switches branches or restores files.
git checkout -b creates a branch and switches to it.
Git 2.23 split it into git switch and git restore.
Checking out a commit or tag gives a detached HEAD.
Restoring a file discards uncommitted changes for good.

Example

The old and the new commandsbash

# Switch branches
git checkout feature        →  git switch feature
git checkout -b fix-login   →  git switch -c fix-login

# Discard uncommitted changes to a file
git checkout -- app.js      →  git restore app.js

# Unstage a file but keep the changes
git reset HEAD app.js       →  git restore --staged app.js

# Look at an old release (detached HEAD)
git switch --detach v2.1.0

Readers ask

What is the difference between git checkout and git switch?

git switch only changes branches, while git checkout can also restore files. git switch, added in Git 2.23, is clearer and safer for everyday branch changes.

How do I create a new branch and switch to it?

Use git switch -c branch-name, or the older git checkout -b branch-name. Both create the branch at the current commit and switch to it.

Why does Git refuse to check out another branch?

Because you have uncommitted changes that would be overwritten by the other branch's files. Commit them, stash them with git stash, or discard them first.