Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Branches and Tags

git symbolic-ref command

Reference for git symbolic-ref: read which branch HEAD points to, repoint HEAD safely, detect a detached HEAD and set the default branch of a remote.

git symbolic-ref reads and writes symbolic refs: refs whose content is not a commit id but the name of another ref. The most important one is HEAD, which normally contains ref: refs/heads/main. Following the pointer gives the current branch; when HEAD holds a raw commit id instead, it is detached and symbolic-ref says so.

It is a plumbing command, ideal for scripts. It answers "which branch am I on?" without the formatting of git branch, and it can move HEAD to another branch without touching the index or the working tree, which git switch never does.

Terminal
git symbolic-ref HEAD                  # refs/heads/main
git symbolic-ref --short HEAD          # main
git symbolic-ref HEAD refs/heads/dev   # repoint HEAD, nothing else changes

Try it

Bash Reading and changing HEAD

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Unborn branches and custom symbolic refs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git symbolic-ref [-q] [--short] [--no-recurse] <name>
git symbolic-ref [-m <reason>] <name> <ref>
git symbolic-ref --delete [-q] <name>
Name Description
<name> The symbolic ref to read, write or delete. HEAD is the usual choice.
<ref> When given, <name> is made to point at this full ref name. It must start with refs/.
-q, --quiet When <name> is not symbolic (detached HEAD), exit with status 1 without printing an error.
--short Print main instead of refs/heads/main (uses the shortest unambiguous form).
--no-recurse Do not follow a chain of symbolic refs to the end; show only the next hop.
-m <reason> Text for the reflog entry written when the ref changes.
-d, --delete Delete the symbolic ref itself, not the ref it points to.

Output: the full ref name the symbolic ref points to.

Errors and edge cases: reading a ref that is not symbolic fails with fatal: ref HEAD is not a symbolic ref and exit status 128; with -q the message is hidden and the status is 1. Writing a target outside refs/ is rejected. The target branch does not have to exist, which is how an unborn branch works.

Usage notes

  • Scripting the current branch. git symbolic-ref --short -q HEAD prints the branch name, or nothing when detached, so scripts can test the exit status. git branch --show-current prints the same name and is easier to read in interactive use.
  • It only moves the pointer. Writing HEAD does not change the index or the working tree. If the new branch has different content, git status will show the difference as staged and unstaged changes. Use git switch for a normal branch change.
  • Orphan branches. Pointing HEAD at a branch name that does not exist makes the next commit a root commit on that branch. git switch --orphan does the same with extra cleanup.
  • Remote default branch. refs/remotes/origin/HEAD is a symbolic ref naming the remote's default branch. git symbolic-ref refs/remotes/origin/HEAD reads it and git remote set-head origin -a rewrites it from the server.
  • Do not edit .git/HEAD by hand. The command validates the target and writes a reflog entry; a typo in the file can leave a repository that looks broken.
  • Reftable. Repositories using the reftable ref storage still support all these commands; only the on-disk format differs from the loose HEAD file shown above.
  • Symlinks. Very old Git versions stored HEAD as a symlink on some platforms; current Git always writes the ref: text form.