On Mon, Nov 23, 2020 at 02:17:32PM -0800, Junio C Hamano wrote:
> Jeff King <peff@xxxxxxxx> writes:
>
> > It might just be me, but "object name" makes me think we'd take any name
> > (e.g., a refname that resolves to an object), whereas "object id" would
> > mean the object's hash specifically. And in this instance we only allow
> > the latter.
>
> Yeah, but glossary-content is very much explicit about this. "name"
> is the full hexadecimal hash, "identifier" is a synonym for it. And
> "id" does not even appear to be defined. We used to call "any name
> that refers to an object" an "extended SHA-1", but I haven't seen
> the phrase used for a long time on the list.
OK, then my "it might just be me" is clearly just me. :)
I think the distinction I laid out earlier is nicer, but it may not be
worth the trouble of trying to _change_ nomenclature at this point.
Let's see what your glossary changes say...
> I've always found it cumbersome that, when I want to mean a full hex
> representation, I have to say "40-byte object name". It is not even
> technically correct these days with SHA-256.
Yeah, that is both long and wrong. I'd maybe say "hex object id" in some
cases, which is slightly less cumbersome and extends to sha256. And
distinguishes it from a binary object id (though see below).
> Documentation/glossary-content.txt | 15 +++++++++++----
> 1 file changed, 11 insertions(+), 4 deletions(-)
>
> diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt
> index 090c888335..e2ab920911 100644
> --- c/Documentation/glossary-content.txt
> +++ w/Documentation/glossary-content.txt
> @@ -262,13 +262,20 @@ This commit is referred to as a "merge commit", or sometimes just a
> identified by its <<def_object_name,object name>>. The objects usually
> live in `$GIT_DIR/objects/`.
>
> +[[def_object_id]]object ID::
> + Synonym for <<def_object_identifier,object identifier>>.
> +
> [[def_object_identifier]]object identifier::
> - Synonym for <<def_object_name,object name>>.
> + An <<def_object_name, object name>> written as an
> + unabbreviated hexadecimal representation of the hash value
> + that uniquely identifies an <<def_object,object>>.
> + Also colloquially called <<def_SHA1,SHA-1>>.
You might want to touch on "binary" here, too, with something like:
This may also be used to refer to the binary representation of the
hash value (e.g., as found within Git trees). Unless specified, this
term typically implies the hexadecimal representation.
But maybe that is overkill. When we are talking about the command line
interface, stdin, etc, I can't think of a place where we'd take the
binary ("hash-object -t tree", but I don't really count that).
> [[def_object_name]]object name::
> - The unique identifier of an <<def_object,object>>. The
> - object name is usually represented by a 40 character
> - hexadecimal string. Also colloquially called <<def_SHA1,SHA-1>>.
> + A name that identifies an <<def_object,object>> uniquely,
> + which can be given in various ways, including but not
> + limited to, the object's full <<def_object_identifier,object
> + identifier>>, a <<def_ref,ref>> that refers to the object.
This all seems like an improvement to me, though the real question is
how often the term "object name" appears in the _other_ manpages to
refer to the more limited case.
-Peff
