git switch vs git checkout: Differences, Equivalent Commands, Detached HEAD, Remote Branches and Common Errors (Tested Examples)

git switch and git checkout both move you to another branch, but git switch does only that, while git checkout also restores files. Git 2.23 split checkout into git switch for branches and git restore for files. Use git switch dev to change branch, git switch -c new to create one (same as checkout -b), and git restore file to discard file changes. git switch is safer: a typo gives a clear error, and it refuses to detach HEAD unless you add --detach.

git checkout is not deprecated and still works in every script and tutorial, so you need to read both. Below, every command was run in a fresh repository with Git 2.47.3. I ran the script twice and got identical output both times.

In this guide:

• The short answer: which one to use
• 1. Switching to an existing branch
• 2. Creating a new branch: switch -c vs checkout -b
• 3. A typo in the branch name
• 4. When a file and a branch have the same name
• 5. Checking out a remote branch
• 6. Detached HEAD: switch needs --detach
• 7. Uncommitted changes that block the switch
• 8. Orphan branches and the previous branch
• Common errors and what they mean
• Frequently asked questions

The short answer: which one to use

For new habits, use git switch for branches and git restore for files. Keep git checkout for older Git versions (before 2.23) and when you follow older instructions. The file side is covered in my post on git reset vs revert vs restore.

1. Switching to an existing branch

$ git switch dev
Switched to branch 'dev'

$ git checkout main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.

For a plain branch name, the two commands do exactly the same thing. They update HEAD, the index and your working files to match the branch, and keep uncommitted changes that do not conflict.

2. Creating a new branch: switch -c vs checkout -b

$ git switch -c feature/login
Switched to a new branch 'feature/login'

$ git switch main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.

$ git checkout -b feature/signup
Switched to a new branch 'feature/signup'

$ git switch main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.

-c stands for create. Both forms accept a start point, for example git switch -c hotfix origin/main. If the branch name already exists, both refuse:

$ git switch -c dev
fatal: a branch named 'dev' already exists

$ git checkout -b dev
fatal: a branch named 'dev' already exists

$ git switch -C dev
Switched to and reset branch 'dev'

-C (and checkout -B) force-creates: it resets the existing dev to the current commit, which can drop commits from dev. Use it only when that is what you want.

3. A typo in the branch name

$ git switch fetaure/login
fatal: invalid reference: fetaure/login

$ git checkout fetaure/login
error: pathspec 'fetaure/login' did not match any file(s) known to git

This is where git switch is clearly better. It knows you meant a branch, so it says the reference is invalid. git checkout falls back to treating the name as a file path and prints a confusing pathspec error with a different exit code. Run git branch -a to see the real names. More small developer helpers are on my free tools page.

4. When a file and a branch have the same name

In this repository, main has a committed file called dev, the file has local edits, and there is also a branch called dev:

$ git checkout dev
error: Your local changes to the following files would be overwritten by checkout:
	dev
Please commit your changes or stash them before you switch branches.
Aborting

$ git status --short
 M dev

$ git checkout -- dev

$ git status --short

git checkout dev guessed that you meant the branch, and it refused because switching would overwrite the edited file. With --, everything after it is a path, so git checkout -- dev restored the file and threw away the edit without asking. That silent discard is the main reason git restore exists. git switch never touches files this way, so there is no ambiguity.

5. Checking out a remote branch

$ git branch -a
  dev
  feature/login
  feature/signup
* main
  remotes/origin/main
  remotes/origin/remote-only

$ git switch remote-only
Switched to a new branch 'remote-only'
branch 'remote-only' set up to track 'origin/remote-only'.

$ git branch -vv
  dev            e48a232 B
  feature/login  e48a232 B
  feature/signup e48a232 B
  main           5198abf [origin/main: ahead 1] add file named dev
* remote-only    447b2f5 [origin/remote-only] R

$ git switch main
Switched to branch 'main'
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

The branch remote-only existed only on origin. Because exactly one remote had a branch with that name, git switch remote-only created a local branch that tracks it. git checkout remote-only does the same guess. If you have two remotes with that branch, use git switch -c remote-only --track origin/remote-only. Run git fetch first if the remote branch is new.

