[CC += git@]

Hi Collin,

On 2026-02-03T16:01:52-0800, Collin Funk wrote:

Alejandro Colomar [off-list ref] writes:

quoted

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi!

I hadn't yet documented how to produce the Fixes: trailer fields in the
Linux man-pages project.  We require the commit-date to disambiguate
possible hash (and subject) collisions.  This documents how to produce
them easily.

I hope this will be useful to other projects.  I've been using this
format for some time, and it has some nice properties: it shows at first
glance the date of a commit (which itself gives an idea of how many
stable versions would need to be fixed).  It can also be parsed by a
machine, by having a consistent and simple (unambiguous) format.


Have a lovely night!
Alex

 CONTRIBUTING.d/git                 | 16 ++++++++++++++++
 CONTRIBUTING.d/patches/description | 11 +++++++++++
 2 files changed, 27 insertions(+)

diff --git a/CONTRIBUTING.d/git b/CONTRIBUTING.d/git
index 4b7a95472..3f944a23c 100644
--- a/CONTRIBUTING.d/git
+++ b/CONTRIBUTING.d/git

@@ -43,6 +43,22 @@ Description
 		$ git config --global \
 			sendemail.sendmailcmd 'mutt -H - && true';
 
+    Commit references
+	'Fixes:' trailer fields should have the following format.
+
+		Fixes: 12-char-hash ([author-date,] commit-date; "subject")
+
+	where the author date is optional, and only included if it's
+	somehow important.  The commit date is often more important, as
+	it's sorted, and thus can be used to find (with a binary search)
+	a commit whose hash and subject may have collisions.  To produce
+	such fields, the following git aliases are useful.
+
+		$ git config --global alias.ref \
+			"show --no-patch --abbrev=12 --date=short --format=tformat:'%C(auto)%h%C(reset) %C(dim white)(%cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(dim white)\")%C(reset)'"
+		$ git config --global alias.ref2 \
+			"show --no-patch --abbrev=12 --date=short --format=tformat:'%C(auto)%h%C(reset) %C(dim white)(%ad, %cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(dim white)\")%C(reset)'"
+

I would recommend taking a look at the one mentioned in git's
SubmittingPatches. It looks fairly similar to yours:

    $ git ref HEAD
    d9fb823121b1 (2026-02-02; "maintainer-makefile: propagate MAKEINFO to gendocs")
    $ git show -s --pretty=reference HEAD
    d9fb82312 (maintainer-makefile: propagate MAKEINFO to gendocs, 2026-02-02)

I've seen that format before (while investigating all the --pretty=
options).  I didn't know that was used in git(1)'s SubmittingPatches,
though.

I considered it, and concluded that it was suboptimal for several
reasons:

-  It is unclear whether ', 2026-02-02' is part of the commit message.
   Since it's common practice to quote the subject in other projects
   --such as the kernel--, a format that quotes the subject is
   preferrable.

-  The date is a short and fixed-width field.  Readability is better if
   such fields go early, as they would be aligned.  Compare:

	8df2abb81a90 (man/man3/stpncpy.3: wfix, 2026-01-06)
	a17ed1cefd7f (man/man3type/intN_t.3type: STANDARDS: These conform to C23, 2026-01-06)

	8df2abb81a90 (2026-01-06; "man/man3/stpncpy.3: wfix")
	a17ed1cefd7f (2026-01-06; "man/man3type/intN_t.3type: STANDARDS: These conform to C23")

-  I use a semicolon, which is a stronger separator than a comma, as
   that allows me to use a comma for adding another sub-field to the
   date field.  In some cases, the author date is useful:

	$ git ref2 8df2abb81a90
	8df2abb81a90 (2026-01-06, 2026-01-06; "man/man3/stpncpy.3: wfix")

   This also allows further future extension, for example for including
   the author and/or committer names, as other fields.

I wondered a few months ago whether I should let git know about this
to improve --pretty=reference.  I guess this is the time.  I've thus
added them to CC.


Have a lovely day!
Alex

Collin

-- 
<https://www.alejandro-colomar.es>