git switch --detach: Usage, Options & Common CI Errors

git switch --detach moves HEAD onto a commit directly, with no branch attached.

Detaching is exactly what CI does when it builds a specific SHA or tag. Knowing the detached-HEAD model prevents the classic "I committed and lost it" surprise on runners.

What it does

git switch --detach points HEAD at a commit, tag, or remote ref without making it a branch. New commits made here are reachable only from HEAD until you create a branch for them.

Common usage

Terminal

git switch --detach <sha>
git switch --detach v1.2.0
git switch --detach origin/main
# keep work made while detached:
git switch -c rescue

Options

Flag	What it does
--detach	Switch to a commit in detached HEAD
<sha> / <tag> / <ref>	The commit-ish to detach onto
-c <name>	Re-attach by creating a branch here
--discard-changes	Drop local changes when switching

Common errors in CI

fatal: a branch is expected, got commit ‘<sha>’ - plain git switch refuses a commit; add --detach. After detaching, "You are in ‘detached HEAD’ state… commits you make will not belong to any branch" warns that new commits are orphaned; create a branch (git switch -c) before switching away to keep them.

Related guides

git switch: Usage, Options & Common CI Errorsgit switch changes branches with a focused, modern interface. Reference for -c, --detach, --track, and the er… git checkout: Usage, Options & Common CI Errorsgit checkout switches branches and restores files. Reference for -b, --detach, and pathspecs, plus the detach… git reflog: Usage, Options & Common CI Errorsgit reflog records where HEAD and branches have been, so you can recover lost commits. Reference for show, ex… git restore --source: Usage, Options & Common CI Errorsgit restore --source pulls file contents from a specific commit into the working tree. Reference for -s, comb…