Git and GitHubgit 2.54 · GitHub · macOS, Linux or Windows
Dashboard
0%
1
Curious builder0 XP earned · 300 to level 2
0 daysFinish a lesson to begin
Badge collection0 of 6 unlocked
26 small wins to finish your pathNext lesson →

Switching branches

git switch moves you to another branch: it points HEAD at that branch and replaces the files in your working tree with the ones from its commit.

Last updated: 12 Oct, 2026 · git 2.54

Creating a branch leaves you where you are. Switching is the step that makes the branch real: your folder changes to what that branch holds, your next commit lands on it, and the branch you came from is left exactly as it was.

Moving to a branch with git checkout · from the Git and GitHub series · 8:02 to 8:52

Syntax: git switch arrived in Git 2.23 for exactly this job. git checkout still does it and is what you will see in older material.

bash
git switch <name>       # move to an existing branch
git switch -c <name>    # create it and move to it in one step
git switch -            # back to the branch you were on before
git checkout <name>     # the older command, same move
Project files used on this pageThis lesson builds on a project from earlier lessons. The code below imports this file. Click a file to see its code, or follow the link to the lesson that wrote it. To run the code yourself, keep it in the same folder.
View the code here
.gitconfig
[user]
	name = Reader
	email = reader@example.com

Moving between two versions of a file

The clearest way to see what switching does is to read the same file on both sides. The repository below is a throwaway one in a temporary folder, and every example on this page starts from it.

ExampleThe throwaway repository, and the file on main
mkdir ask-docs && cd ask-docs && git init -q -b main
export GIT_AUTHOR_DATE="2026-10-12T10:00:00+00:00" GIT_COMMITTER_DATE="2026-10-12T10:00:00+00:00"
printf 'You are a support assistant.\n' > prompt.txt
printf 'chunk_size = 500\n' > loader.py
git add . && git commit -q -m "Add the prompt and the loader"
cat prompt.txt

That is the prompt as main holds it. The experiment is going to rewrite it.

Creating a branch and committing on it

ExampleOne step to create the branch and move to it
git switch -c shorter-prompt
printf 'Answer in two sentences.\n' > prompt.txt
git commit -q -am "Ask for two sentence answers"
cat prompt.txt
  • Switched to a new branch 'shorter-prompt' is -c doing two things: creating the name and moving you onto it.
  • The file holds the new prompt while you are on the experiment, and the commit you made went to the experiment rather than to main.

Switching back

ExampleThe same file, read on the other branch
git switch main
cat prompt.txt

Switched to branch 'main', and the file holds the old prompt again. Git rewrote it from the commit main points at. Nothing was lost: the other version is safe in the commit on the other branch.

git switch - goes back to where you came from, the way cd - does in a shell. It saves a lot of typing when you are moving between two branches.

Switching with work you have not committed

Git refuses to throw away changes you have not committed. If the file you edited differs between the two branches, the switch is refused and nothing moves.

ExampleA switch that Git refuses
printf 'You are a careful support assistant.\n' > prompt.txt   # edited, not committed
git switch shorter-prompt
printf -- '--- the file is untouched ---\n'
cat prompt.txt
  • error: Your local changes ... would be overwritten by checkout names the file in the way. Git stops before touching anything.
  • Aborting means you are still on main and your edit is still there, which the cat confirms.
  • The fix is to decide what the edit is worth. Commit it on the branch you are on, or throw it away with git restore prompt.txt, or put it aside with git stash, which the undoing part covers.

An edit to a file that is the same on both branches is carried across instead of refused, and git status on the other side still shows it as modified. That is convenient and surprising in equal measure, so run git status before you switch.

Landing on a commit instead of a branch

You can also move to a single commit. Git then has no branch to move forward, a state it calls detached HEAD. It is useful for looking at an old version and dangerous for working in.

ExampleLanding on the previous commit
printf 'chunk_size = 800\n' > loader.py
git commit -q -am "Raise the chunk size to 800"
git switch --detach @~1
git status
  • @~1 means one commit before where you are. HEAD~1 is the same thing written out, and a short identifier from git log --oneline works too.
  • HEAD detached at ... says you are on a commit and not on a branch. The files are the ones from that commit, so this is how you look at an old version of the project.
  • A commit made here belongs to no branch and is easy to lose. If you want to keep work started in this state, make a branch for it with git switch -c <name>.

Getting back to a branch

ExampleOne dash back to where you came from
git switch -

Previous HEAD position was ... names the commit you were standing on, and the line under it says you are on a branch again. git switch - takes you back to the branch you left, whichever one it was.

switch compared with checkout

git checkout does several unrelated jobs, which is why Git 2.23 split it into git switch for branches and git restore for files. Both old and new commands work, and you will meet both.

JobCurrent commandOlder command
Move to a branchgit switch maingit checkout main
Create it and movegit switch -c fixgit checkout -b fix
Move to a commitgit switch --detach <id>git checkout <id>
Throw away an editgit restore <file>git checkout -- <file>
Unstage a filegit restore --staged <file>git reset <file>

Where you switch

  • Starting an experiment. git switch -c chunk-800 creates it and moves you in one line.
  • Comparing two versions by hand. Switch, run the thing, switch back, run it again.
  • Reading an old version. git switch --detach on an old commit, look, then git switch -.
Watch out. Switching does not carry your uncommitted work to the new branch as a feature. It either refuses, or carries the edit across where the file is identical on both sides, which is how an edit meant for the experiment ends up committed on main. Commit or stash before you move, and read the first line of git status after you land.
Try it yourself
  • Switch to a branch, create a file, commit it, switch back and run ls. The file is not there, and it comes back when you switch again.
  • Run git switch nope for a branch that does not exist and read what Git suggests.
  • Edit a file, run git switch -c scratch and then git status. The edit came with you, because the new branch starts from the same commit.
PreviousBranches

Every expert started right here.