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

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

From
Julia Evans via GitGitGadget <gitgitgadget@gmail.com>
Date
Oct 26, 2026, 13:06 UTC
Message-ID
<pull.2282.git.1793019999896.gitgitgadget@gmail.com>
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)
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:

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
 	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.
+
 [[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
Next: Junio C Hamano
Message 1 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.