git-for-each-ref
Iterate and format Git references (branches, tags)
TLDR
List all refs (branches and tags)
List only branches
List only tags
Show branches merged into HEAD
List short names of all refs
Sort refs by committer date (most recent first)
Sort refs by committer date (oldest first)
Limit output to a specified number of refs
SYNOPSIS
git for-each-ref [options] [pattern...]
Commonly used options:
git for-each-ref [--count=n] [--format=format] [--sort=key] [--color[=when]] [--points-at=object] [--merged[=object]] [pattern...]
PARAMETERS
--count=
Limit the number of references output to the first n items after sorting.
--shell | --perl | --python | --tcl
Generate output suitable for shell, Perl, Python, or Tcl scripts by quoting values appropriately.
--points-at=
Show only references that point to the given object (commit, tree, blob, or tag).
--merged[=
Only show references that are merged into the specified object (defaults to HEAD if not provided).
--no-merged[=
Only show references that are not merged into the specified object.
--contains[=
Only show references whose commit (if applicable) contains the specified object.
--no-contains[=
Only show references whose commit (if applicable) does not contain the specified object.
--color[=
Colorize the output. when can be 'always', 'never', or 'auto' (default).
--format=
A string defining the output format for each reference. It uses placeholders (e.g., %(refname), %(objectname)) which are substituted with reference data. See 'Format Placeholders' section for details.
One or more patterns to limit the references shown. Patterns match reference names (e.g., 'refs/heads/*', 'refs/tags/*').
--sort=
A field to sort the output by. Prefix with '-' for descending order (e.g., '-committerdate'). Common keys include 'refname', 'objecttype', 'objectsize', 'committerdate'. See 'Sorting Keys' section for details.
--omit-empty
Do not print a newline for lines where the format expands to an empty string.
--ignore-case
Ignore case when matching patterns.
DESCRIPTION
git-for-each-ref is a versatile Git plumbing command designed to iterate over and display information about Git references (like branches, tags, remote-tracking branches, and stashes). It provides highly customizable output formats, making it invaluable for scripting and generating tailored reports from a Git repository.
Unlike git show-ref which simply lists references, or git log which focuses on commits, git for-each-ref offers granular control over what information about each reference is displayed and how it is formatted. Users can specify a format string using various placeholders to extract details such as the reference name, object ID it points to, type of object, committer/author details for annotated tags or branch tips, and more.
The command also supports powerful filtering options, allowing users to select references based on patterns, whether they are merged into a specific branch, or if they contain a particular commit. Additionally, the output can be sorted by various criteria like creation date, name, or committer date, further enhancing its utility for complex automation tasks and repository analysis.
CAVEATS
Using complex --format strings, especially with nested dereferencing or conditional formatting, can become difficult to read and debug.
When using the command in shell scripts, proper quoting and escaping of the --format string and any embedded newlines or special characters is crucial to avoid parsing issues.
Performance might be affected in extremely large repositories or when sorting by certain object attributes that require extensive object parsing (e.g., objectsize for all refs).
FORMAT PLACEHOLDERS
Key to highly customized output.
The --format option accepts a string with placeholders that expand to specific information about each reference. Some commonly used placeholders include:
- %(refname): The full name of the reference (e.g., "refs/heads/main", "refs/tags/v1.0").
- %(refname:short): The shortened reference name (e.g., "main", "v1.0").
- %(objectname): The SHA-1 or object ID the reference points to.
- %(objecttype): The type of object (commit, tree, blob, tag) the reference points to.
- %(objectsize): The size of the object pointed to by the reference.
- %(committerdate): The committer date of the commit object (for branches) or annotated tag object. Various format options are available, e.g., %(committerdate:relative), %(committerdate:iso).
- %(authorname), %(authoremail), %(committername), %(committeremail): Author/committer details for the associated commit or tag object.
- %(upstream): The name of the upstream branch.
- %(HEAD): Displays '*' if the reference is currently HEAD, otherwise a space.
- %(symref): The symbolic ref that this ref points to, if any.
- %(subject), %(body), %(contents): Contents of the commit or tag message.
SORTING KEYS
Control the order of output.
The --sort option allows sorting the output by various keys. Common keys include:
- refname: Sort by the full reference name (default).
- version:refname: Sort refname in version order (e.g., for tags like v1.0, v2.0, v1.10).
- objecttype: Sort by the type of object the ref points to.
- committerdate: Sort by the committer date of the pointed-to object.
- creatordate: For tags, the tagger date; for branches, the committer date of the commit.
HISTORY
git-for-each-ref has been a staple in Git's plumbing command set since early versions, providing a foundational tool for scripting and automating tasks related to Git references. Its design reflects Git's philosophy of providing low-level, composable commands that can be combined to achieve complex operations. Over time, the command has evolved with the addition of more sophisticated filtering options (like --merged and --contains) and a continuously expanding set of format placeholders, making it increasingly powerful for custom reporting and repository analysis. Its utility has grown significantly as Git repositories have become larger and more complex, demanding more flexible ways to query reference information.
SEE ALSO
git-show-ref(1), git-rev-parse(1), git-log(1), git-branch(1), git-tag(1)
