Re: [PATCH] Hash name is SHA-1

[Junio C Hamano <junkio@cox.net>]

Matthias Lederhofer <matled@gmx.net> writes:

> The patch should probably only change sha1 to SHA-1 and not reformat
> the initialisation of _usage arrays or the comments (new line before
> first line of comment).  If the reformatting is desired it should be a
> separate patch imho.

I do agree the original patch conflates many different things,
and it would be nicer to do this clean-up as separate pieces.

* Code and comment reformatting.

  I agree that multi-line comment should begin with "/*\n",
  the comment sentences should begin with an indent and "* ",
  and the comment block should end with an indent and "*/\n".

  But this obviously belongs to a separate clean-up.

* The official name of these 40-hexdigit thingy we use to name
  objects is "object name" (see Documentation/glossary.txt).

  Taking an example from this hunk from 'update' hook
  documentation:

    @@ -30,12 +30,12 @@ and executable, it is called with three parameters:

            $GIT_DIR/hooks/update refname sha1-old sha1-new

    +The refname parameter is relative to $GIT_DIR; e.g. for the master
    +head this is "refs/heads/master".  The two sha1 are the object names
    +for the refname before and after the update.  Note that the hook is
    +called before the refname is updated, so either sha1-old is 0{40}
    +(meaning there is no such ref yet), or it should match what is
    +recorded in refname.

  I would prefer "the two object names are for the refname before...".

* Some commands take any object name, while some others only
  take committish.  For example, this hunk for show-branch:

    @@ -29,7 +29,7 @@ no <rev> nor <glob> is given on the command line.
     OPTIONS
     -------
     <rev>::
    -	Arbitrary extended SHA1 expression (see `git-rev-parse`)
    +	Arbitrary extended SHA-1 expression (see `git-rev-parse`)
            that typically names a branch HEAD or a tag.

     <glob>::

  is not Horst's fault but this needs to name a committish, so
  rephrasing it to "an arbitrary object name" is not even correct
  (let alone spellfixing SHA-1).

* The name of the hash function we currently happen to use, in
  order to come up with an "object name", is SHA-1 not SHA1.

  Currently we say sha1 and sha-1 interchangeably, but if we aim
  for consistency we should use the latter thoughout.  For example:

    @@ -59,7 +59,7 @@ OPTIONS
            one.

     --symbolic::
    -	Usually the object names are output in SHA1 form (with
    +	Usually the object names are output in SHA-1 form (with
            possible '{caret}' prefix); this option makes them output in a
            form as close to the original input as possible.

  is a good change.  But at the same time we might want to say
  just "are output as their hexadecimal values".