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

["Julia Evans via GitGitGadget" <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