Re: [PATCH] glossary: use "object ID" as the canonical term

[Junio C Hamano <gitster@pobox.com>]

Ben Knoble <ben.knoble@gmail.com> writes:

>> from gitrevisions.adoc:
>>   Here are various ways to spell object names.
>>   (lists <refname>, HEAD, etc)
>
> Perhaps « notation »
> would be the better word here, if one is needed.
>
> [Let me just use « 40 » as a magic number for the below,
> even though we know there might be other lengths.]
>
> I think Junio misunderstood your comment on this? Or perhaps
> the intent is overly-pedantic: « spell an object name » might
> mean « these things all represent the 40-digit object ID and
> are thus interchangeable », but I do think I find that interpretation confusing.

Think of a blob object, say a sequence of 6 bytes 'h', 'e', 'l',
'l', 'o', '\n'.  It is stored securely somewhere in Git's storage
system.  You can call it up whenever you need it.

But how do you call it up?  By specifying its name.  The name of
that blob is ce013625030ba8dba906f756967f9e9ca394464a in your SHA-1
repository, or 2cf8d83d9ee29543...b7e3f3a183d337639025de576db9ebb4
in your SHA-256 repository.  It is like a fruit is called orange in
one language while laranja in another language.  Different names in
repositories with different hashes, but in repositories with the
same hash, a name identifies the object uniquely.  We give names to
tree objects and commit objects in a similar way.  For example, a
commit object whose name is e83c5163316f89bfbde7d9ab23ca2e25604af290
is what everybody with a full clone of our project has.

Since it is so cumbersome to write an object name, we provide many
shorthand ways.  Perhaps e83c51633 may be a unique prefix among the
names of objects the repository knows about, in which case, you can
use that shorter hexadecimal string as if you are giving the full
object name.  Or a reference whose refname is 'refs/heads/main' may
record the object name of that commit, and you can use 'main' where
a command expects a commit object name.  Or that reference may be
recorded in HEAD (i.e., 'main' branch is checked out), and you can
say "HEAD".  Your HEAD may even record the commit's object name
directly (i.e., a detached HEAD that checks out the "Initial
revision of 'git', the information manager from hell").

In many (but not necessarily all) situations, refnames, branch
names, unique prefixes of object names, etc., can be used where
object names are expected to identify the object you want to name.

    Side note.  You cannot necessarily go in the other direction.
    When a command expects a branch name 'main', you cannot
    necessarily feed it the refname 'refs/heads/main' of the
    reference that is used to store the 'main' branch, or the object
    name that the reference 'refs/heads/main' records, and expect it
    to behave as if you gave 'main' to the command.

By the way, the story does not change if you forced people to use
"object identifier" instead of "object name".  If "Here are various
ways to spell object names" is wrong, then "Here are various ways to
spell object identifiers" is wrong in exactly the same way.  The
badness does not lie in "object <name|identifier>" in that sentence.
It is that the sentence does not say "Here are various things that
can be used in place of", and that is what needs to be corrected.

Long ago before we standardized on the phrase "object name", we had
mixture of phrases in our documentation and it was chaotic.  We
seemed to have big discussion about the terminology back then, and
with f1671ecbfa ([PATCH] Assorted changes to glossary, 2005-08-18),
we finally got it sorted out after having a firm description that
"object name" is the canonical word to use in the glossary, with all
other "identifier", "hash", and "SHA-1" as colloquial or historical
synonyms.

The patch rubbed it in the wrong way without appreciating the effort
that went into the current set of descriptions.  I would not be
surprised if there are pieces of documentation that use "hash" to
mean the name given to objects, either leftover from olden days or
newly written without paying close attention to what the official
terminology is (the recent "gitdatamodel" documentation also commits
this sin).  But I'd prefer to fix them to continue the effort
started at f1671ecbfa, not the other way around.

There may have been other discussions, but the discussion thread
that directly led to the said commit is:

https://lore.kernel.org/git/Pine.LNX.4.63.0508051655480.8418@wgmdd8.biozentrum.uni-wuerzburg.de/