Skip to content

Git Ref Plumbing for DevOps ​

Branches, tags, and HEAD are all references (refs). Porcelain commands like git branch, git tag, and git checkout manipulate them with safety rails. The plumbing commands git symbolic-ref, git update-ref, and git show-ref do the same work without the rails. That makes them essential for CI/CD scripts, hook logic, and automation that needs to touch refs directly.

This guide covers the three ref plumbing commands every DevOps engineer should have in their toolkit.

Why ref plumbing matters in CI ​

Porcelain commands are designed for humans. They print messages, abort on common mistakes, and refuse operations that might lose data. That's good at a terminal. In a script:

  • git checkout -b refuses if the branch exists, but doesn't tell you which ref it conflicts with.
  • git branch -d refuses to delete an unmerged branch, even when you know it's safe.
  • git tag -d succeeds silently or fails silently depending on tag type.
  • None of them output a machine-parseable result by default.

Ref plumbing gives you direct, scriptable control over the ref namespace with predictable exit codes and no decorative output.

git show-ref: List and resolve references ​

git show-ref outputs every ref in the repository with its full SHA. It is the plumbing equivalent of listing .git/refs/ but works with packed refs too.

Basic listing ​

bash
git show-ref

Output:

a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 refs/heads/main
b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0a1 refs/heads/feature/x
c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0a1b2 refs/tags/v1.0.0
d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0a1b2c3 refs/remotes/origin/main

Every line is SHA<tab>refname. No headers, no decoration, no color. Parse it with cut, awk, or any tool.

Verify a ref exists ​

bash
if git show-ref --quiet refs/heads/feature/x; then
    echo "Branch exists"
fi

--quiet exits 0 if the ref exists, 1 if not. No output. No branch listing. Just a boolean.

Pattern matching ​

bash
git show-ref --heads          # Only branches (refs/heads/*)
git show-ref --tags           # Only tags (refs/tags/*)
git show-ref --heads feature  # Branches matching "feature"

Hash check ​

bash
git show-ref --hash refs/heads/main  # Just the SHA, nothing else

Use --hash when you need the SHA for another command and don't want to parse the full line.

git symbolic-ref: Read and write symbolic refs ​

HEAD and some other refs don't point to a commit. They point to another ref. That's a symbolic ref. git symbolic-ref reads and writes these indirections.

Read what HEAD points to ​

bash
git symbolic-ref HEAD

Output:

refs/heads/main

Compare with git rev-parse HEAD which dereferences the symbolic ref and returns the commit SHA. git symbolic-ref returns the ref name, which is what you need when the question is "what branch am I on?"

Detect detached HEAD ​

bash
if ! git symbolic-ref -q HEAD > /dev/null 2>&1; then
    echo "Detached HEAD"
fi

-q suppresses errors. git symbolic-ref exits non-zero when HEAD is detached, because there is no symbolic ref to read. This is the most reliable way to detect detached HEAD in a script.

Update HEAD to a branch ​

bash
git symbolic-ref HEAD refs/heads/main

This is what git checkout main does internally. It updates the symbolic ref without touching the working tree. Use it in hooks or initialization scripts where you know the working tree state is correct.

Safety check: ensure a ref is symbolic ​

bash
git symbolic-ref --short HEAD  # "main" instead of "refs/heads/main"

--short strips the refs/heads/ prefix. Useful for branch display in CI logs.

git update-ref: Update refs safely ​

git update-ref is the atomic primitive for updating any ref. It replaces the entire echo SHA > .git/refs/heads/branch workflow with a safe, logged, transaction-capable operation.

Create or update a branch ​

bash
git update-ref refs/heads/deploy/v2.0.0 abc1234

This sets refs/heads/deploy/v2.0.0 to abc1234. If the ref already exists, it's overwritten. If not, it's created. No porcelain warnings, no interactive prompts.

Delete a ref ​

bash
git update-ref -d refs/heads/old/experiment

Deletes the ref. No "are you sure" prompt. The reflog still records the deletion if reflogs are enabled for that ref.

Conditional update (compare-and-swap) ​

bash
git update-ref refs/heads/main abc1234 def5678

