Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash Custom formats and sorting

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.

Bash Filtering and conditionals

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

Terminal
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 the tagger* fields and contents come from the tag itself; use *authorname-style prefixes (*objectname) to reach the peeled commit.
  • Sorting by date with -committerdate shows 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-%d and :padded reshape values without external tools.
  • Quoting for shells: --shell makes eval "$(...)" 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 --format accepts the same atoms.
  • Performance: with reftable or packed refs it reads refs once; limiting by pattern avoids loading unneeded ones. --include-root-refs adds HEAD and pseudo-refs like ORIG_HEAD.