Hotfix interruption
You're partway through a feature when an urgent fix comes in. You create a branch with git switch -c hotfix main, fix the bug, and return to the feature with git switch -.
Git · Command
git switch
git switch moves you onto a different branch. It can also create a branch, reset one, detach HEAD at a commit, or start an orphan branch as part of the same command.
Last updated
- Since
- 2.23.0
How it works
When you run git switch <branch>, Git points HEAD at that branch. It then rewrites the index and working tree so they match the branch's tip, and every commit you make after that goes on top of the branch. You can add flags to create a branch first (-c), reset an existing one (-C), or land on a bare commit with no branch (--detach). Unlike git checkout, switch never restores individual files and only changes branches. If the switch would overwrite your uncommitted work, Git stops unless you tell it to throw that work away or carry it along.
Syntax
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>Parameters
| Name | Type | Description |
|---|---|---|
<branch> | branch name | The existing branch to move to. Use - for the previous branch, or @{-N} for the Nth-last branch or commit you switched to. |
<new-branch> | branch name | The name to give the branch created by -c, -C or --orphan. |
<start-point> | commit-ish | Where the new branch (or detached HEAD) begins. It defaults to the current HEAD. You can write A...B to mean their single merge base. |
-c, --create | flag | Create <new-branch> at <start-point> and then switch to it. |
-C, --force-create | flag | Same as -c, but if the branch already exists it is reset to <start-point>. |
-d, --detach | flag | Switch to a commit without being on any branch. |
--guess / --no-guess | flag | Turns on or off creating a tracking branch automatically from a remote branch with the same name. It is on by default, and the checkout.guess setting can change that. |
-f, --discard-changes | flag | Switch even when you have local changes, and throw those changes away. |
-m, --merge | flag | Stash conflicting local changes automatically and reapply them after the switch. |
--conflict=<style> | merge | diff3 | zdiff3 | Works like --merge but sets how conflict hunks are shown. |
-t, --track[=(direct|inherit)] / --no-track | flag | Turns upstream configuration for the new branch on or off. -t implies -c. |
--orphan | flag | Create a new branch that has no commits yet. |
Key points
- You can switch with uncommitted changes in place. Git only refuses when the switch would destroy some of those changes.
- -c works like running git branch and then git switch as one all-or-nothing step. If the switch fails, for example because another worktree is using the branch, no branch is created or reset.
- -C is the force version of -c. If the branch name already exists, Git moves that branch to the start point.
- If you name a branch that doesn't exist locally but exists on exactly one remote, Git creates a local tracking branch for it automatically. If several remotes have it, the checkout.defaultRemote setting decides which one wins.
- git switch - takes you back to the branch you were on before, which is the same as @{-1}.
- --detach lets you check out any commit or tag to look around or experiment without moving a branch. If the work turns out useful, you can keep it later with git switch -c.
- -m keeps your uncommitted work: Git stashes the edits that conflict, switches, and then applies them again on the new branch.
Common mistakes
- -f is a short alias for --discard-changes, so it silently deletes your uncommitted edits in both the index and the working tree.
- With -m, reapplying your changes can still produce conflicts. When that happens the stash entry is kept, and you have to resolve the conflicts and drop the stash yourself.
- --orphan clears out all tracked files, so the working tree starts empty on the new branch.
- Submodules stay where they are unless you ask for --recurse-submodules, so after a switch they can point at the wrong commits.
Example: Everyday branch hopping
# Start a feature branch from main
git switch -c feature/login main
# Carry uncommitted edits to another branch
git switch -m hotfix
# Jump back to the previous branch
git switch -
# Inspect an old commit without a branch
git switch --detach HEAD~3
# Keep experimental work done while detached
git switch -c spike/idea
# Track a remote branch (auto-guessed from origin)
git switch new-topicThese commands show the common ways to use git switch: creating a branch, carrying local edits, jumping back, detaching HEAD, keeping detached work, and tracking a remote branch automatically.
When to use it
Reviewing a teammate's branch
After git fetch, running git switch their-topic creates a local branch that tracks origin/their-topic, so you don't need to type any --track options.
Bisect-style inspection
To check whether an old release had a bug, you run git switch --detach v1.2.0 and build or test it without moving any branch.
Separate history for docs
git switch --orphan gh-pages starts an empty branch with no shared history, for example to hold generated site files.
Interview questions
QWhy was git switch introduced when git checkout already exists?
git checkout does two unrelated jobs: it changes branches and it restores files, so a slip in its arguments can overwrite your work. git switch only changes branches, and git restore handles files. That split makes it clearer what each command is meant to do and harder to destroy changes by accident.
Follow-up: What is the git switch equivalent of git checkout -b feature origin/main? Answer: git switch -c feature origin/main. Depending on branch.autoSetupMerge, it may also set up upstream tracking to origin/main.
QWhat happens if you run git switch while you have uncommitted changes?
Git switches and keeps your changes as long as none of the files you edited differ between the two branches. If a file does differ, Git refuses and reports that you have local changes. You can then use -m to stash the conflicting edits and reapply them after the switch, or -f/--discard-changes to throw them away.
Follow-up: After git switch -m reports conflicts, how do you clean up? Answer: the stash entry is kept, so you resolve the conflicts and then run git stash drop. Alternatively, reset the working tree and run git stash pop later.
QHow does git switch -c differ from git switch -C?
-c creates a new branch and fails if that name already exists. -C creates it, or if it already exists, resets it to the start point, which is the same as git branch -f followed by git switch. Both are transactional, so nothing changes if the switch itself fails.
Follow-up: Why can git switch refuse a branch even though it exists? Answer: another worktree may already have it checked out. You can override that with --ignore-other-worktrees, which lets more than one worktree hold the same branch.
Related
git checkoutgit branchgit restoregit stashgit worktreegit mergegit config