git-symbolic-ref

Store a reference by a name

$ git symbolic-ref refs/[name] [ref]

$ git symbolic-ref -m "[message]" refs/[name] refs/heads/[branch_name]

$ git symbolic-ref refs/[name]

$ git symbolic-ref [[-d|--delete]] refs/[name]

$ git symbolic-ref [[-q|--quiet]] --short refs/[name]

git symbolic-ref [-m <msg>] [-q] [--short] <name> [<ref>]
git symbolic-ref -d [-q] <name>

-d
    Delete the symbolic ref name instead of reading or creating it.

-m <msg>
    Specify reflog message when updating or creating the symref.

-q
    Quiet mode: suppress errors if ref does not exist (read) or already exists (create).

--short
    When reading, output only the short refname (e.g., main), not fully qualified (refs/heads/main).

<name>
    Name of the symref (e.g., HEAD) to read, set, or delete.

<ref>
    Target refname (e.g., refs/heads/main) for name to point to (write mode only).

The git symbolic-ref command is a low-level plumbing tool for reading, creating, updating, or deleting symbolic references (symrefs) in a Git repository.

Symrefs are special refs that contain the name of another ref rather than a commit object ID (SHA-1). The canonical example is HEAD, which points to refs/heads/main (or another branch). Other examples include CHERRY_PICK_HEAD, REBASE_HEAD, or BISECT_HEAD.

Without the -d option, providing a ref argument sets name to point to it. Omitting ref reads and prints the target of name. The -d flag deletes the symref.

This command writes directly to the .git/<name> file, bypassing higher-level porcelain commands like git branch or git checkout. It supports reflog updates via -m and quiet mode with -q. Use --short for concise output when reading.

Primarily used in scripts or for repository maintenance, not everyday workflows.

Fails if target ref does not exist, is not a ref, or creates a cycle. Operates only on loose refs (not packed). Exit code 1 if name exists but is not a symref; 128 for other errors. Must be run inside a Git repository.

Read HEAD target:
git symbolic-ref HEAD
refs/heads/main

Set HEAD to new branch:
git symbolic-ref HEAD refs/heads/feature

Delete BISECT_HEAD:
git symbolic-ref -d BISECT_HEAD

Short output:
git symbolic-ref --short HEAD
main

Introduced around Git 1.2.0 (2006) as core plumbing for symref handling. Evolved with Git's ref system; stable since early versions for managing HEAD and workflow states like bisect or rebase.

git-update-ref(1), git-branch(1), git-checkout(1), git-reflog(1)