git switch

Branching & Merging

Switch branches


The 'git switch' command moves you to another branch: HEAD follows it and your working files change to match that branch. With -c it creates the branch first. It was added in Git 2.23 to take over the branch-switching half of git checkout, with clearer names and safer defaults — it refuses to switch when that would overwrite your uncommitted edits.

Synopsis

git switch [<options>] <branch>
git switch [<options>] (-c|-C) <new-branch> [<start-point>]
git switch [<options>] --detach [<start-point>]
git switch [<options>] --orphan <new-branch>
[ ] optional| or<arg> placeholder... repeatable--flag option

Options

Click any option to expand

Beginner (2)

Create a new branch at the current commit (or at a given start point) and switch to it.

RecommendedCreate and switch in one step

Example

git switch -c feature/login

Switch even if it overwrites uncommitted changes; those changes are thrown away.

Not recommendedSilently deletes uncommitted edits; stash them instead

Example

git switch --discard-changes main

Intermediate (2)

Like -c, but if the branch already exists it is reset to the start point.

When neededResets an existing branch — its old commits are dropped

Example

git switch -C feature/login

Switch to a commit instead of a branch (detached HEAD), e.g. to inspect an old version.

When neededInspect an old commit without moving any branch

Example

git switch --detach HEAD~1

Advanced (1)

Create a new branch with no history and remove the tracked files from disk.

When neededSeparate history, e.g. a gh-pages branch

Example

git switch --orphan docs

Choosing the Right Option

switch vs checkout

The same branch actions, old and new

Commandgit checkout equivalent
git switch maingit checkout main
git switch -c feature/logingit checkout -b feature/login
git switch --detach HEAD~1git checkout HEAD~1
git switch -git checkout -

Examples

Switch to a branch

git switch main

Move to main.


Create and switch

git switch -c feature/login

Create feature/login and move to it.


Previous branch

git switch -

Go back to the branch you were on before.


Track a remote branch

git switch feature/login

If only origin/feature/login exists, a local branch tracking it is created.

Workflow Examples

1
git switch main

Start from main

2
git pull

Get the latest main

3
git switch -c feature/login

Create your branch

1
git stash

Park the edits

2
git switch main

Switch

3
git switch - && git stash pop

Come back and restore the edits

Troubleshooting

error: Your local changes to the following files would be overwritten by checkout

Cause: An uncommitted edit conflicts with the other branch

Commit or stash it first, or use --discard-changes to throw it away

fatal: invalid reference: feature/x

Cause: The branch does not exist

Create it with git switch -c, or run git fetch if it exists on origin

fatal: a branch is expected, got commit

Cause: You gave a commit, not a branch

Use git switch --detach <commit>

Tips & Pitfalls

Best Practices

  • ✓Use git switch for branches and git restore for files instead of git checkout.
  • ✓Keep a clean status (commit or stash) before switching.
  • ✓Pull main before creating a new branch from it.

Common Mistakes

  • ✗Switching with uncommitted edits and being surprised they follow you to the new branch.
  • ✗Using git switch <commit> — commits need --detach.
  • ✗Forgetting -c and getting "invalid reference" for a branch that does not exist yet.

FAQ

A:

For branches it does the same job, but with clearer options and it cannot touch files by accident.

A:

Git 2.23 or newer.

A:

They follow you to the new branch, unless they conflict — then the switch is refused.