Re: Referring to commits in commit messages

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Dec 19, 2018, 23:29 UTC
Message-ID: <20181219232948.GD228469@google.com>
In-Reply-To: <20181219224810.GA20888@sigill.intra.peff.net>

Jeff King wrote:

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

>> 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.

Thanks.

[...]

Show 8 quoted lines

>> 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 speaking from experience: this is hard for newcomers to grasp.

> 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.

If it's that unreliable, I'd rather just have the hash, to be honest.

Ideally the full 40 characters, since that would make git name-rev --stdin work. :)

[...]

Show 7 quoted lines

>> 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).

Sure, but in those cases do we need the ability to query on them?

To me it seems similar to having a policy on how to reference people in commit messages (e.g. "always include their email address"), so that I can grep for a contributor to see how they were involved in a patch. If it's not structured data, then at some point I stop worrying so much about machine parsability.

Thanks, Jonathan