Switching & Checkout

The historical checkout problem

For most of Git's life, git checkout was the Swiss Army knife for moving things around. It switched branches, created branches, detached HEAD, restored individual files from history, threw away uncommitted edits, and a few other things besides. The argument that followed git checkout changed the meaning of the command entirely, and beginners learned the hard way that git checkout main and git checkout main.py were doing different jobs.

In August 2019, Git 2.23 introduced two new commands designed to split that responsibility. The release notes describe the goal directly: to clearly separate the responsibilities of git checkout into two narrower categories: operations which change branches and operations which change files.

• git switch handles branches and HEAD movement.
• git restore handles file contents in the working tree and index.

Both were marked experimental at introduction and have been stable for years now. git checkout still exists and is not going anywhere. You should write new commands with switch and restore, but you should also be able to read checkout in tutorials, scripts, and your own muscle memory without flinching.

Switching branches with git switch

The base form does exactly what its name says.

git switch feature-login

HEAD moves to point at the named branch. The working tree and index are updated so the files on disk match the snapshot at the tip of that branch. Files that are identical in both branches are left alone, which is why switching is usually fast and unobtrusive.

There is a small but useful shortcut: - means "the previous branch," in the same spirit as cd - in a shell.

git switch -

Use it when you are bouncing between a feature branch and the main line to compare behavior or rerun tests.

Refusing to clobber your work

If switching would overwrite local changes you have not committed, Git refuses up front rather than losing them. The message looks like this:

$ git switch main
error: Your local changes to the following files would be overwritten by checkout:
        src/login.js
Please commit your changes or stash them before you switch branches.
Aborting

You have three reasonable responses, in order of preference:

• Commit the changes, even as a scratch commit on the current branch you can clean up later.
• Stash them with git stash if they are not ready to commit but you want to come back to them.
• Discard them with git switch --discard-changes <branch> if you genuinely do not want them.

If the changes touch files that do not differ between the two branches, Git happily carries them across with you. That is the case nine times out of ten: you are working on a single feature, you want to peek at another branch for a moment, and your work-in-progress travels along.

Creating branches as you switch

The -c flag (for create) starts a new branch from the current commit and switches to it in one step. This is the everyday "start a new feature" command.

git switch -c add-search-bar

You can give a starting point explicitly, in which case the new branch begins at that commit, branch, or tag instead of the current HEAD.

git switch -c hotfix-1.4.1 v1.4.0
git switch -c review-pr-273 origin/feature/payments

The first creates a hotfix branch starting at the v1.4.0 tag. The second creates a local branch tracking a colleague's remote branch, which is how you typically review someone else's pull request locally.

What happens to the working tree

It helps to be exact about what changes when you switch. Git compares the snapshot at the tip of the target branch with the snapshot at HEAD and updates only the files that differ. Unchanged files are not touched on disk at all, which matters for build caches, editor state, and large repositories.

This is the model that justifies the previous section's three options. Commit, stash, or discard is the menu because those are the three ways to clear the conflict that triggered the refusal.

Detached HEAD

Normally HEAD points at a branch, and the branch points at a commit. Move HEAD by switching branches, and the branch label travels along when you commit. There is a second mode where HEAD points directly at a commit, with no branch in between. Git calls this a detached HEAD.

You enter detached HEAD on purpose with --detach, or accidentally by passing a commit identifier to the older git checkout command:

git switch --detach 9f4e21d
# legacy form, still common:
git checkout 9f4e21d

This is genuinely useful. You can check out a tagged release, an old commit, or someone else's pinned reference, build the project, and poke around without disturbing any branch. Reading old states is what detached HEAD is for.

The escape route is one command:

git switch -c rescue-experiment

That creates a real branch at the current commit and switches to it. Your detached commits now have a name attached. From there you can keep going, merge them back, or delete the branch if you decide the experiment was not worth keeping.

If you only wanted to look around and made no commits, leaving is easy: just git switch <branch> to any normal branch and HEAD reattaches.

Restoring files from another ref

Switching moves your whole HEAD. Sometimes you do not want that. You want one file the way it looked at a particular commit, or you want to undo your unstaged edits to one file. That is what git restore is for.

git restore --source main --staged --worktree src/config.js

That command says: take src/config.js as it exists at main, put it in the index, and put it in the working tree. Your HEAD does not move. No branch is touched. You have just one file overwritten with another version.

The flags say which copy you want to change.

The default source for --staged is HEAD, and the default for a bare git restore with no --source is the index. That asymmetry exists because the two most common jobs are "throw away my unstaged edits to this file" and "unstage this file."

Translating old checkout commands

You will read git checkout in old tutorials, blog posts, accepted Stack Overflow answers, and your own shell history forever. Here is the translation table so you can match what you see to what you would write today.

You do not have to migrate. The old forms still work and will keep working. The benefit of the new forms is that the command name tells you, before you read the arguments, whether you are about to move HEAD or to overwrite files.

Common pitfalls

Worked examples

git switch main
git pull
git switch -c add-search-bar

git switch main
# error: Your local changes to the following files would be overwritten by checkout:
#         src/login.js
git stash push -m "wip login button"
git switch main
# ... look around ...
git switch -
git stash pop

git switch --detach v1.4.0
# build, run, observe...
git switch -c hotfix-1.4.1

git restore --source main --staged --worktree src/config.js
git status