Git Reference ยท Branches and Tags
git for-each-ref command
Reference for git for-each-ref: list refs with --format placeholders, sort, count, filter with --merged and --contains, and use it in scripts instead of parsing git branch.
git for-each-ref is the scriptable way to list refs (branches, tags, remote-tracking branches, notes, stashes). Each ref is printed using a format string you supply, so you can pull out exactly the fields you need: names, hashes, dates, authors, upstreams, commit subjects. The porcelain commands git branch and git tag are built on the same machinery and share its --format and --sort syntax.
Prefer it over parsing the output of git branch, which is meant for people and may change.
git for-each-ref # all refs git for-each-ref refs/heads # local branches only git for-each-ref --format='%(refname:short) %(objectname:short)' refs/tags
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
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>...]
| Name | Description |
|---|---|
<pattern>... |
Prefix or glob that refs must match (refs/heads, refs/tags/v*). With none, all refs. |
--format=<fmt> |
Output template. Default is %(objectname) %(objecttype)<TAB>%(refname). |
--sort=<key> |
Sort by a field; prefix - to reverse; repeatable (the last key is the primary one). |
--count=<n> |
Stop after n refs. |
--merged, --no-merged |
Keep refs whose tips are (or are not) reachable from a commit. |
--contains, --no-contains |
Keep refs whose history contains (or lacks) a commit. |
--points-at=<obj> |
Keep refs that point at the object. |
--exclude=<pattern> |
Drop matching refs. |
--shell, --perl, --python, --tcl |
Quote values for use in that language. |
--stdin |
Read the patterns from standard input. |
Common placeholders: %(refname), %(refname:short), %(objectname), %(objectname:short), %(objecttype), %(subject), %(body), %(authorname), %(authordate), %(committerdate:iso), %(taggername), %(upstream:short), %(upstream:track), %(HEAD), %(symref), %(creatordate), and %(if)...%(then)...%(else)...%(end).
Returns: one line per ref (an empty list prints nothing). Errors: an unknown placeholder fails with "unknown field name".
Usage notes
- Fields about the pointed-at commit (
subject,authorname,committerdate) work for branches and lightweight tags. For annotated tags thetagger*fields andcontentscome from the tag itself; use*authorname-style prefixes (*objectname) to reach the peeled commit. - Sorting by date with
-committerdateshows the most recently touched branch first, which makes it a good "recent branches" command. - Placeholder modifiers such as
:short,:lstrip=2,:rstrip=1,:date=format:%Y-%m-%dand:paddedreshape values without external tools. - Quoting for shells:
--shellmakeseval "$(...)"safe for names with odd characters. - Stdin patterns let you pipe in thousands of patterns without hitting command-line limits.
- Scripts should use this, not
git branch, since its output is stable and parseable;git branch --formataccepts the same atoms. - Performance: with
reftableor packed refs it reads refs once; limiting by pattern avoids loading unneeded ones.--include-root-refsaddsHEADand pseudo-refs likeORIG_HEAD.
Related
git branch,git tag,git show-ref,git rev-parse,git symbolic-ref- Lessons: Refs and HEAD, Branches