This updates refs/heads/main to abc1234 only if its current value is def5678. If another process changed it in the meantime, the command fails. This is how CI pipelines safely advance deployment branches:

bash
# Only advance the deploy branch if it still points to what we expect
git update-ref refs/heads/production "$NEW_SHA" "$EXPECTED_OLD_SHA" || {
    echo "ERROR: production branch moved unexpectedly"
    exit 1
}

Batch updates with --stdin ​

bash
echo "update refs/heads/stable abc1234 def5678
delete refs/heads/old/candidate
create refs/tags/v3.0.0 abc1234" | git update-ref --stdin

Multiple operations in one call. Each line is update|create|delete <ref> <new-value> [old-value]. The entire batch is atomic. If any operation fails, none apply.

Reflog management ​

bash
git update-ref -m "deploy: promote v2.0.0 to production" \
    refs/heads/production abc1234 def5678

-m sets the reflog message. Without it, the reflog records "update-ref" which is useless for post-mortems. Always set a meaningful message in automation.

Combined patterns for CI ​

Lock deployment branch against concurrent pipelines ​

bash
# Before deployment
if ! git update-ref refs/heads/deploy/lock "$(git rev-parse HEAD)" \
       "$(git rev-parse refs/heads/deploy/lock 2>/dev/null || echo 0000)"; then
    echo "Another pipeline holds the lock"
    exit 1
fi

# After deployment
git update-ref -d refs/heads/deploy/lock

A ref-based mutex. Only one pipeline can hold the lock because update-ref is atomic. No external locking service needed.

Promote a tag to a branch for deployment ​

bash
TAG_SHA=$(git show-ref --hash refs/tags/"$CI_COMMIT_TAG")
git update-ref refs/heads/deploy/candidate "$TAG_SHA"

Extract the SHA from a tag with show-ref, create a deployment branch with update-ref. No checkout needed.

Detect stale refs ​

bash
# List branches that haven't been updated in 90 days
git show-ref --heads | while read -r sha ref; do
    committer_date=$(git log -1 --format=%ct "$sha")
    now=$(date +%s)
    age_days=$(( (now - committer_date) / 86400 ))
    if [ "$age_days" -gt 90 ]; then
        echo "$ref stale for ${age_days} days"
    fi
done

Performance notes ​

CommandCostNotes
git show-refO(refs)Lists all refs; scales to tens of thousands
git show-ref --hash <ref>O(1)Single ref lookup
git symbolic-refO(1)Reads/writes one file
git update-refO(1) + reflog writeWrites one file + optional reflog entry
git update-ref --stdinO(n) batchedAtomic batch, same cost per operation

All ref plumbing commands operate on the ref namespace only. They never touch the working tree, index, or object database. This makes them safe to run in bare repos, in pre-receive hooks, and in CI runners that only need to update refs.

Edge cases ​

ConditionWhat happens
Ref is packed (in .git/packed-refs)show-ref finds it; update-ref unpacks it, updates, then repacks on next git gc
Ref is a symbolic ref (e.g., HEAD)update-ref dereferences it; use symbolic-ref to change the indirection
Ref name contains spaces or special charsQuote it. Git ref names can contain almost any byte except space, ~, ^, :, \\, ?, *, [, and ASCII control chars
Concurrent update-ref on the same refLast write wins unless you use the old-value guard (compare-and-swap)
Updating a ref that doesn't existFails unless you use create mode
Detached HEADsymbolic-ref HEAD fails; update-ref HEAD still works (HEAD is a regular ref when detached)

Quick reference ​

bash
git show-ref [--heads|--tags] [--quiet] [--hash] [pattern]
    # List refs matching pattern, or all refs

git symbolic-ref [-q] [--short] <name>
    # Read a symbolic ref

git symbolic-ref <name> <ref>
    # Set a symbolic ref

git update-ref [--stdin] [-m <msg>] <ref> <new-value> [<old-value>]
    # Create, update, or conditional-update a ref

git update-ref -d <ref> [<old-value>]
    # Delete a ref, optionally conditional on current value

Git Master — Git Reference for Every Skill Level