What are valid fields for the --format option of git for-each-ref?

Question

I am trying to find the first branch that was created on a repository. To do so I used:

git for-each-ref --sort=commiterdate --format='%(commiterdate:short) %(refname:short)' --count=1 

However I want more information on this branch. I.e how long this branch lived, when was it merged back to the master trunk etc. Is there a list of field options available somewhere? I tried googling a lot but couldn't find anything.

Answer 1

I've found a field list on git repository, file builtin/for-each-ref.c:

} valid_atom[] = {     { "refname" },     { "objecttype" },     { "objectsize", FIELD_ULONG },     { "objectname" },     { "tree" },     { "parent" },     { "numparent", FIELD_ULONG },     { "object" },     { "type" },     { "tag" },     { "author" },     { "authorname" },     { "authoremail" },     { "authordate", FIELD_TIME },     { "committer" },     { "committername" },     { "committeremail" },     { "committerdate", FIELD_TIME },     { "tagger" },     { "taggername" },     { "taggeremail" },     { "taggerdate", FIELD_TIME },     { "creator" },     { "creatordate", FIELD_TIME },     { "subject" },     { "body" },     { "contents" },     { "contents:subject" },     { "contents:body" },     { "contents:signature" },     { "upstream" },     { "symref" },     { "flag" },     { "HEAD" },     { "color" }, }; 

Answer 2

git for-each-ref --format mentions:

A string that interpolates %(fieldname) from a ref being shown and the object it points at.

And it refers to the section "FIELDS NAMES" which has a complete list.

Bit to see those options in action, you can report to t/t6300-for-each-ref.sh which illustrates all the "atoms" used for --format.

Those atoms just evolved with Git 2.29 (Q4 2020): the "--format=" option to the "for-each-ref" command and friends learned a few more tricks, e.g. the ":short" suffix that applies to "objectname" now also can be used for "parent", "tree", etc.

See commit 905f0a4, commit 47d4676, commit 26bc0aa, commit 837adb1, commit 87d3beb, commit e7601eb, commit 5101100, commit b82445d (21 Aug 2020) by Hariom Verma (harry-hov).
^{(Merged by Junio C Hamano -- gitster -- in commit c25fba9, 09 Sep 2020)}

ref-filter: add short modifier to 'parent' atom

^{Mentored-by: Christian Couder
Mentored-by: Heba Waly
Signed-off-by: Hariom Verma}

Sometimes while using 'parent' atom, user might want to see abbrev hash instead of full 40 character hash.

Just like 'objectname', it might be convenient for users to have the :short and :short=<length> option for printing 'parent' hash.

Let's introduce short option to 'parent' atom.

And:

ref-filter: add sanitize option for 'subject' atom

^{Mentored-by: Christian Couder
Mentored-by: Heba Waly
Signed-off-by: Hariom Verma}

Currently, subject does not take any arguments. This commit introduce sanitize formatting option to 'subject' atom.

subject:sanitize - print sanitized subject line, suitable for a filename.

e.g.

%(subject): "the subject line"  %(subject:sanitize): "the-subject-line" 

git for-each-ref now includes in its man page:

Instead of contents:subject, field subject can also be used to > obtain same results. :sanitize can be appended to subject for subject line suitable for filename.

---

Git 2.33 (Q3 2021) exposes a new way to see that list: the code to handle the "--format" option in "for-each-ref" and friends made too many string comparisons on %(atom)s used in the format string.
That has been corrected by converting them into enum when the format string is parsed.

See commit 1197f1a, commit 0caf20f (13 May 2021) by ZheNing Hu (adlternative).
^{(Merged by Junio C Hamano -- gitster -- in commit 289af16, 14 Jun 2021)}

ref-filter: introduce enum atom_type

^{Helped-by: Junio C Hamano
Helped-by: Christian Couder
Signed-off-by: ZheNing Hu}

In the original ref-filter design, it will copy the parsed atom's name and attributes to used_atom[i].name in the atom's parsing step, and use it again for string matching in the later specific ref attributes filling step.
It use a lot of string matching to determine which atom we need.

Introduce the enum "atom_type", each enum value is named as ATOM_*, which is the index of each corresponding valid_atom entry.
In the first step of the atom parsing, used_atom.atom_type will record corresponding enum value from valid_atom entry index, and then in specific reference attribute filling step, only need to compare the value of the used_atom[i].atom_type to check the atom type.

You can see the full list in ref-filter.c.