GIT-SYMBOLIC-REF(1)

💅 GIT-SYMBOLIC-REF(1) 💅

okay bestie, welcome to the Git Manual page for git-symbolic-ref — the little command that reads, modifies and deletes symbolic refs, and honestly it's giving quiet-main-character energy. no cap. 🎀

---

✨ SYNOPSIS ✨

git symbolic-ref [-m <reason>] <name> <ref>
git symbolic-ref [-q] [--short] [--no-recurse] <name>
git symbolic-ref --delete [-q] <name>

---

🌸 DESCRIPTION 🌸

so here's the vibe check 👑:

one argument → it reads which branch head the given symbolic ref refers to and prints out its path, relative to the .git/ directory. and like, the classic move? you pass HEAD as the <name> argument to find out which branch your working tree is on. literally the "where am i" of git 🧭

two arguments → it creates or updates a symbolic ref <name> so it points at the given branch <ref>. slay, you're now pointing at a new thing 💫

--delete plus one more argument → it deletes the given symbolic ref. bye bestie 👋

and what even is a symbolic ref? great question, obsessed that you asked 🫶 — it's a regular file that stores a string starting with ref: refs/. for example, your .git/HEAD is a regular file whose content is:

ref: refs/heads/master

periodt. that's it. that's the whole file. 🍓

---

⭐ OPTIONS ⭐

• -d, --delete — deletes the symbolic ref <name>. gone, deleted, not coming back 💀
• -q, --quiet — don't be loud about it: if <name> isn't a symbolic ref but a detached HEAD, it won't throw an error message at you. instead it just exits with a non-zero status, silently. (the quiet quitting of exit codes 🙈)
• --short — when showing the value of <name> as a symbolic ref, it tries to shorten the value — like from refs/heads/master to just master. cute little glow-down ✨
• --recurse, --no-recurse — when showing the value of <name> as a symbolic ref, if <name> refers to another symbolic ref, it follows that chain of symbolic refs until the result no longer points at a symbolic ref. that's --recurse, and it's the default (she's thorough 💅). --no-recurse stops after dereferencing only a single level of symbolic ref — one hop and we're done 🦋
• -m — updates the reflog for <name> with <reason>. only valid when you're creating or updating a symbolic ref, so don't try it on the read side, bestie 🚫

---

🦋 NOTES 🦋

storytime, gather round 🎀 — in the past, .git/HEAD was a symbolic link pointing at refs/heads/master. when we wanted to switch branches we did:

ln -sf refs/heads/newbranch .git/HEAD

and when we wanted to know which branch we were on, we did:

readlink .git/HEAD

but here's the tea ☕ — symbolic links are not entirely portable, so they are now deprecated, and symbolic refs (like the ones described above) are used by default. rip to the symlink era, she was iconic but problematic 😭

⚠️ exit status check, iykyk: git symbolic-ref exits with status 0 if the contents of the symbolic ref were printed correctly, status 1 if the requested name is not a symbolic ref, or 128 if another error occurs. memorise it, it WILL come up 🔥

---

🌈 SEE ALSO 🌈

• git-update-ref(1) — go read that one too, bestie 🫶

---

🧚 GIT 🧚

part of the git(1) suite. obviously. the whole family is iconic 👑

---

and that's the page!! brought to you by Git 2.56.0, dated 2026-09-27 — mwah, go read a symbolic ref and tell her she's pretty 💜✨