git symbolic-ref: Usage, Options & Common CI Errors

git symbolic-ref reads or updates symbolic references such as HEAD or refs/remotes/origin/HEAD.

symbolic-ref is the reliable way to discover the current branch or a remote’s default branch in scripts.

What it does

git symbolic-ref reads the target of a symbolic ref (e.g. HEAD points to refs/heads/main) or sets one. It is how you reliably query the current branch or origin’s default branch.

Common usage

Terminal

git symbolic-ref HEAD                 # refs/heads/main
git symbolic-ref --short HEAD         # main
git symbolic-ref refs/remotes/origin/HEAD   # origin's default
git symbolic-ref HEAD refs/heads/main # repoint HEAD

Options

Flag	What it does
--short	Strip the refs/heads/ prefix
-d / --delete	Delete a symbolic ref
-q / --quiet	No error if the ref is not symbolic
<name> <ref>	Point a symbolic ref at a target

Common errors in CI

fatal: ref HEAD is not a symbolic ref - HEAD is detached (pointing at a SHA, common in CI). Use git rev-parse HEAD for the SHA instead. To find origin’s default branch when origin/HEAD is unset, run git remote set-head origin -a first.

Related guides

git rev-parse: Usage, Options & Common CI Errorsgit rev-parse resolves refs to SHAs and reports repo paths - core CI plumbing. Reference for --short, --abbre… 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 switch: Usage, Options & Common CI Errorsgit switch changes branches with a focused, modern interface. Reference for -c, --detach, --track, and the er… git remote: Usage, Options & Common CI Errorsgit remote manages the named connections to remote repositories. Reference for add, set-url, -v, remove, and…