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

[Ben Knoble <ben.knoble@gmail.com>]

> Le 26 oct. 2026 à 09:13, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :
> 
> From: Julia Evans <julia@jvns.ca>
> 
> Currently in the glossary "object name" is used as the canonical term to
> refer to an object's SHA-1 (or SHA-256) identifier. However, in several
> places in the documentation, "object name" is used with a different
> meaning, for example:
> 
> from git-rev-parse.adoc:
>   Usually the object names are output in SHA-1 form (with possible
>   ^ prefix); this option makes them output in a form as close to the
>   original input as possible.
> 
> 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.

I read you as saying that our docs say an object name is 
the 40-digit string, but some places use it to mean all the possible 
notations.

It does seem simpler to have one word (ID) for the 40 digits, and
another for all the various ways to write down something that
resolves to those digits.

> 
> from git-describe.adoc:
>   `<commit-ish>...`::
>     Commit-ish object names to describe. Defaults to `HEAD`
>     if omitted.
> 
> Especially in the `git-rev-parse.adoc` usage, it's clear that "master"
> is considered to be an object name, which is not what the glossary entry
> says.
> 
> It's important for the documentation to be precise, and it's useful to
> have a way to unambiguously refer to an object's SHA-1 identifier.
> For example, the term "object ID" is used many places in the
> documentation already, and there are places which say "object name" and
> mean "object ID", for example:

I love ID, btw! Ever since the datamodel patches I’ve caught
myself being more precise in my own writing, using ID when I mean
the 40-digit string :)

> from diff-generate-patch.adoc:
>   The index line includes the blob object names before and
>   after the change.
> 
> from gitformat-pack.adoc:
>   The base object name or offset is not included in the size
>   computation.
> 
> Update the glossary to use "object ID" to refer to the ID, and warn
> readers that "object name" does not always have the same meaning. If we
> ever reach a point where the term is used consistently, we can remove
> the warning.
> 
> This leaves us without an obvious term to use to refer to "a name for
> an object", but since that's already the case it's better to at least
> clearly acknowledge the issue.
> 
> As a bonus, this aligns Git's documentation better with how the terms
> "ID" and "name" are normally used in the broader industry, where an "ID"
> is normally understood to be something that's interpreted by computers,
> and a "name" is for humans.
> 
> This is similar to a patch Junio suggested in 2020:
> https://lore.kernel.org/git/xmqqft4zn2f7.fsf@gitster.c.googlers.com/
> 
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>   glossary: use "object ID" as the canonical term
> 
>   If folks have a different preference for how to word the definition of
>   "object name" I'm happy to change it.
> 
>   The only really important thing IMO is that we make it clear to readers
>   that "object name" doesn't always have the same meaning.
> 
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2282%2Fjvns%2Fobject-name-id-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2282/jvns/object-name-id-v1
> Pull-Request: https://github.com/gitgitgadget/git/pull/2282
> 
> Documentation/glossary-content.adoc | 18 +++++++++++-------
> 1 file changed, 11 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc
> index 52301a56dd..b1c216893a 100644
> --- a/Documentation/glossary-content.adoc
> +++ b/Documentation/glossary-content.adoc
> @@ -217,7 +217,7 @@ transferring objects between repositories; see linkgit:git-replace[1]
> for a more flexible and robust system to do the same thing.
> 
> [[def_hash]]hash::
> -    In Git's context, synonym for <<def_object_name,object name>>.
> +    In Git's context, synonym for <<def_object_identifier,object ID>>.
> 
> [[def_head]]head::
>   A <<def_ref,named reference>> to the <<def_commit,commit>> at the tip of a
> @@ -296,17 +296,20 @@ This commit is referred to as a "merge commit", or sometimes just a
> 
> [[def_object_database]]object database::
>   Stores a set of "objects", and an individual <<def_object,object>> is
> -    identified by its <<def_object_name,object name>>. The objects usually
> +    identified by its <<def_object_identifier,object ID>>. The objects usually
>   live in `$GIT_DIR/objects/`.
> 
> [[def_object_identifier]]object identifier, object ID, oid::
> -    Synonyms for <<def_object_name,object name>>.
> -
> -[[def_object_name]]object name::
>   The unique identifier of an <<def_object,object>>.  The
>   object name is usually represented by a 40 character

Should this now say « object ID »? And, while at it, should we 
mention SHA-256/other lengths?

>   hexadecimal string.  Also colloquially called <<def_SHA1,SHA-1>>.
> 
> +[[def_object_name]]object name::
> +    Depending on the context, either an <<def_object_identifier,object ID>>,
> +    or a name used to refer to an object, like a branch name or other reference.
> +    The meaning of this term has changed over time so it's not always used
> +    in a consistent way.
> +

I wonder if we the use of name is consistent enough to define 
object name as an ID or « any of the notations in gitrevisions(1)
that [would] resolve to an object ID » ?

> [[def_object_type]]object type::
>   One of the identifiers "<<def_commit_object,commit>>",
>   "<<def_tree_object,tree>>", "<<def_tag_object,tag>>" or
> @@ -553,7 +556,7 @@ The following pseudorefs are known to Git:
>   to the result.
> 
> [[def_ref]]ref::
> -    A name that points to an <<def_object_name,object name>> or
> +    A name that points to an <<def_object_identifier,object ID>> or
>   another ref (the latter is called a <<def_symref,symbolic ref>>).
>   For convenience, a ref can sometimes be abbreviated when used
>   as an argument to a Git command; see linkgit:gitrevisions[7]
> @@ -645,7 +648,8 @@ format. See linkgit:git-reflog[1] for details.
> 
> [[def_SHA1]]SHA-1::
>   "Secure Hash Algorithm 1"; a cryptographic hash function.
> -    In the context of Git used as a synonym for <<def_object_name,object name>>.
> +    In the context of Git used as a synonym for
> +    <<def_object_identifier,object ID>>.
> 
> [[def_shallow_clone]]shallow clone::
>   Mostly a synonym to <<def_shallow_repository,shallow repository>>
> 
> base-commit: 7e34d8174dcda3435d1404c9a30bef46afe6c13e
> --
> gitgitgadget