What are valid fields for the --format option of git for-each-ref?
GitGit Problem Overview
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.
Git Solutions
Solution 1 - Git
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" },
};
Solution 2 - Git
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
.
Solution 3 - Git
You want to use git for-each-ref
so look at git help for-each-ref
. Or [here][1]
[1]: https://www.kernel.org/pub/software/scm/git/docs/git-for-each-ref.html "here"