Appearance
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 -brefuses if the branch exists, but doesn't tell you which ref it conflicts with.git branch -drefuses to delete an unmerged branch, even when you know it's safe.git tag -dsucceeds 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-refOutput:
a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 refs/heads/main
b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0a1 refs/heads/feature/x
c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0a1b2 refs/tags/v1.0.0
d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0a1b2c3 refs/remotes/origin/mainEvery 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 elseUse --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 HEADOutput:
refs/heads/mainCompare 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/mainThis 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 abc1234This 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/experimentDeletes 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 def5678This 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 --stdinMultiple 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/lockA 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
donePerformance notes
| Command | Cost | Notes |
|---|---|---|
git show-ref | O(refs) | Lists all refs; scales to tens of thousands |
git show-ref --hash <ref> | O(1) | Single ref lookup |
git symbolic-ref | O(1) | Reads/writes one file |
git update-ref | O(1) + reflog write | Writes one file + optional reflog entry |
git update-ref --stdin | O(n) batched | Atomic 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
| Condition | What 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 chars | Quote it. Git ref names can contain almost any byte except space, ~, ^, :, \\, ?, *, [, and ASCII control chars |
Concurrent update-ref on the same ref | Last write wins unless you use the old-value guard (compare-and-swap) |
| Updating a ref that doesn't exist | Fails unless you use create mode |
| Detached HEAD | symbolic-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