Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Branches and Tags

git switch command

Reference for git switch: move to a branch, create with -c, force with -C, detach HEAD, track remote branches, and how it differs from git checkout.

git switch changes the branch your working tree is on. It was added in Git 2.23 together with git restore to split the overloaded git checkout in two: switch handles branches, restore handles files. Because it cannot overwrite files by accident, it is the safer command for everyday branch changes.

When you switch, Git updates the index and working tree to match the target branch and moves HEAD. It refuses if uncommitted changes would be lost, unless the same file is identical in both branches.

Terminal
git switch main
git switch -c new-feature
git switch --detach v1.0

Try it

Bash Switch, create and go back

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Dirty tree, detach and start points

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Create a tracking branch from a remote

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git switch [<options>] [--no-guess] <branch>
git switch [<options>] --detach [<start-point>]
git switch [<options>] (-c | -C) <new-branch> [<start-point>]
git switch [<options>] --orphan <new-branch>
Name Description
<branch> Existing branch to switch to. - means the previous branch.
-c, --create Create the branch (at HEAD or the start point) and switch to it.
-C, --force-create Create it, or reset it if it exists.
-d, --detach Detach HEAD at a commit, tag or branch tip.
--orphan Start a new branch with no history and an empty index.
-t, --track Set the upstream when creating from a remote branch.
--no-guess Do not create a tracking branch from a unique remote branch name.
-f, --force Throw away local changes.
-m, --merge Three-way merge local changes into the new branch.
--discard-changes Same as --force for tracked files.

Returns: Switched to branch '<name>' or Switched to a new branch '<name>' (messages go to standard error).

Errors: unknown branch names fail with "invalid reference"; local changes that would be overwritten fail with "Your local changes ... would be overwritten by checkout".

Usage notes

  • No file restoring. git switch does not accept paths; use git restore for files. git switch main file.txt is an error.
  • Branches only. Naming a tag or commit without --detach fails, which prevents accidental detached HEADs.
  • DWIM tracking. If topic does not exist locally but exactly one remote has origin/topic, git switch topic creates a local branch tracking it.
  • git switch - jumps to the previously checked-out branch (like cd -).
  • Uncommitted changes move with you when the target branch has the same version of the touched files. Otherwise commit, stash or use -m.
  • --orphan is for unrelated histories, such as a gh-pages branch.
  • Availability: added in Git 2.23; it covers every branch-related form of git checkout.
  • Submodules are not updated unless --recurse-submodules or submodule.recurse is set.