Web lists-archives.com

Re: Referring to commits in commit messages

On Wed, Dec 19, 2018 at 2:36 PM Jonathan Nieder <jrnieder@xxxxxxxxx> wrote:
> 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


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.