Re: Referring to commits in commit messages

[Jeff King <peff@peff.net>]

On Wed, Dec 19, 2018 at 10:39:27AM -0800, Jonathan Nieder wrote:

> Jeff King wrote:
> 
> >   - 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.
> 
> Is there some rule about how long the hex string has to be for this to
> work?

In both cases, it has to be 7 characters. In my experience, it doesn't
produce a lot of false positives (in the case of GitHub, I believe it
actually confirms that it's a real commit; in my terminal, it highlights
anything plausible).

> >   In commit 1234abcd (the subject line, 2016-01-01, v2.11.0), we did
> >   blah blah blah
> 
> The issue with this is that it is ambiguous about what the tag name is
> referring to: does that mean that "git describe" and "git version"
> tell me that v2.11.0 is the nearest *previous* release to that commit
> or that "git name-rev" tells me that v2.11.0 is a nearby *subsequent*
> release that contains it?

Sure, it's ambiguous if you've never seen it. But if it becomes a
convention in the project, then I don't think that's an obstacle.

I'm also not sure it really matters all that much either way. If you buy
my argument that this is just about placing the general era of the
commit in the mind of the reader, then "just before v2.11" or "just
after v2.11" are about the same.

> Of course the latter is the only answer that's useful, but in practice
> the former is what people tend to do when they are trying to follow a
> convention like this.  So we'd need some automatic linting to make it
> useful.

I thought we were just talking about an informational message in one
human's writing, that would be read and interpreted by another human
(the commit id is the thing that remains machine-readable). Automatic
linting seems a bit overboard...

> I think a more promising approach is the Fixes trailer Duy mentioned,
> which has been working well for the Linux kernel project.  I'll follow
> up in a reply to his message.

I think that's a good idea if something is in fact being fixed. But
there are many other reasons to refer to another commit in prose (or
even outside of a commit message entirely).

-Peff