git for-each-ref

The duct tape of any ref-related script you'll ever write.

🎯 What & why

Iterates refs and prints fields you choose with a format string. It is the duct tape of every ref-handling script you will ever write - and it replaces the fragile for ref in $(git branch) pattern.

🧠 Mental model

A SELECT statement over refs/: pick atoms with %(...), filter by reachability or pointee, sort by any atom, cap with --count. Quoted, NUL-safe, and aware of peeled tags - everything ad-hoc shell loops get wrong.

🛠️ Synopsis

git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
                 [(--sort=<key>)...] [--format=<format>]
                 [--include-root-refs] [ --stdin | <pattern>... ]
                 [--points-at=<object>]
                 [--merged[=<object>]] [--no-merged[=<object>]]
                 [--contains[=<object>]] [--no-contains[=<object>]]
                 [--exclude=<pattern>...]

🎚️ Switches & options

Flag	What it does
`--format=<fmt>`	Format string with atoms like `%(refname)`, `%(objectname)`, `%(committerdate:iso)`, `%(authoremail)`, `%(upstream:short)`.
`--sort=<key>`	Sort by an atom; prefix with `-` to reverse; repeat for multi-key sort (e.g. `--sort=-committerdate`).
`--count=<n>`	Stop after the first n matches - cheap top-N once paired with `--sort`.
`--contains <commit>`	Only refs whose tip has <commit> as ancestor; `--no-contains` for the inverse.
`--merged[=<commit>]`	Only refs reachable from <commit> (default HEAD); `--no-merged` for unmerged ones.
`--points-at <object>`	Only refs that point directly at <object> (peeled, so it works for tags).
`<pattern>...`	Glob patterns like `refs/heads/` or `refs/tags/v`; without any, all refs are listed.

💡 Use cases

Listing branches sorted by last commit date for stale-branch cleanup.
Generating release notes from tags filtered by --contains a specific commit.
Building dashboards: ref name, last committer email, upstream tracking status, in one pass.
Driving safe shell loops via --shell or NUL-terminated %00 in a custom format.

🧪 Examples

Branches sorted by most recent commit

git for-each-ref --sort=-committerdate --format='%(refname:short) %(committerdate:relative) %(authoremail)' refs/heads/

Top 10 stale branches (oldest first)

git for-each-ref --sort=committerdate --count=10 --format='%(refname:short) %(committerdate:short)' refs/heads/

Tags that contain a given commit

git for-each-ref --contains <sha> --format='%(refname:short)' refs/tags/

Branches not yet merged into main

git for-each-ref --no-merged main --format='%(refname:short)' refs/heads/

🎓 Recommendations

Reach for this before writing any shell loop over git branch or git tag - it is faster, quoting-safe, and supports filters those commands don't.
Use --format='%(refname)%00%(objectname)' (NUL separator) when piping into xargs -0 or other parsers.
Combine --sort=-committerdate with --count=N for cheap leaderboards instead of sorting in shell.

🪤 Common pitfalls

git branch and git tag strip the refs/heads/ and refs/tags/ prefixes; for-each-ref does not unless you ask via %(refname:short).
--contains checks the ref's tip, not full history; for tags that means the tag's peeled commit.
Without a pattern argument it lists every ref including refs/notes/ and refs/remotes/ - usually noise. Always scope it.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.