Git Course 0%

git switch

Intermediate Git CLI Safe ≈ 5 min

Summary: git switch <branch> moves HEAD to another branch and rewrites the working tree to that branch's snapshot. git switch -c <name> creates a branch and switches to it in one step.

Safe — Git refuses to switch when the move would overwrite uncommitted changes, so nothing is silently lost.

What it does

Writes the new branch into .git/HEAD and updates every file that differs between the two snapshots. Files that exist only on the branch you leave disappear from the folder; files only on the branch you enter appear. Uncommitted changes come along when they do not collide with the switch, and block it when they do.

Why it exists

Before Git 2.23, git checkout did this and discarded file changes, which made a dangerous command look routine. switch does only branch movement, and git restore does only files.

When to use it

  • Moving to another branch to work, review or test.
  • Creating a branch for a new piece of work: -c.
  • Returning to the previous branch: git switch -.
  • Starting a branch from a tag or an old commit: git switch -c <name> <start>.

When not to use it

  • To discard changes in a file: git restore.
  • To look at an old commit without a branch: git switch --detach <commit> says so explicitly, which is better than plain checkout.

Syntax

Form Meaning
git switch <branch> Switch to an existing branch
git switch -c <name> Create at the current commit and switch
git switch -c <name> <start> Create at a commit, branch or tag, and switch
git switch - Back to the previous branch
git switch --detach <commit> Look at a commit without a branch (detached HEAD)
git switch -f <branch> Switch and discard local changes Dangerous

Examples

Terminal
$ git switch -c docs/12-windows-install-steps
Switched to a new branch 'docs/12-windows-install-steps'
Terminal
$ git switch main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.

From a tag:

Terminal
$ git switch -c hotfix/23-region-name v1.2.0
Switched to a new branch 'hotfix/23-region-name'

A typo is refused clearly:

Terminal
$ git switch nope
fatal: invalid reference: nope

And so is a switch that would lose work:

Terminal
$ git switch feature/21-difficulty-filter
error: Your local changes to the following files would be overwritten by checkout:
	README.md
Please commit your changes or stash them before you switch branches.
Aborting

Expected result

HEAD points at the new branch, the working tree matches it, and git status reports the new branch on its first line. No commit is created.

Try it here

The simulator below runs a small model of Git in the page. Nothing here touches a real repository, so try the command, then try it wrong (lesson 2.8 explains it).

The Git state simulator loads here.

Common mistakes

  • Files "disappearing" after a switch. They exist on the other branch; switch back to see them (lesson 6.1).
  • Being blocked by uncommitted work. Commit it, or stash it. That refusal is the safety feature.
  • -f to get past the refusal. It discards the changes it named. Stash instead.
  • Creating a branch while on another feature branch, so it inherits that work. Check git status first.
  • Switching mid-merge or mid-rebase. Git refuses; finish or abort first.

How to undo or recover

git switch - returns you. Switching creates nothing and destroys nothing, so there is normally nothing to undo. If you used -f and lost uncommitted changes, they are gone unless your editor or IntelliJ's Local History still has them.

In VS Code

Click the branch name in the status bar and pick a branch, or + Create new branch…. The Command Palette has Git: Checkout to… and Git: Create Branch….

In IntelliJ IDEA

The branches popup (status bar, bottom right) → select a branch → Checkout. With conflicting local changes IntelliJ offers Smart checkout, which shelves, switches and unshelves.

git branch manages the labels · git restore is the file half of the old checkout · git checkout is the older command that did both · git stash parks work that blocks a switch.

Lessons that use this command

Create, switch, rename, delete · What a branch really is · Lab 3.

Key terms

Branch HEAD Working tree

Related