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

[Vadim Zeitlin]

On Wed, 25 Mar 2020 16:38:44 +0000 Greg Chicares <address@hidden> wrote:

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

 Yes, and unfortunately there doesn't seem to be any way to customize
messages produced by it. Of course, they can still be edited manually.

GC> More commonly, I've
GC> written commit messages like this:
GC>     Reverted commit b30b5db803, which has been rendered unnecessary.
GC> with approximately ten hex digits.

 This addresses one concern, with wrapping, but not the other one: I still
don't know what b30b5db803 was (nor what 
88bf1025e65e2f1e51c76c057634659e11a7fdbd
was neither, of course) when reading the commit history.

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

 It's definitely supposed to be. I very often use "git log --oneline" (I
have "git lg" as an alias to it, with a couple of other extra options) or
"git log --graph" (I have another alias for it...) and it's really helpful
to be able to see what each commit did from just the summary.

GC> >  The only possible objection to it I can see is that commit SHA-1 which 
are
GC> > unique now might become ambiguous in the future. However in the
GC> > (relatively, but not completely) unlikely case that this happens we would
GC> > still be able to find the original commit by choosing the one with this
GC> > abbreviated SHA-1 before the specified date, so it should never be a
GC> > problem in practice.
GC> 
GC> To avoid such potential future ambiguity, I've tended to include
GC> a few more digits than the minimum. But I've never seen a problem
GC> with that in practice for lmi, so whatever number of digits "format:%h"
GC> provides is sufficient.

 FWIW, %h is dynamic and depends on the size of the repository, so it can
start using more digits than the 9 it uses for lmi currently in the future,
e.g. it uses 10 for wx repository and 12 for Linux one. We'd need quite a
few more commits for this, however.

GC> >  What do you think of using this format for lmi?
GC> 
GC> It's just fine for optional use. I'm not ready to will that it should
GC> become a universal law, because I don't think one is necessary,

 It's definitely not necessarily, but it just seems like such a good idea.
I always found commit references in Git commit messages rather useless when
viewing them in the terminal (GitHub turns them into hyperlinks, with
tooltips, automatically, which is very nice) and this convention addresses
this concern very well.

GC> and also because, if I had a seat in the universal parliament of git, I
GC> would instead have proposed:
GC> 
GC> - git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
GC> + git show -s --date=short --pretty='format:%h (%s, %cI)' <commit>
GC>                                                      ^^

 Hmm, I'd probably use "i" rather than "I", as the latter is IMO less
readable due to the lack of separation between the date and the time parts.
And in practice, I use the value of "iso" for log.date in my ~/.gitconfig
so %ad already does the same thing as %ai for me anyhow.

 As for the difference between %a and %c, it's less obvious. I think the
author time is more important, but I'm not really sure why, to be honest.

 Anyhow, I'll start using this style for my commits and maybe you will be
so impressed by its benefits when looking at Git history in the future that
you will convert to it too.

 Thanks,
VZ

pgp3dleYKPpyb.pgp
Description: PGP signature