git symbolic-ref

How HEAD points at a branch instead of a SHA.

🎯 What & why

git symbolic-ref reads or writes refs that point at other refs instead of at a SHA. The canonical example is HEAD, which usually points at refs/heads/<current-branch> rather than directly at a commit.

🧠 Mental model

A symbolic ref is a one-line file containing ref: refs/.... Reading resolves one hop; writing replaces the target. This is exactly how git switch <branch> re-aims HEAD without moving any commit.

🛠️ Synopsis

git symbolic-ref [-m <reason>] <name> <ref>     # write
git symbolic-ref [-q] [--short] <name>          # read
git symbolic-ref --delete [-q] <name>           # delete

Reads exit non-zero (and may print to stderr) if <name> is not symbolic.

🎚️ Switches & options

Flag	What it does
`--short`	Strip `refs/heads/` from the read result -- e.g. `main` instead of `refs/heads/main`.
`-d, --delete`	⚠️ Remove the symbolic ref entirely (HEAD-less repo if you delete HEAD).
`-q, --quiet`	Suppress error output when <name> is not symbolic; rely on exit code.
`-m <reason>`	Reflog message recorded with the update -- HEAD's reflog is the audit trail.

💡 Use cases

Detect the current branch in scripts: git symbolic-ref --short HEAD.
Move HEAD to a different branch without checking out any files.
Repoint refs/remotes/origin/HEAD after the upstream default branch is renamed.
Distinguish detached-HEAD state (read fails) from on-a-branch state (read succeeds).

🧪 Examples

Read current branch (short form)

git symbolic-ref --short HEAD

Re-point HEAD to a feature branch

git symbolic-ref HEAD refs/heads/feature

Update origin's default branch ref

git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

Reflog-friendly write

git symbolic-ref -m 'switch to release' HEAD refs/heads/release

🎓 Recommendations

Prefer git symbolic-ref --short HEAD over parsing git branch --show-current in legacy scripts.
Use -q plus exit-code checks to handle detached HEAD gracefully.
Pass -m whenever you write HEAD so the reflog records why.

🪤 Common pitfalls

Pointing HEAD at a non-existent ref leaves the repo in an unborn-branch state.
Reading a non-symbolic ref (e.g. detached HEAD) is an error, not an empty result -- always check the exit code.
Deleting HEAD turns the repo into something most porcelain refuses to touch -- only do it intentionally.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.