git for-each-ref的--format选项的有效字段是什么？

Question

我试图找到在存储库上创建的第一个分支.为此,我使用了:

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

但是我想要更多关于这个分支的信息.即这个分支存在了多长时间,何时合并回主干线等.是否有可用的字段选项列表？我尝试使用谷歌搜索,但找不到任何东西.

Answer 1

我在git存储库上找到了一个字段列表,文件内置/ 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提到：

%(fieldname)从显示的引用及其指向的对象插入的字符串。

它指的是“字段名称”部分，其中有完整的列表。

要查看这些选项的实际效果，您可以报告其中t/t6300-for-each-ref.sh说明了用于 的所有“原子” --format。

这些原子刚刚随着 Git 2.29（2020 年第 4 季度）而发展：“ ”命令--format=的“ for-each-ref”选项和朋友们学到了更多技巧，例如:short适用于“”的“”后缀objectname现在也可以用于“ parent”、“ tree” ， ETC。

请参阅提交 905f0a4、提交 47d4676、提交 26bc0aa、提交 837adb1、提交 87d3beb、提交 e7601eb、提交 5101100、提交 b82445d（2020 年 8 月 21 日），作者：Hariom Verma ( harry-hov)。
^{（由Junio C Hamano 合并 -- gitster--在提交 c25fba9中，2020 年 9 月 9 日）}

ref-filter：short为“父”原子添加修饰符

^{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.

Git 2.40 (Q1 2023) adds some clearer error messages produced by "git for-each-ref"^(man) and friends.

See commit 285da43, commit 1955ef1, commit dda4fc1, commit a33d0fa, commit afc1a94 (14 Dec 2022) by Jeff King (peff).
^{(Merged by Junio C Hamano -- gitster -- in commit 78d1502, 26 Dec 2022)}

ref-filter: convert email atom parser to use err_bad_arg()

^{Signed-off-by: Jeff King
Acked-by: Taylor Blau}

The error message for a bogus argument to %(authoremail), etc, is:

$ git for-each-ref --format='%(authoremail:foo)'
fatal: unrecognized email option: foo

Saying just "email" is a little vague; most of the other atom parsers would use the full name "%(authoremail)", but we can't do that here because the same function also handles %(taggeremail), etc.
Until recently, passing atom->name was a bad idea, because it erroneously included the arguments in the atom name.
But since the previous commit taught err_bad_arg() to handle this, we can now do so and get:

fatal: unrecognized %(authoremail) argument: foo

which is consistent with other atoms.

With Git 2.43 (Q4 2023), "git for-each-ref"^(man) and friends learn to apply mailmap to authorname and other fields.

See commit a3d2e83, commit 0144f0d, commit 04830eb (25 Sep 2023) by Kousik Sanagavarapu (five-sh).
^{(Merged by Junio C Hamano -- gitster -- in commit 42b495e, 04 Oct 2023)}

ref-filter: add mailmap support

^{Mentored-by: Christian Couder
Mentored-by: Hariom Verma
Signed-off-by: Kousik Sanagavarapu}

Add mailmap support to ref-filter formats which are similar in pretty.
This support is such that the following pretty placeholders are equivalent to the new ref-filter atoms:

%aN = authorname:mailmap
%cN = committername:mailmap

%aE = authoremail:mailmap
%aL = authoremail:mailmap,localpart
%cE = committeremail:mailmap
%cL = committeremail:mailmap,localpart

Additionally, mailmap can also be used with ":trim" option for email by doing something like "authoremail:mailmap,trim".

The above also applies for the "tagger" atom, that is, "taggername:mailmap", "taggeremail:mailmap", "taggeremail:mailmap,trim" and "taggername:mailmap,localpart".

The functionality of ":trim" and ":localpart" remains the same.
That is, ":trim" gives the email, but without the angle brackets and ":localpart" gives the part of the email before the '@' character (if such a character is not found then we directly grab everything between the angle brackets).

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

从修剪过的电子邮件中。除了这些之外，还可以使用该:mailmap选项和相应的:mailmap,trimand :mailmap,localpart（顺序无关）根据文件.mailmap或根据mailmap.file或mailmap.blob配置变量中设置的文件获取名称和电子邮件的值（请参阅链接git：gitmailmap [5 ]）。