git switch: moving between branches

git switch <branch> moves you to another branch and rewrites the files in your working directory to match its last commit.

Switching changes what is in the folder. A file created on another branch disappears from the folder after you move away: it is not gone, it sits in that branch's commit, and git shows you the state you are looking at now.

$ git switch feature-x
Switched to branch 'feature-x'

$ git switch main
Switched to branch 'main'

$ git switch -             # go back to the branch you were on before

The -c flag (create) makes a branch and moves onto it in one step. This is the most common form of the command:

$ git switch -c feature-x
Switched to a new branch 'feature-x'

$ git switch -c old-view main   # branch off main instead of the current commit

The new branch starts at the commit you are standing on, unless you name a different starting point.

How it relates to git checkout

In older articles, forum answers and books you will see git checkout feature-x and git checkout -b feature-x. Those do the same thing. git switch arrived in git 2.23 in 2019 to separate two different jobs that one checkout used to do: walking between branches and restoring files from a commit. The second job went to git restore. The old checkout still works and is not going away, but two commands with clear names are easier to keep straight.

What stops a switch

Git will not let you leave if uncommitted edits would be overwritten in the process:

$ git switch draft
error: Your local changes to the following files would be overwritten by checkout:
	report.txt
Please commit your changes or stash them before you switch branches.
Aborting

This is a safeguard, not a failure. You have two ways out: commit the edits, even with a throwaway message, or put them aside for a while with git stash. After that the switch goes through.

If your edits do not touch anything that differs between the branches, git quietly carries them with you onto the new branch. That is convenient right up to the moment you forget where you left them.

Common mistakes

Git does not silently create a branch from a name it does not know; it answers fatal: invalid reference: nope. Check the list with git branch: the name is probably a typo.

git switch -c onto a name already in use fails too: fatal: a branch named 'draft' already exists. If the branch exists, move to it without -c.

Where this is in the book

Chapter 5. Branches: parallel versions of a project works through switching with an example: an urgent fix on the main version while your own rewrite sits half finished.

To practise it by hand, open the Sandbox: a real terminal with git and step checks.