Re: Referring to commits in commit messages

[Jeff King <peff@peff.net>]

On Wed, Dec 19, 2018 at 03:02:14PM +0100, Ævar Arnfjörð Bjarmason wrote:

> On Mon, Dec 17 2018, Jonathan Nieder wrote:
> 
> > v2.11.0-rc3~3^2~1 (stripspace: respect repository config, 2016-11-21)
> 
> Minor nit not just on this patch, but your patches in general: I think
> you're the only one using this type of template instead of the `%h
> ("%s", %ad)` format documented in SubmittingPatches.
> 
> I've had at least a couple of cases where I've git log --grep=<abbr sha>
> and missed a commit of yours when you referred to another commit.
> 
> E.g. when composing
> https://public-inbox.org/git/878t0lfwrj.fsf@evledraar.gmail.com/ I
> remembered PERLLIB_EXTRA went back & forth between
> working/breaking/working with your/my/your patch, so:
> 
>     git log --grep=0386dd37b1
> 
> Just found the chain up to my breaking change, but not your 7a7bfc7adc,
> which refers to that commit as v1.9-rc0~88^2.
> 
> Maybe this is really a feature request. I.e. maybe we should have some
> mode where --grep=<commitish> will be combined with some mode where we
> try to find various forms of <commitish> in commit messages, then
> normalize & match them....

That would help when you're using --grep, but not other things that are
trying to parse the commit message. Two instances I've noticed:

  - web interfaces like GitHub won't linkify this type of reference
    (whereas they will for something that looks like a hex object id)

  - my terminal makes it easy to select hex strings, but doesn't
    understand this git-describe output :)

These tools _could_ be taught a regex like /v(\d+.)(-rc\d+)?([~^]+d)*/.
But matching hex strings is a lot simpler, and works across many
projects.

So I agree with you that this git-describe format is less convenient for
readers, but my preferred solution is to use a different format, rather
than try to teach every reading tool to be more clever.

As far as I can tell, the main advantage of using "v2.11.0-rc3~3^2~1"
over its hex id is that it gives a better sense in time of which Git
version we're talking about.  The date in the parentheses does something
similar for wall-clock time, but it's left to the reader to map that to
a Git version if they choose.

Personally, I find the wall-clock time to be enough, since usually what
I want to know is "how ancient is this". And in the rare instance that I
care about the containing version, it's not a big deal to use "git tag
--contains".  If we really want to convey that information in the text,
I think it would be reasonable to say something like:

  In commit 1234abcd (the subject line, 2016-01-01, v2.11.0), we did
  blah blah blah

with a few simple rules:

  - only mention a single version, the oldest one that contains the
    commit[1]. If it's in v2.11.1, we can infer that it's in v2.12.0,
    etc.

  - only mention released commits; for the granularity we're talking
    about here, the distinction between v2.11.0 and v2.11.0-rc3 is not
    important

  - if it hasn't been in a released version, don't include a version at
    all.

That's probably over-engineering, and I'm perfectly fine with the
oid/subject/date format most people use. Just trying to give an option
if people really think the tag name is useful.

-Peff

[1] I usually compute the containing version with:

      $ git help has
      'has' is aliased to '!f() { git tag --contains "$@" | grep ^v | grep -v -- -rc | sort -V | head -1; }; f'

    though I suspect it could be done these days with fewer processes
    using "tag --sort".