git switch

Switch branches, create with -c, refuse a dirty overwrite, and set up tracking, checked on Git 2.39.5.

コマンドページの本文は現在英語です。

git switch moves HEAD and updates the working tree to the chosen branch or commit. git switch -c <name> creates that branch and switches to it. git branch <name> only creates the name; that difference is the main split between this page and the git branch page.

On Git 2.39.5 the official manual still marks git switch as experimental, so later versions may change details. Examples were checked in isolated temporary repositories. --discard-changes can throw away local edits; this page does not demonstrate it.

Examples were checked against Git 2.39.5. See the official documentation for the complete command.

Git command catalog → · Git tutorial overview →

Create, switch, and detached HEAD

git switch -c topic creates topic at HEAD and checks it out. The example then switches back to main, and the file content is still the main version because topic has no new commit yet.

git switch --detach HEAD leaves you on a commit with no current branch. --show-current prints nothing, and porcelain -b reports "HEAD (no branch)". New commits in that state do not move a branch name. git switch main attaches HEAD to main again.

git switch, git switch -c, git switch --detach

git switch <branch>
git switch -c <new-branch>
git switch --detach <commit>

Move HEAD to a branch, create a branch and switch to it, or detach HEAD at a commit.

ParameterDescription
<branch>An existing branch to check out.
-c <new-branch>Create the branch at HEAD, or at a given start point, and switch to it.
--detach [<commit>]Point HEAD at a commit instead of a branch. The default is HEAD itself.

Returns: HEAD, the index, and the working tree match the chosen branch or commit, unless the switch is rejected.

  • Switch progress messages go to standard error on Git 2.39.5. The example merges them into the output with 2>&1.
bash
git init -b main >/dev/null
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
printf 'base\n' > file.txt
git add file.txt
git commit -m "Add file" >/dev/null
echo "create"
git switch -c topic 2>&1
echo "current=$(git branch --show-current)"
echo "switch-main"
git switch main 2>&1
echo "current=$(git branch --show-current)"
echo "file=$(cat file.txt)"
echo "detach"
git switch --detach HEAD 2>&1
echo "detach-exit=$?"
echo "show-current=$(git branch --show-current)"
echo "abbrev=$(git rev-parse --abbrev-ref HEAD)"
git status --porcelain -b
echo "reattach"
git switch main 2>&1
echo "current=$(git branch --show-current)"

Expected output

create
Switched to a new branch 'topic'
current=topic
switch-main
Switched to branch 'main'
current=main
file=base
detach
HEAD is now at 8bb07df Add file
detach-exit=0
show-current=
abbrev=HEAD
## HEAD (no branch)
reattach
Switched to branch 'main'
current=main

Related: git branch, git status

Official documentation →

Refusing a switch that would overwrite work

git switch does not require a clean working tree in every case, but it aborts when checking out the other branch would overwrite uncommitted edits. In the example, main has a dirty file.txt and topic has a different committed version of that file.

The switch exits 1, prints that local changes would be overwritten, and leaves the dirty file in place. Git mentions stash in that message. Stash is not the only option, and this page does not run stash; inspect the work, then commit it, move it aside, or finish it before you switch.

git switch (dirty worktree)

git switch <branch>

Abort a switch when it would overwrite uncommitted working-tree edits.

Returns: On this failure, HEAD stays on the current branch and the working tree is unchanged.

Exit status

  • 1 — The switch was aborted because local changes would be overwritten. Measured on Git 2.39.5. The error is on standard error; the example captures it with 2>&1.
  • Do not pass --discard-changes just to make the switch succeed. That option throws away the local edits.
bash
git init -b main >/dev/null
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
printf 'base\n' > file.txt
git add file.txt
git commit -m "Add file" >/dev/null
git switch -c topic >/dev/null 2>&1
printf 'topic\n' > file.txt
git add file.txt
GIT_AUTHOR_DATE='2024-01-15T13:00:00+0000' GIT_COMMITTER_DATE='2024-01-15T13:00:00+0000' git commit -m "Edit on topic" >/dev/null
git switch main >/dev/null 2>&1
printf 'main-edit\n' > file.txt
echo "before"
git status --porcelain
echo "switch-topic"
git switch topic 2>&1
echo "switch-dirty-exit=$?"
echo "after"
git status --porcelain

Expected output

before
 M file.txt
switch-topic
error: Your local changes to the following files would be overwritten by checkout:
	file.txt
Please commit your changes or stash them before you switch branches.
Aborting
switch-dirty-exit=1
after
 M file.txt

Official documentation →

Switch and unique remote-tracking branches

If you ask to switch to a name that does not exist locally, git switch --guess (the default) can create a local branch that tracks a unique remote-tracking branch of the same name. The example uses a local bare repository as origin, not a hosting service, and it never pushes tags or signed objects.

In the second clone, only main exists locally. git switch topic creates topic from origin/topic, prints that tracking is set up, and leaves HEAD on topic with upstream origin/topic. If more than one remote had a matching name, guess would not be unique; use --track and an explicit start point in that case.

git switch, --guess, tracking

git switch [<options>] <branch>
git switch --guess <branch>

Create a local branch that tracks a unique remote-tracking branch of the same name.

ParameterDescription
--guess / --no-guessWhen the name is missing locally, try a unique remote-tracking branch of the same name. --guess is the default on Git 2.39.5.

Returns: A new local branch, with its upstream set, and the working tree at that tip.

  • The example runs git push only into a bare repository created in the same temporary directory, so the second clone has origin/topic to guess from.
bash
mkdir repo
cd repo
git init -b main >/dev/null
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
printf 'base\n' > file.txt
git add file.txt
git commit -m "Add file" >/dev/null
git switch -c topic >/dev/null 2>&1
printf 'topic\n' > file.txt
git add file.txt
GIT_AUTHOR_DATE='2024-01-15T13:00:00+0000' GIT_COMMITTER_DATE='2024-01-15T13:00:00+0000' git commit -m "Edit on topic" >/dev/null
git switch main >/dev/null 2>&1
cd ..
git init --bare bare.git >/dev/null
cd repo
git remote add origin ../bare.git
git push -u origin main >/dev/null 2>&1
git push -u origin topic >/dev/null 2>&1
cd ..
git clone bare.git clone >/dev/null 2>&1
cd clone
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
echo "before"
git branch -vv
echo "switch-topic"
git switch topic 2>&1
echo "switch-exit=$?"
echo "after"
git branch -vv
echo "current=$(git branch --show-current)"
echo "upstream=$(git rev-parse --abbrev-ref --symbolic-full-name HEAD@{upstream})"

Expected output

before
* main 8bb07df [origin/main] Add file
switch-topic
Switched to a new branch 'topic'
branch 'topic' set up to track 'origin/topic'.
switch-exit=0
after
  main  8bb07df [origin/main] Add file
* topic a87e73e [origin/topic] Edit on topic
current=topic
upstream=origin/topic

Official documentation →