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 <reason>] <name> [<ref>]
git symbolic-ref --delete <name>
git symbolic-ref --quiet <name>
git symbolic-ref --short <name>

-m <reason>
    Sets the reflog message when creating or updating a symbolic ref. This message is recorded in the reflog for the target reference.

--delete
    Deletes the specified symbolic reference. The command will fail if the reference is not symbolic.

--quiet
    Suppresses error messages when checking if a ref is symbolic. Returns 0 if symbolic, 1 if not symbolic, or 128 if the ref does not exist or other errors occur.

--short
    When reading a symbolic ref, displays the target ref in a shorter, more user-friendly format (e.g., main instead of refs/heads/main).

<name>
    The name of the symbolic reference to operate on (e.g., HEAD, refs/remotes/origin/HEAD). It must be a non-existent ref or an existing symbolic ref for write operations.

<ref>
    The target reference that <name> should point to (e.g., refs/heads/feature-branch). Used when setting a symbolic ref. Must be a valid existing reference.

git symbolic-ref is a low-level command used to read, update, and delete symbolic references in Git. Unlike a direct reference which points directly to a commit hash, a symbolic reference points to another reference. The most common example is HEAD, which typically points to your current branch (e.g., refs/heads/main). This command allows you to inspect what a symbolic ref points to, change its target (e.g., to programmatically switch HEAD to another branch), or remove it entirely. It's crucial for operations that manipulate the repository's state at a foundational level, often utilized by plumbing commands or scripts to manage the active branch or other dynamic pointers within the Git repository.

Directly manipulating HEAD with git symbolic-ref can lead to a 'detached HEAD' state if pointed directly to a commit-ish, or put the repository into an unexpected state if used incorrectly. It's generally safer to use higher-level commands like git checkout or git switch for common branch operations. This command is primarily for scripting and plumbing operations where precise control over Git's internal references is required.

Symbolic references point to other references (e.g., HEAD points to refs/heads/main). Direct references (also known as 'loose' references) point directly to a commit, tree, or blob object's SHA-1 hash (e.g., refs/heads/main points to a specific commit ID). git symbolic-ref only operates on symbolic references, managing their targets.

Beyond manipulating HEAD, git symbolic-ref is used to manage symbolic links for remote tracking branches (e.g., refs/remotes/origin/HEAD typically points to refs/remotes/origin/main). It's also invaluable in custom Git workflows or advanced scripting scenarios where a dynamic, human-readable pointer to another reference is needed within the repository.

The git symbolic-ref command is a fundamental Git plumbing command, integrated into Git's core functionality since its early development. It provides direct access to the mechanism of symbolic references, which are central to how Git manages concepts like the current branch (HEAD) and remote tracking branches. Its design reflects Git's philosophy of providing low-level tools that higher-level 'porcelain' commands are built upon, enabling robust and flexible repository management.

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