6. Detached HEAD: switch needs --detach

$ git switch HEAD~1
fatal: a branch is expected, got commit 'HEAD~1'
hint: If you want to detach HEAD at the commit, try again with the --detach option.

$ git switch --detach HEAD~1
HEAD is now at e48a232 B

$ git status
HEAD detached at e48a232
nothing to commit, working tree clean

$ git switch -
Previous HEAD position was e48a232 B
Switched to branch 'main'
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

git switch only accepts branch names unless you pass --detach, so you cannot detach HEAD by accident. git checkout detaches silently and then prints a long warning:

$ git checkout HEAD~1
Note: switching to 'HEAD~1'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at e48a232 B

Notice that even git checkout's own advice now recommends git switch -c and git switch -. If you commit in detached HEAD, create a branch before you leave, or find the commits later with git reflog.

7. Uncommitted changes that block the switch

$ git switch dev
error: Your local changes to the following files would be overwritten by checkout:
	app.txt
Please commit your changes or stash them before you switch branches.
Aborting

$ git switch --merge dev
Switched to branch 'dev'
M	app.txt

$ git status --short
UU app.txt

Both commands refuse when your edits would be overwritten. Your options are: commit, stash (see git stash pop vs apply), carry the edits over with --merge, or throw them away. --merge does a three-way merge and can leave a conflict, shown here as UU, that you resolve like any merge conflict.

To throw local edits away and switch in one step, use --discard-changes (the same as checkout -f). Here app.txt had a throwaway edit, and the switch replaced it with the dev version:

$ git switch --discard-changes dev
Switched to branch 'dev'

$ cat app.txt
dev change

8. Orphan branches and the previous branch

$ git switch --orphan gh-pages
Switched to a new branch 'gh-pages'

$ git status --short

$ ls

git switch --orphan creates a branch with no history and an empty working tree, which is handy for a gh-pages branch. git checkout --orphan also creates a branch with no history, but keeps your files staged, so you have to remove them yourself.

$ git switch dev
Switched to branch 'dev'

$ git switch -
Switched to branch 'main'
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

$ git branch --show-current
main

git switch - jumps back to the previous branch, like cd - in a shell. git branch --show-current prints the current branch name, useful in scripts. To clean up old branches afterwards, see how to delete a Git branch locally and remotely.

Common errors and what they mean

• fatal: invalid reference: x from git switch: no branch with that name. Check the spelling, or git fetch first.
• error: pathspec 'x' did not match any file(s) known to git from git checkout: the same problem.
• fatal: a branch is expected, got commit: add --detach or use a branch name.
• fatal: a branch named 'x' already exists: drop -c, or pick another name.
• Your local changes ... would be overwritten: commit, stash, --merge or --discard-changes.
• git: 'switch' is not a git command: your Git is older than 2.23. Upgrade, or use checkout.

The official git switch documentation lists every option.

Frequently asked questions

What is the difference between git switch and git checkout?

git switch only changes branches. git checkout changes branches and also restores files, which is why Git 2.23 added git switch and git restore as clearer replacements.

Is git checkout deprecated?

No. git checkout still works and is widely used in scripts and tutorials. git switch and git restore are simply clearer for everyday work.

What is the git switch equivalent of git checkout -b?

git switch -c branch-name. Use git switch -C to create or reset a branch, like git checkout -B.

How do I switch to a remote branch?

Run git fetch, then git switch branch-name. If exactly one remote has that branch, Git creates a local branch that tracks it.

Why does git switch say a branch is expected, got commit?

git switch only takes branch names. Add --detach to look at a commit, for example git switch --detach HEAD~1.

How do I go back to the previous branch?

git switch - (or git checkout -) returns to the branch you were on before.

Which Git version added git switch?

Git 2.23, released in 2019. Run git --version to check yours.

Last checked: 9 November 2026. Figures, settings and guidance can change, so confirm anything important with the sources linked above.