Re: [PATCH 1/2] Documentation: replace sha1 by SHA-1
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Apr 24, 2009, 22:38 UTC
- Message-ID
- <7vzle5ad8n.fsf@gitster.siamese.dyndns.org>
- In-Reply-To
- <20090424212856.GB14435@coredump.intra.peff.net>
Jeff King <peff@peff.net> writes:
Show 19 quoted lines
> On Fri, Apr 24, 2009 at 04:49:34PM +0200, Michael J Gruber wrote: > >> --- a/Documentation/git-cat-file.txt >> +++ b/Documentation/git-cat-file.txt >> @@ -76,7 +76,7 @@ If '--batch' is specified, output of the following form is printed for each >> object specified on stdin: >> >> ------------ >> -<sha1> SP <type> SP <size> LF >> +<SHA-1> SP <type> SP <size> LF >> <contents> LF >> ------------ > > Maybe it is just me, but I find the original for this one easier to > read. Perhaps because <sha1> is really a variable name here (but for a > human reader to interpret instead of a compiler), so I find the > punctuation and capitalization distracting. > > I wonder if all <sha1> should simply be left as-is.
Or spell them using their official terminology "object name".
In all places in the documentation these two patches touch, that is what matters. They are computed by taking a hash over a defined format, and the hash function we use happens to be SHA-1, but that is not important to somebody who wants to use "cat-file" nor even to somebody who wants to reimplement it. I think hash-object should mention what the actual hash function is, but even that should not stress the SHA-1-ness of the hash. That's just too much implementation detail.
And sha1 and SHA1 are both accepted colloquial forms of "object name" in the git world. I think it is Ok to leave it in the IRC transcript "pack heuristics" documentation (and I'd prefer that particular one left untouched). If we want to go formal in the documentation, I think rewriting them to SHA-1 misses the point.