glossary: use "object ID" as the canonical term

From: Julia Evans <[email protected]>

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: Julia Evans <[email protected]>

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/[email protected]/

Signed-off-by Julia Evans <[email protected]>

---
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(-)

Documentation/glossary-content.adoc +0 -0

index 52301a56dd..b1c216893a 100644
@@ -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::

Documentation/glossary-content.adoc +1 -1

-    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

Documentation/glossary-content.adoc +0 -0

@@ -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

Documentation/glossary-content.adoc +1 -1

-    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::

[[def_object_type]]object type::
One of the identifiers "<<def_commit_object,commit>>", "<<def_tree_object,tree>>", "<<def_tag_object,tag>>" or

Documentation/glossary-content.adoc +0 -0

@@ -553,7 +556,7 @@ The following pseudorefs are known to Git:
  to the result.
 

[[def_ref]]ref::

Documentation/glossary-content.adoc +1 -1

-    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.

Documentation/glossary-content.adoc +2 -1

-    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

Quoted 3 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.

Quoted 7 lines · Ben Knoble

Quoted 3 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.

Quoted 7 lines

[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/

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 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…

Quoted 6 lines · D. Ben Knoble

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.

That goes both ways. You can tell that to those who are subverting terminology that have clearly been documented for the past 20 years in our official glossary ;-).

Quoted 4 lines

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…

I do not think it is OK. "main" is *NOT* an object ID or object name. "main" can be used where an object name or object identifier is called for to uniquely specify an object.

Quoted 6 lines · D. Ben Knoble

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.

That goes both ways. You can tell that to those who are subverting terminology that have clearly been documented for the past 20 years in our official glossary ;-).

Quoted 4 lines

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.