Re: [lmi] Proposal for commit references format in the commit messages

[Greg Chicares]

On 2020-03-25 15:42, Vadim Zeitlin wrote:
> 
>  So far, we've been referring to the existing commits in new commit
> messages by their full SHA-1. This is completely unambiguous, but creates
> word wrapping problems, due to the length of the commit hashes, and, maybe
> more importantly, is not particularly clear, as baseline humans have little
> capacity for remembering random sequences of 40 hexadecimal digits and so
> it's impossible in practice to know which commit is being referred to
> without using some Git command (git-log, git-show, ...) to look it up.

I've used some commit messages like this:
    This reverts commit 88bf1025e65e2f1e51c76c057634659e11a7fdbd.
but I think those are written by git-revert itself. More commonly, I've
written commit messages like this:
    Reverted commit b30b5db803, which has been rendered unnecessary.
with approximately ten hex digits.

When I want more clarity, I write something like this:

commit 3d6e389b979dcc3469a60b5ddd265fa553c4b6ce
Author: Gregory W. Chicares <address@hidden>
Date:   2019-08-25T20:49:53+00:00
[...]    
    What was asserted in commit 89e684ce of 20190802T2218Z is [...]

because I haven't transcended time as the git designers have, so I
still commit each change at a particular instant (and I rarely if
ever commit two changes in the same clock minute, so any finer
granularity would be wasted).

>  Git project itself uses a different convention, as explained in the
> "commit-reference" section of its patch submission guidelines at
> 
> https://git.kernel.org/pub/scm/git/git.git/plain/Documentation/SubmittingPatches?id=master
[...as exemplified in...]
> https://github.com/vadz/lmi/pull/139/commits/cc3412451592d715dc704a1f9309a3bcf6792f58
> 
> which I reproduce here:
> 
>     Remove unused starts_with() function from PDF generation code
> 
>     This function is not used any longer after the changes of the commit
>     12f58cdd3 (Simplify single-premium conditionals, 2019-08-26) and
>     resulted in -Wunused-function from clang.
> 
>  I believe this format of commit reference is much more useful than the
> current one and I like it so much that I'm going to start using it for all
> my other projects from now on.

That's perfectly fine by me. I'm not convinced that the first line
of the referenced commit message is generally useful, but I don't
object if you want to include it in commit messages you write.

>  The only possible objection to it I can see is that commit SHA-1 which are
> unique now might become ambiguous in the future. However in the
> (relatively, but not completely) unlikely case that this happens we would
> still be able to find the original commit by choosing the one with this
> abbreviated SHA-1 before the specified date, so it should never be a
> problem in practice.

To avoid such potential future ambiguity, I've tended to include
a few more digits than the minimum. But I've never seen a problem
with that in practice for lmi, so whatever number of digits "format:%h"
provides is sufficient.

>  What do you think of using this format for lmi?

It's just fine for optional use. I'm not ready to will that it should
become a universal law, because I don't think one is necessary, and
also because, if I had a seat in the universal parliament of git, I
would instead have proposed:

- git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
+ git show -s --date=short --pretty='format:%h (%s, %cI)' <commit>
                                                     ^^