git switch

The "switch" command allows you to switch your current HEAD branch. It's relatively new (added in Git v2.23) and provides a simpler alternative to the classic "checkout" command.

Before "switch" was available, changing branches had to be done with the "checkout" command. The problem with "checkout", however, is that it's a very versatile command: you can not only use it to switch branches, but also to discard changes, restore files, and much more.

The "switch" command provides a simple alternative to "checkout". It has a very clear and limited purpose: switching and creating branches!

Important Options

<branch-name>

The name of a local or remote branch that you want to switch to. If you specify the name of an existing local branch, you will switch to this branch and make it the current "HEAD" branch.
But you can also specify a remote branch: in that case, Git will create a new local branch based on that remote branch and set up a tracking relationship.

-c <new-name>

The name of a new local branch you want to create. Using the "-c" flag, you can specify a name for a new branch that should be created. You can also specify a starting point (either another branch or a concrete revision); if you don't provide any specific starting point, the new branch will be based on the current HEAD branch.

-f / --force / --discard-changes

Switch to the specified branch and discard any local changes to obtain a clean working copy. As a general rule, your working copy does NOT have to be clean before you can use "switch". However, if you have local modifications that would conflict with the switched-to branch, Git would abort the switch. Using --force (or its alias --discard-changes) will discard any uncommitted changes to tracked files and then switch to the specified branch.

-d / --detach

Switch to a specific commit in "detached HEAD" mode. Using -d (or --detach), you can point HEAD at a specific commit without being on any branch. This is useful for inspecting old code or running tests against a specific revision.

-m / --merge

Perform a three-way merge between the current branch, your working tree contents, and the new branch. If you have uncommitted changes that don't conflict with the target branch, -m lets you carry them over without committing or stashing first. If there are merge conflicts, Git will mark them in the affected files for you to resolve manually.

-

Switch back to the previous branch. When specifying just the "-" character instead of a branch name, Git will switch back to the last checked out branch. This can be helpful if you want to often and quickly jump between two branches.

Usage Examples

The most common scenario is to simply specify the local branch you want to switch to:

$ git switch other-branch

This will make the given branch the new HEAD branch. If, in one go, you also want to create a new local branch, you can use the "-c" parameter:

$ git switch -c new-branch

If you want to check out a remote branch (that doesn't yet exist as a local branch in your local repository), you can simply provide the remote branch's name. When Git cannot find the specified name as a local branch, it will assume you want to check out the respective remote branch of that name:

$ git switch remote-branch

This will not only create a local branch, but also set up a "tracking relationship" between the two branches, making sure that pulling and pushing will be as easy as "git pull" and "git push".

If you have local modifications that would conflict with the branch you want to switch to, you can instruct Git to clear your working copy of any local changes (please be careful with this!):

$ git switch --force other-branch

Finally, if you want to switch back to the previously checked out branch, you can simply do this by specifying only the "-" character:

$ git switch -

You can create a branch from a specific starting point — another branch, a tag, or a commit:

$ git switch -c hotfix v2.1.0
$ git switch -c bugfix main
$ git switch -c experiment abc1234

To create a local branch from a remote branch (with tracking set up automatically):

$ git switch -c local-name origin/remote-branch

To switch to a specific commit in detached HEAD mode:

$ git switch -d v2.1.0
$ git switch -d abc1234

To return to a branch afterwards:

$ git switch main

To carry uncommitted changes over to a new branch using a three-way merge:

$ git switch -m feature-branch

Does git switch --force Overwrite Untracked Files?

No. The --force flag (or -f) only discards uncommitted changes to tracked files. It does NOT delete or overwrite untracked files.

If the target branch contains a file that also exists as an untracked file in your working directory, Git will abort the switch — even with --force:

$ git switch --force feature-branch
error: The following untracked working tree files would be
overwritten by checkout:
    config.yaml
Please move or remove them before you switch branches.
Aborting

This is identical to how git checkout -f behaves.

Scenario	What happens with --force
Tracked files with local changes	Changes are discarded
Untracked files that conflict with the target branch	Switch is blocked
Untracked files that don't conflict	Left untouched

How to Resolve "Untracked Working Tree Files Would Be Overwritten"

You have three options:

1. Stash them (safest — preserves the files):

$ git stash push --include-untracked
$ git switch feature-branch
$ git stash pop

2. Delete them (if you don't need them):

$ git clean -fd
$ git switch feature-branch

3. Track them first (commit or add to .gitignore):

$ git add config.yaml
$ git commit -m "Track config"
$ git switch feature-branch

git switch vs git checkout

Both commands can switch branches, but they differ in scope and safety:

	git switch	git checkout
Switch branches	Yes	Yes
Create branches	-c flag	-b flag
Restore files	No (use git restore)	Yes
Detach HEAD	-d flag	Yes (any commit)
Discard changes	--discard-changes	-f flag
Available since	Git 2.23	Always
Scope	Branches only	Branches + files

The key advantage of git switch is clarity: it only handles branch operations, reducing the risk of accidentally overwriting files when you meant to switch branches.

# These two are equivalent:
$ git checkout -b new-feature
$ git switch -c new-feature

# These two are equivalent:
$ git checkout -f other-branch
$ git switch --discard-changes other-branch

Learn More

• Check out the chapter Checking Out a Local Branch in our free online book
• Find the full command description in the Git documentation
• More frequently asked questions about Git & version control