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.
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
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.
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
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 HEADprints the branch name, or nothing when detached, so scripts can test the exit status.git branch --show-currentprints the same name and is easier to read in interactive use. - It only moves the pointer. Writing
HEADdoes not change the index or the working tree. If the new branch has different content,git statuswill show the difference as staged and unstaged changes. Usegit switchfor a normal branch change. - Orphan branches. Pointing
HEADat a branch name that does not exist makes the next commit a root commit on that branch.git switch --orphandoes the same with extra cleanup. - Remote default branch.
refs/remotes/origin/HEADis a symbolic ref naming the remote's default branch.git symbolic-ref refs/remotes/origin/HEADreads it andgit remote set-head origin -arewrites it from the server. - Do not edit
.git/HEADby 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
HEADfile shown above. - Symlinks. Very old Git versions stored
HEADas a symlink on some platforms; current Git always writes theref:text form.
Related
git update-ref,git show-ref,git branch,git switch- Lessons: Refs and HEAD, Branches