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

By Daniel Zoghalchali·Latchkey

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.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

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