Git for-each-ref builds reports from local references and the objects they point to. It can list branch identities, inspect tag metadata, or generate a narrowly scoped release inventory. Its formatting and sorting controls are more useful than scraping a human-oriented branch listing.
The important word is local. A report describes the repository’s current reference state, including whatever remote-tracking refs were last fetched. It does not automatically contact a server, prove release approval, or tell you which branches are safe to delete.
Define the report population first
Choose the reference namespace the report should cover. Local branches live under refs/heads, tags under refs/tags, and remote-tracking references under refs/remotes. These namespaces represent different kinds of state.
A local branch and a remote-tracking branch with similar names can point to different objects. Include the full reference name so consumers do not collapse them into one label. Human-friendly shortened names can be added as display fields, but should not replace the authoritative identity.
Confirm repository context before collecting evidence. Running the same command in a different checkout can produce a valid-looking report about the wrong project. Record the repository identity and observation time alongside any output used operationally.
Git for-each-ref supports explicit output fields
A simple local branch report can use a tab-separated format:
git for-each-ref \
--sort=refname \
--format='%(refname)%09%(objectname)%09%(objecttype)' \
refs/headsThe example selects full ref names, full object identifiers, and object types. %09 inserts a tab. It performs an inspection rather than a checkout, fetch, or reference update.
Keep the format string application-controlled. Do not accept arbitrary format expressions from a less trusted caller merely because the command is read-only. Some fields can expose personal metadata, commit messages, or information outside the caller’s intended report scope.
Preserve full object IDs as strings. Avoid a fixed-length assumption tied to one hash algorithm, and do not substitute a short display prefix when machine comparison requires exact identity.
Sorting needs an explicit interpretation
Without an explicit sort key, reference-name ordering is the default. Numeric fields and date fields have documented numeric ordering, while other fields generally use byte-value ordering. A textual release label therefore needs a deliberate version-ordering policy.
When several sort options are supplied, the last key becomes the primary key. This is easy to reverse accidentally when building a command programmatically. Include a tie-breaker when the chosen primary field can repeat, and test the expected order with representative fixtures.
Formatted date strings can alter sorting semantics when included in sort keys. A display-oriented date format is not necessarily chronological text order. Keep raw timestamp ordering separate from the representation shown to readers.
A limit such as --count reduces output after the command’s ordering decisions. It does not prove that omitted references are unimportant or that the first few are approved releases. Explain the scope and selection rule in the report.
Annotated and lightweight tags differ
An annotated tag points to a tag object, while a lightweight tag directly names its target. The same field can therefore describe different objects depending on the tag’s kind.
Fields prefixed with * can inspect the peeled target where applicable. Use those fields deliberately when a report needs the commit behind an annotated tag. Retain the tag object’s identity as well when the tag’s own metadata or signature matters.
Do not label every tagger date as a commit date, or every author field as a release approver. Annotated-tag metadata and commit metadata answer different questions. A reliable release inventory makes these distinctions visible rather than presenting one ambiguous “date” column.
Tests should include both tag kinds and a tag targeting a non-commit object if your repository permits that. A report built only around one happy-path annotated commit tag may misclassify legitimate edge cases.
Containment is not integration approval
The command supports filters that ask whether references contain a commit or are merged relative to a chosen object. These are useful graph questions. They do not certify that the corresponding work is approved, deployed, or safe to delete.
Resolve the comparison object deliberately and record its identity. If a mutable branch moves between reports, the result can change without any change to the candidate reference. Use a captured object ID when a stable comparison is required.
Before branch cleanup, review worktree use, collaboration state, remote policy, and recovery options separately. A merged filter can support a cleanup decision, but should not be turned directly into a destructive loop without review.
Treat reference metadata as untrusted data
Commit subjects, author names, and tag messages can contain characters meaningful to a shell, terminal, or export format. The command provides host-language quoting options, but a report usually does not need to execute generated scriptlets at all.
Prefer parsing data with explicit field boundaries. If free-form messages are included, use a delimiter strategy that handles their possible line breaks and tabs. Restrict fields when a simple report only needs names and IDs.
Escape output for its destination. A web dashboard needs HTML-safe rendering; a spreadsheet export may need protection against formula interpretation. A terminal display may need control-character handling. Git metadata does not become trusted because Git printed it.
Explain freshness and incomplete views
Remote-tracking references can be stale or absent because of fetch configuration. A local report may intentionally exclude some branches, tags, or namespaces. State these limitations when using the report to make operational decisions.
If the task requires current server advertisement, use a remote inspection workflow and compare it with local state. If it requires object verification, inspect and verify the actual objects. Do not infer either property from a neatly formatted local inventory.
Keep an observation timestamp and the command configuration with saved reports. These details make later comparisons meaningful and help explain why a branch appeared in one inventory but not another.
Frequently asked questions
Does the command fetch new references?
No. It reports local references. Refreshing remote state requires a separate authorized fetch or remote query.
Can it produce a release approval list?
It can provide input to that list. Approval rules and signature or provenance checks must be applied separately and tied to exact object identities.
Is formatted output safe to evaluate?
Do not evaluate it just to parse a report. Prefer data-oriented formats and destination-specific escaping, especially when metadata can be influenced by other contributors.
Practical takeaway
Choose the namespace, fields, sort order, and observation context explicitly. Preserve tag-kind differences and parse output as data. A good ref report supplies precise evidence while leaving freshness, trust, and destructive decisions visible.
Documentation and related reading
Check the official documentation for the exact behavior of your deployed version. For complementary implementation guidance, read the Git ls-remote guide.
Continue with the Git Guides for a broader practical reading path.
