git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
D. Ben Knoble <ben.knoble@gmail.com>
Date
Oct 27, 2026, 18:00 UTC
Message-ID
<CALnO6CCGLFwFH73of8QHnsvFjHZ8d86CRhQgV88z=WeKun6abg@mail.gmail.com>
In-Reply-To
<xmqqh5i7kpc0.fsf@gitster.g>
On Tue, Oct 27, 2026 at 1:47 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 55 quoted lines
>
> 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.
I'm with you so far!
Show 7 quoted lines
> 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.

I suppose where we diverge is that (partly due to datamodel) I think of "ID" as "only the cryptographic hash of its contents"---everything else is a name or notation that Git eventually resolves to such a hash. (Well, it may not operationally, but in a mental model of how Git operates, that will do.)

Show 22 quoted lines
> 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/

That historical context is certainly useful, and definitely explains that any work in this area is fraught. Still, absorbing a discussion from 2005 as a requirement for making improvements might be creating too much of a barrier to entry? idk.

I can't speak for Julia, but I read her attempt here to clarify things in line with the ways folks usually use "ID" vs. "name." Of course we don't always want to let what other people say dictate our terminology, but in cases where we can make things easier for folks to understand by using vocabulary in line with their expectations rather than subverting it, I think that's a worthy goal.

I still find it strange to call "main" an object ID ;) even if our current terminology says that's fine. Heck, the glossary says a name is a "unique" identifier… so there ought not to be more than one way to spell it, even if there are many notations to refer to it? Alas…

-- 
D. Ben Knoble
Previous: Junio C HamanoNext: D. Ben Knoble
Message 5 of 10 in “glossary: use "object ID" as the canonical term”
  1. glossary: use "object ID" as the canonical termJulia Evans via GitGitGadget, Oct 26, 2026
  2. Junio C HamanoOct 26, 2026
  3. Ben KnobleOct 27, 2026
  4. Junio C HamanoOct 27, 2026
  5. D. Ben KnobleOct 27, 2026
  6. D. Ben KnobleOct 27, 2026
  7. Junio C HamanoOct 27, 2026
  8. D. Ben KnobleOct 27, 2026
  9. Julia EvansOct 27, 2026
  10. Junio C HamanoOct 28, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.