git switch: Usage, Options & Common CI Errors

git switch is the modern command dedicated to changing branches.

switch handles branch movement only, so it is harder to misuse than checkout. Use restore for files.

What it does

git switch moves HEAD to another branch and updates the working tree. It can create a branch with -c but will not restore files.

Common usage

Terminal

git switch main
git switch -c feature           # create and switch
git switch -                    # back to previous branch
git switch --detach <sha>
git switch -c local origin/remote   # create tracking branch

Options

Flag	What it does
-c <name>	Create a new branch and switch
-C <name>	Create or reset a branch and switch
--detach	Switch to a commit in detached HEAD
--track / -t	Set up upstream tracking
--discard-changes	Throw away local changes when switching

Common errors in CI

fatal: invalid reference: <name> - the branch does not exist locally (common after a shallow/single-branch clone). Fetch it first, or use git switch -c <name> origin/<name>. Like checkout, "your local changes would be overwritten" means commit or stash before switching.

Related guides

git checkout: Usage, Options & Common CI Errorsgit checkout switches branches and restores files. Reference for -b, --detach, and pathspecs, plus the detach… git restore: Usage, Options & Common CI Errorsgit restore discards working-tree changes or unstages files. Reference for --staged, --source, --worktree, an… git branch: Usage, Options & Common CI Errorsgit branch lists, creates, renames, and deletes branches. Reference for -d, -D, -m, --set-upstream-to, and th… git fetch: Usage, Options & Common CI Errorsgit fetch downloads remote objects and refs without touching your working tree. Reference for --depth, --unsh…