Re: [PATCH] glossary: use "object ID" as the canonical term
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Oct 27, 2026, 17:47 UTC
- Message-ID
- <xmqqh5i7kpc0.fsf@gitster.g>
- In-Reply-To
- <E45A3779-A25F-43BC-B490-1FB836EAEF39@gmail.com>
Ben Knoble <ben.knoble@gmail.com> writes:
Show 14 quoted lines
>> 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/