Re: Referring to commits in commit messages

From: Jacob Keller <jacob.keller@gmail.com>
Date: Dec 24, 2018, 00:01 UTC
Message-ID: <CA+P7+xoL2jEV68bkndoLmRBaTY0vNs=gBAWdpw=U4g=XO-Eapg@mail.gmail.com>
In-Reply-To: <20181219221401.GC228469@google.com>

On Wed, Dec 19, 2018 at 2:36 PM Jonathan Nieder <jrnieder@gmail.com> wrote:

Show 23 quoted lines

> In Linux kernel land, Documentation/process/submitting-patches.rst
> contains the following:
>
> -- >8 --
> If your patch fixes a bug in a specific commit, e.g. you found an issue using
> ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
> the SHA-1 ID, and the one line summary.  For example::
>
>         Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
>
> The following ``git config`` settings can be used to add a pretty format for
> outputting the above style in the ``git log`` or ``git show`` commands::
>
>         [core]
>                 abbrev = 12
>         [pretty]
>                 fixes = Fixes: %h (\"%s\")
> -- 8< --
>
> I like it because (1) the semantics are clear, (2) it's very concrete
> (e.g. "first 12 characters", (3) it goes in a trailer, where other
> bits intended for machine consumption already go.
>

For what it's worth, Linux's checkpatch.pl script also checks for and enforces that commit references have this format.

I personally like having the date information, and have attempted to get checkpatch.pl to stop complaining about the date when it's included. (see https://patchwork.ozlabs.org/patch/821543/ for the patch that I've had up, we've been trying to get the maintainer of checkpatch.pl to notice and pull it in, but not very much success as of yet).

I'd prefer to keep the format as seen on this list fairly often which is the something like

show --pretty=%h (\"%s\", %ad) --date=short

or

show --pretty=%h (\"%s\", %cd) --date=short

I like the date since it gives a quick approximation of how long ago the commit was made, and helps in the rare case of disambiguation. Personally I also like the quotes since it makes it more obvious where the subject begins and ends. They aren't strictly necessary but aid readability to me.

Thanks, Jake