{"thread":{"id":"66664","subject":"[PATCH] glossary: use \"object ID\" as the canonical term","startedAt":"2026-10-26T13:06:39Z","lastAt":"2026-10-28T01:08:38Z","messageCount":10,"participants":["Julia Evans via GitGitGadget","Junio C Hamano","Ben Knoble","D. Ben Knoble","Julia Evans"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"556341","messageId":"pull.2282.git.1793019999896.gitgitgadget@gmail.com","threadId":"66664","inReplyTo":null,"subject":"[PATCH] glossary: use \"object ID\" as the canonical term","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-26T13:06:39Z","receivedAt":"2026-10-26T13:06:39Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nCurrently in the glossary \"object name\" is used as the canonical term to\nrefer to an object's SHA-1 (or SHA-256) identifier. However, in several\nplaces in the documentation, \"object name\" is used with a different\nmeaning, for example:\n\nfrom git-rev-parse.adoc:\n    Usually the object names are output in SHA-1 form (with possible\n    ^ prefix); this option makes them output in a form as close to the\n    original input as possible.\n\nfrom gitrevisions.adoc:\n    Here are various ways to spell object names.\n    (lists <refname>, HEAD, etc)\n\nfrom git-describe.adoc:\n    `<commit-ish>...`::\n      Commit-ish object names to describe. Defaults to `HEAD`\n      if omitted.\n\nEspecially in the `git-rev-parse.adoc` usage, it's clear that \"master\"\nis considered to be an object name, which is not what the glossary entry\nsays.\n\nIt's important for the documentation to be precise, and it's useful to\nhave a way to unambiguously refer to an object's SHA-1 identifier.\nFor example, the term \"object ID\" is used many places in the\ndocumentation already, and there are places which say \"object name\" and\nmean \"object ID\", for example:\n\nfrom diff-generate-patch.adoc:\n    The index line includes the blob object names before and\n    after the change.\n\nfrom gitformat-pack.adoc:\n    The base object name or offset is not included in the size\n    computation.\n\nUpdate the glossary to use \"object ID\" to refer to the ID, and warn\nreaders that \"object name\" does not always have the same meaning. If we\never reach a point where the term is used consistently, we can remove\nthe warning.\n\nThis leaves us without an obvious term to use to refer to \"a name for\nan object\", but since that's already the case it's better to at least\nclearly acknowledge the issue.\n\nAs a bonus, this aligns Git's documentation better with how the terms\n\"ID\" and \"name\" are normally used in the broader industry, where an \"ID\"\nis normally understood to be something that's interpreted by computers,\nand a \"name\" is for humans.\n\nThis is similar to a patch Junio suggested in 2020:\nhttps://lore.kernel.org/git/xmqqft4zn2f7.fsf@gitster.c.googlers.com/\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    glossary: use \"object ID\" as the canonical term\n    \n    If folks have a different preference for how to word the definition of\n    \"object name\" I'm happy to change it.\n    \n    The only really important thing IMO is that we make it clear to readers\n    that \"object name\" doesn't always have the same meaning.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2282%2Fjvns%2Fobject-name-id-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2282/jvns/object-name-id-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2282\n\n Documentation/glossary-content.adoc | 18 +++++++++++-------\n 1 file changed, 11 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc\nindex 52301a56dd..b1c216893a 100644\n--- a/Documentation/glossary-content.adoc\n+++ b/Documentation/glossary-content.adoc\n@@ -217,7 +217,7 @@ transferring objects between repositories; see linkgit:git-replace[1]\n for a more flexible and robust system to do the same thing.\n \n [[def_hash]]hash::\n-\tIn Git's context, synonym for <<def_object_name,object name>>.\n+\tIn Git's context, synonym for <<def_object_identifier,object ID>>.\n \n [[def_head]]head::\n \tA <<def_ref,named reference>> to the <<def_commit,commit>> at the tip of a\n@@ -296,17 +296,20 @@ This commit is referred to as a \"merge commit\", or sometimes just a\n \n [[def_object_database]]object database::\n \tStores a set of \"objects\", and an individual <<def_object,object>> is\n-\tidentified by its <<def_object_name,object name>>. The objects usually\n+\tidentified by its <<def_object_identifier,object ID>>. The objects usually\n \tlive in `$GIT_DIR/objects/`.\n \n [[def_object_identifier]]object identifier, object ID, oid::\n-\tSynonyms for <<def_object_name,object name>>.\n-\n-[[def_object_name]]object name::\n \tThe unique identifier of an <<def_object,object>>.  The\n \tobject name is usually represented by a 40 character\n \thexadecimal string.  Also colloquially called <<def_SHA1,SHA-1>>.\n \n+[[def_object_name]]object name::\n+\tDepending on the context, either an <<def_object_identifier,object ID>>,\n+\tor a name used to refer to an object, like a branch name or other reference.\n+\tThe meaning of this term has changed over time so it's not always used\n+\tin a consistent way.\n+\n [[def_object_type]]object type::\n \tOne of the identifiers \"<<def_commit_object,commit>>\",\n \t\"<<def_tree_object,tree>>\", \"<<def_tag_object,tag>>\" or\n@@ -553,7 +556,7 @@ The following pseudorefs are known to Git:\n \tto the result.\n \n [[def_ref]]ref::\n-\tA name that points to an <<def_object_name,object name>> or\n+\tA name that points to an <<def_object_identifier,object ID>> or\n \tanother ref (the latter is called a <<def_symref,symbolic ref>>).\n \tFor convenience, a ref can sometimes be abbreviated when used\n \tas an argument to a Git command; see linkgit:gitrevisions[7]\n@@ -645,7 +648,8 @@ format. See linkgit:git-reflog[1] for details.\n \n [[def_SHA1]]SHA-1::\n \t\"Secure Hash Algorithm 1\"; a cryptographic hash function.\n-\tIn the context of Git used as a synonym for <<def_object_name,object name>>.\n+\tIn the context of Git used as a synonym for\n+\t<<def_object_identifier,object ID>>.\n \n [[def_shallow_clone]]shallow clone::\n \tMostly a synonym to <<def_shallow_repository,shallow repository>>\n\nbase-commit: 7e34d8174dcda3435d1404c9a30bef46afe6c13e\n-- \ngitgitgadget\n\n"},{"id":"556374","messageId":"xmqqecdcs83z.fsf@gitster.g","threadId":"66664","inReplyTo":"pull.2282.git.1793019999896.gitgitgadget@gmail.com","subject":"Re: [PATCH] glossary: use \"object ID\" as the canonical term","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-26T17:08:00Z","receivedAt":"2026-10-26T17:08:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> Currently in the glossary \"object name\" is used as the canonical term to\n> refer to an object's SHA-1 (or SHA-256) identifier. However, in several\n> places in the documentation, \"object name\" is used with a different\n> meaning, for example:\n\nThese other places should be fixed, IMHO, though.\n\n>\n> from git-rev-parse.adoc:\n>     Usually the object names are output in SHA-1 form (with possible\n>     ^ prefix); this option makes them output in a form as close to the\n>     original input as possible.\n>\n> from gitrevisions.adoc:\n>     Here are various ways to spell object names.\n>     (lists <refname>, HEAD, etc)\n\nYou can use <refname>, HEAD, etc., where the command takes object\nnames.  It exactly refers to those 40 hexadecimal digits to identify\nobjects.\n\nI'll reject this.\n\n\n"},{"id":"556490","messageId":"E45A3779-A25F-43BC-B490-1FB836EAEF39@gmail.com","threadId":"66664","inReplyTo":"pull.2282.git.1793019999896.gitgitgadget@gmail.com","subject":"Re: [PATCH] glossary: use \"object ID\" as the canonical term","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-27T12:15:42Z","receivedAt":"2026-10-27T12:15:42Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 26 oct. 2026 à 09:13, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :\n> \n> ﻿From: Julia Evans <julia@jvns.ca>\n> \n> Currently in the glossary \"object name\" is used as the canonical term to\n> refer to an object's SHA-1 (or SHA-256) identifier. However, in several\n> places in the documentation, \"object name\" is used with a different\n> meaning, for example:\n> \n> from git-rev-parse.adoc:\n>   Usually the object names are output in SHA-1 form (with possible\n>   ^ prefix); this option makes them output in a form as close to the\n>   original input as possible.\n> \n> from gitrevisions.adoc:\n>   Here are various ways to spell object names.\n>   (lists <refname>, HEAD, etc)\n\nPerhaps « notation »\nwould be the better word here, if one is needed.\n\n[Let me just use « 40 » as a magic number for the below,\neven though we know there might be other lengths.]\n\nI think Junio misunderstood your comment on this? Or perhaps\nthe intent is overly-pedantic: « spell an object name » might\nmean « these things all represent the 40-digit object ID and\nare thus interchangeable », but I do think I find that interpretation confusing.\n\nI read you as saying that our docs say an object name is \nthe 40-digit string, but some places use it to mean all the possible \nnotations.\n\nIt does seem simpler to have one word (ID) for the 40 digits, and\nanother for all the various ways to write down something that\nresolves to those digits.\n\n> \n> from git-describe.adoc:\n>   `<commit-ish>...`::\n>     Commit-ish object names to describe. Defaults to `HEAD`\n>     if omitted.\n> \n> Especially in the `git-rev-parse.adoc` usage, it's clear that \"master\"\n> is considered to be an object name, which is not what the glossary entry\n> says.\n> \n> It's important for the documentation to be precise, and it's useful to\n> have a way to unambiguously refer to an object's SHA-1 identifier.\n> For example, the term \"object ID\" is used many places in the\n> documentation already, and there are places which say \"object name\" and\n> mean \"object ID\", for example:\n\nI love ID, btw! Ever since the datamodel patches I’ve caught\nmyself being more precise in my own writing, using ID when I mean\nthe 40-digit string :)\n\n> from diff-generate-patch.adoc:\n>   The index line includes the blob object names before and\n>   after the change.\n> \n> from gitformat-pack.adoc:\n>   The base object name or offset is not included in the size\n>   computation.\n> \n> Update the glossary to use \"object ID\" to refer to the ID, and warn\n> readers that \"object name\" does not always have the same meaning. If we\n> ever reach a point where the term is used consistently, we can remove\n> the warning.\n> \n> This leaves us without an obvious term to use to refer to \"a name for\n> an object\", but since that's already the case it's better to at least\n> clearly acknowledge the issue.\n> \n> As a bonus, this aligns Git's documentation better with how the terms\n> \"ID\" and \"name\" are normally used in the broader industry, where an \"ID\"\n> is normally understood to be something that's interpreted by computers,\n> and a \"name\" is for humans.\n> \n> This is similar to a patch Junio suggested in 2020:\n> https://lore.kernel.org/git/xmqqft4zn2f7.fsf@gitster.c.googlers.com/\n> \n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>   glossary: use \"object ID\" as the canonical term\n> \n>   If folks have a different preference for how to word the definition of\n>   \"object name\" I'm happy to change it.\n> \n>   The only really important thing IMO is that we make it clear to readers\n>   that \"object name\" doesn't always have the same meaning.\n> \n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2282%2Fjvns%2Fobject-name-id-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2282/jvns/object-name-id-v1\n> Pull-Request: https://github.com/gitgitgadget/git/pull/2282\n> \n> Documentation/glossary-content.adoc | 18 +++++++++++-------\n> 1 file changed, 11 insertions(+), 7 deletions(-)\n> \n> diff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc\n> index 52301a56dd..b1c216893a 100644\n> --- a/Documentation/glossary-content.adoc\n> +++ b/Documentation/glossary-content.adoc\n> @@ -217,7 +217,7 @@ transferring objects between repositories; see linkgit:git-replace[1]\n> for a more flexible and robust system to do the same thing.\n> \n> [[def_hash]]hash::\n> -    In Git's context, synonym for <<def_object_name,object name>>.\n> +    In Git's context, synonym for <<def_object_identifier,object ID>>.\n> \n> [[def_head]]head::\n>   A <<def_ref,named reference>> to the <<def_commit,commit>> at the tip of a\n> @@ -296,17 +296,20 @@ This commit is referred to as a \"merge commit\", or sometimes just a\n> \n> [[def_object_database]]object database::\n>   Stores a set of \"objects\", and an individual <<def_object,object>> is\n> -    identified by its <<def_object_name,object name>>. The objects usually\n> +    identified by its <<def_object_identifier,object ID>>. The objects usually\n>   live in `$GIT_DIR/objects/`.\n> \n> [[def_object_identifier]]object identifier, object ID, oid::\n> -    Synonyms for <<def_object_name,object name>>.\n> -\n> -[[def_object_name]]object name::\n>   The unique identifier of an <<def_object,object>>.  The\n>   object name is usually represented by a 40 character\n\nShould this now say « object ID »? And, while at it, should we \nmention SHA-256/other lengths?\n\n>   hexadecimal string.  Also colloquially called <<def_SHA1,SHA-1>>.\n> \n> +[[def_object_name]]object name::\n> +    Depending on the context, either an <<def_object_identifier,object ID>>,\n> +    or a name used to refer to an object, like a branch name or other reference.\n> +    The meaning of this term has changed over time so it's not always used\n> +    in a consistent way.\n> +\n\nI wonder if we the use of name is consistent enough to define \nobject name as an ID or « any of the notations in gitrevisions(1)\nthat [would] resolve to an object ID » ?\n\n> [[def_object_type]]object type::\n>   One of the identifiers \"<<def_commit_object,commit>>\",\n>   \"<<def_tree_object,tree>>\", \"<<def_tag_object,tag>>\" or\n> @@ -553,7 +556,7 @@ The following pseudorefs are known to Git:\n>   to the result.\n> \n> [[def_ref]]ref::\n> -    A name that points to an <<def_object_name,object name>> or\n> +    A name that points to an <<def_object_identifier,object ID>> or\n>   another ref (the latter is called a <<def_symref,symbolic ref>>).\n>   For convenience, a ref can sometimes be abbreviated when used\n>   as an argument to a Git command; see linkgit:gitrevisions[7]\n> @@ -645,7 +648,8 @@ format. See linkgit:git-reflog[1] for details.\n> \n> [[def_SHA1]]SHA-1::\n>   \"Secure Hash Algorithm 1\"; a cryptographic hash function.\n> -    In the context of Git used as a synonym for <<def_object_name,object name>>.\n> +    In the context of Git used as a synonym for\n> +    <<def_object_identifier,object ID>>.\n> \n> [[def_shallow_clone]]shallow clone::\n>   Mostly a synonym to <<def_shallow_repository,shallow repository>>\n> \n> base-commit: 7e34d8174dcda3435d1404c9a30bef46afe6c13e\n> --\n> gitgitgadget\n\n"},{"id":"556548","messageId":"xmqqh5i7kpc0.fsf@gitster.g","threadId":"66664","inReplyTo":"E45A3779-A25F-43BC-B490-1FB836EAEF39@gmail.com","subject":"Re: [PATCH] glossary: use \"object ID\" as the canonical term","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-27T17:47:43Z","receivedAt":"2026-10-27T17:47:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ben Knoble <ben.knoble@gmail.com> writes:\n\n>> from gitrevisions.adoc:\n>>   Here are various ways to spell object names.\n>>   (lists <refname>, HEAD, etc)\n>\n> Perhaps « notation »\n> would be the better word here, if one is needed.\n>\n> [Let me just use « 40 » as a magic number for the below,\n> even though we know there might be other lengths.]\n>\n> I think Junio misunderstood your comment on this? Or perhaps\n> the intent is overly-pedantic: « spell an object name » might\n> mean « these things all represent the 40-digit object ID and\n> are thus interchangeable », but I do think I find that interpretation confusing.\n\nThink of a blob object, say a sequence of 6 bytes 'h', 'e', 'l',\n'l', 'o', '\\n'.  It is stored securely somewhere in Git's storage\nsystem.  You can call it up whenever you need it.\n\nBut how do you call it up?  By specifying its name.  The name of\nthat blob is ce013625030ba8dba906f756967f9e9ca394464a in your SHA-1\nrepository, or 2cf8d83d9ee29543...b7e3f3a183d337639025de576db9ebb4\nin your SHA-256 repository.  It is like a fruit is called orange in\none language while laranja in another language.  Different names in\nrepositories with different hashes, but in repositories with the\nsame hash, a name identifies the object uniquely.  We give names to\ntree objects and commit objects in a similar way.  For example, a\ncommit object whose name is e83c5163316f89bfbde7d9ab23ca2e25604af290\nis what everybody with a full clone of our project has.\n\nSince it is so cumbersome to write an object name, we provide many\nshorthand ways.  Perhaps e83c51633 may be a unique prefix among the\nnames of objects the repository knows about, in which case, you can\nuse that shorter hexadecimal string as if you are giving the full\nobject name.  Or a reference whose refname is 'refs/heads/main' may\nrecord the object name of that commit, and you can use 'main' where\na command expects a commit object name.  Or that reference may be\nrecorded in HEAD (i.e., 'main' branch is checked out), and you can\nsay \"HEAD\".  Your HEAD may even record the commit's object name\ndirectly (i.e., a detached HEAD that checks out the \"Initial\nrevision of 'git', the information manager from hell\").\n\nIn many (but not necessarily all) situations, refnames, branch\nnames, unique prefixes of object names, etc., can be used where\nobject names are expected to identify the object you want to name.\n\n    Side note.  You cannot necessarily go in the other direction.\n    When a command expects a branch name 'main', you cannot\n    necessarily feed it the refname 'refs/heads/main' of the\n    reference that is used to store the 'main' branch, or the object\n    name that the reference 'refs/heads/main' records, and expect it\n    to behave as if you gave 'main' to the command.\n\nBy the way, the story does not change if you forced people to use\n\"object identifier\" instead of \"object name\".  If \"Here are various\nways to spell object names\" is wrong, then \"Here are various ways to\nspell object identifiers\" is wrong in exactly the same way.  The\nbadness does not lie in \"object <name|identifier>\" in that sentence.\nIt is that the sentence does not say \"Here are various things that\ncan be used in place of\", and that is what needs to be corrected.\n\nLong ago before we standardized on the phrase \"object name\", we had\nmixture of phrases in our documentation and it was chaotic.  We\nseemed to have big discussion about the terminology back then, and\nwith f1671ecbfa ([PATCH] Assorted changes to glossary, 2005-08-18),\nwe finally got it sorted out after having a firm description that\n\"object name\" is the canonical word to use in the glossary, with all\nother \"identifier\", \"hash\", and \"SHA-1\" as colloquial or historical\nsynonyms.\n\nThe patch rubbed it in the wrong way without appreciating the effort\nthat went into the current set of descriptions.  I would not be\nsurprised if there are pieces of documentation that use \"hash\" to\nmean the name given to objects, either leftover from olden days or\nnewly written without paying close attention to what the official\nterminology is (the recent \"gitdatamodel\" documentation also commits\nthis sin).  But I'd prefer to fix them to continue the effort\nstarted at f1671ecbfa, not the other way around.\n\nThere may have been other discussions, but the discussion thread\nthat directly led to the said commit is:\n\nhttps://lore.kernel.org/git/Pine.LNX.4.63.0508051655480.8418@wgmdd8.biozentrum.uni-wuerzburg.de/\n\n\n"},{"id":"556550","messageId":"CALnO6CCGLFwFH73of8QHnsvFjHZ8d86CRhQgV88z=WeKun6abg@mail.gmail.com","threadId":"66664","inReplyTo":"xmqqh5i7kpc0.fsf@gitster.g","subject":"Re: [PATCH] glossary: use \"object ID\" as the canonical term","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-27T18:00:12Z","receivedAt":"2026-10-27T18:00:12Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Oct 27, 2026 at 1:47 PM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> Ben Knoble <ben.knoble@gmail.com> writes:\n>\n> >> from gitrevisions.adoc:\n> >>   Here are various ways to spell object names.\n> >>   (lists <refname>, HEAD, etc)\n> >\n> > Perhaps « notation »\n> > would be the better word here, if one is needed.\n> >\n> > [Let me just use « 40 » as a magic number for the below,\n> > even though we know there might be other lengths.]\n> >\n> > I think Junio misunderstood your comment on this? Or perhaps\n> > the intent is overly-pedantic: « spell an object name » might\n> > mean « these things all represent the 40-digit object ID and\n> > are thus interchangeable », but I do think I find that interpretation confusing.\n>\n> Think of a blob object, say a sequence of 6 bytes 'h', 'e', 'l',\n> 'l', 'o', '\\n'.  It is stored securely somewhere in Git's storage\n> system.  You can call it up whenever you need it.\n>\n> But how do you call it up?  By specifying its name.  The name of\n> that blob is ce013625030ba8dba906f756967f9e9ca394464a in your SHA-1\n> repository, or 2cf8d83d9ee29543...b7e3f3a183d337639025de576db9ebb4\n> in your SHA-256 repository.  It is like a fruit is called orange in\n> one language while laranja in another language.  Different names in\n> repositories with different hashes, but in repositories with the\n> same hash, a name identifies the object uniquely.  We give names to\n> tree objects and commit objects in a similar way.  For example, a\n> commit object whose name is e83c5163316f89bfbde7d9ab23ca2e25604af290\n> is what everybody with a full clone of our project has.\n>\n> Since it is so cumbersome to write an object name, we provide many\n> shorthand ways.  Perhaps e83c51633 may be a unique prefix among the\n> names of objects the repository knows about, in which case, you can\n> use that shorter hexadecimal string as if you are giving the full\n> object name.  Or a reference whose refname is 'refs/heads/main' may\n> record the object name of that commit, and you can use 'main' where\n> a command expects a commit object name.  Or that reference may be\n> recorded in HEAD (i.e., 'main' branch is checked out), and you can\n> say \"HEAD\".  Your HEAD may even record the commit's object name\n> directly (i.e., a detached HEAD that checks out the \"Initial\n> revision of 'git', the information manager from hell\").\n>\n> In many (but not necessarily all) situations, refnames, branch\n> names, unique prefixes of object names, etc., can be used where\n> object names are expected to identify the object you want to name.\n>\n>     Side note.  You cannot necessarily go in the other direction.\n>     When a command expects a branch name 'main', you cannot\n>     necessarily feed it the refname 'refs/heads/main' of the\n>     reference that is used to store the 'main' branch, or the object\n>     name that the reference 'refs/heads/main' records, and expect it\n>     to behave as if you gave 'main' to the command.\n\nI'm with you so far!\n\n> By the way, the story does not change if you forced people to use\n> \"object identifier\" instead of \"object name\".  If \"Here are various\n> ways to spell object names\" is wrong, then \"Here are various ways to\n> spell object identifiers\" is wrong in exactly the same way.  The\n> badness does not lie in \"object <name|identifier>\" in that sentence.\n> It is that the sentence does not say \"Here are various things that\n> can be used in place of\", and that is what needs to be corrected.\n\nI suppose where we diverge is that (partly due to datamodel) I think\nof \"ID\" as \"only the cryptographic hash of its contents\"---everything\nelse is a name or notation that Git eventually resolves to such a\nhash. (Well, it may not operationally, but in a mental model of how\nGit operates, that will do.)\n\n> Long ago before we standardized on the phrase \"object name\", we had\n> mixture of phrases in our documentation and it was chaotic.  We\n> seemed to have big discussion about the terminology back then, and\n> with f1671ecbfa ([PATCH] Assorted changes to glossary, 2005-08-18),\n> we finally got it sorted out after having a firm description that\n> \"object name\" is the canonical word to use in the glossary, with all\n> other \"identifier\", \"hash\", and \"SHA-1\" as colloquial or historical\n> synonyms.\n>\n> The patch rubbed it in the wrong way without appreciating the effort\n> that went into the current set of descriptions.  I would not be\n> surprised if there are pieces of documentation that use \"hash\" to\n> mean the name given to objects, either leftover from olden days or\n> newly written without paying close attention to what the official\n> terminology is (the recent \"gitdatamodel\" documentation also commits\n> this sin).  But I'd prefer to fix them to continue the effort\n> started at f1671ecbfa, not the other way around.\n>\n> There may have been other discussions, but the discussion thread\n> that directly led to the said commit is:\n>\n> https://lore.kernel.org/git/Pine.LNX.4.63.0508051655480.8418@wgmdd8.biozentrum.uni-wuerzburg.de/\n\nThat historical context is certainly useful, and definitely explains\nthat any work in this area is fraught. Still, absorbing a discussion\nfrom 2005 as a requirement for making improvements might be creating\ntoo much of a barrier to entry? idk.\n\nI can't speak for Julia, but I read her attempt here to clarify things\nin line with the ways folks usually use \"ID\" vs. \"name.\" Of course we\ndon't always want to let what other people say dictate our\nterminology, but in cases where we can make things easier for folks to\nunderstand by using vocabulary in line with their expectations rather\nthan subverting it, I think that's a worthy goal.\n\nI still find it strange to call \"main\" an object ID ;) even if our\ncurrent terminology says that's fine. Heck, the glossary says a name\nis a \"unique\" identifier… so there ought not to be more than one way\nto spell it, even if there are many notations to refer to it? Alas…\n\n-- \nD. Ben Knoble\n\n"},{"id":"556551","messageId":"CALnO6CBweMkXMZZnhOC7CERwVYfnWFKr+KHd0UiYzriiD4vdDw@mail.gmail.com","threadId":"66664","inReplyTo":"CALnO6CCGLFwFH73of8QHnsvFjHZ8d86CRhQgV88z=WeKun6abg@mail.gmail.com","subject":"Re: [PATCH] glossary: use \"object ID\" as the canonical term","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-27T18:03:34Z","receivedAt":"2026-10-27T18:03:34Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Oct 27, 2026 at 2:00 PM D. Ben Knoble <ben.knoble@gmail.com> wrote:\n>\n> I can't speak for Julia, but I read her attempt here to clarify things\n> in line with the ways folks usually use \"ID\" vs. \"name.\" Of course we\n> don't always want to let what other people say dictate our\n> terminology, but in cases where we can make things easier for folks to\n> understand by using vocabulary in line with their expectations rather\n> than subverting it, I think that's a worthy goal.\n\nRephrasing this: I'm not sure I think it's a good idea to expect\neveryone (esp. newcomers) to use what I view as idiosyncratic\ndefinitions of \"ID\", \"name\", etc. Yes, we've had them for a long time,\nand people mostly get by… but it can be confusing.\n\nWe have enough jargon, surely :)\n\n-- \nD. Ben Knoble\n\n"},{"id":"556562","messageId":"xmqqh5i7j6km.fsf@gitster.g","threadId":"66664","inReplyTo":"CALnO6CCGLFwFH73of8QHnsvFjHZ8d86CRhQgV88z=WeKun6abg@mail.gmail.com","subject":"Re: [PATCH] glossary: use \"object ID\" as the canonical term","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-27T19:18:17Z","receivedAt":"2026-10-27T19:18:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" <ben.knoble@gmail.com> writes:\n\n> I can't speak for Julia, but I read her attempt here to clarify things\n> in line with the ways folks usually use \"ID\" vs. \"name.\" Of course we\n> don't always want to let what other people say dictate our\n> terminology, but in cases where we can make things easier for folks to\n> understand by using vocabulary in line with their expectations rather\n> than subverting it, I think that's a worthy goal.\n\nThat goes both ways.  You can tell that to those who are subverting\nterminology that have clearly been documented for the past 20 years\nin our official glossary ;-).\n\n> I still find it strange to call \"main\" an object ID ;) even if our\n> current terminology says that's fine. Heck, the glossary says a name\n> is a \"unique\" identifier… so there ought not to be more than one way\n> to spell it, even if there are many notations to refer to it? Alas…\n\nI do not think it is OK.  \"main\" is *NOT* an object ID or object\nname.  \"main\" can be used where an object name or object identifier\nis called for to uniquely specify an object.\n\n\n\n"},{"id":"556564","messageId":"CALnO6CDMjtNVuvYNdnaKMSDQ0gxEXXo_r=133TeMNUCBZe1ikw@mail.gmail.com","threadId":"66664","inReplyTo":"xmqqh5i7j6km.fsf@gitster.g","subject":"Re: [PATCH] glossary: use \"object ID\" as the canonical term","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-27T19:24:23Z","receivedAt":"2026-10-27T19:24:23Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Oct 27, 2026 at 3:18 PM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> \"D. Ben Knoble\" <ben.knoble@gmail.com> writes:\n>\n> > I can't speak for Julia, but I read her attempt here to clarify things\n> > in line with the ways folks usually use \"ID\" vs. \"name.\" Of course we\n> > don't always want to let what other people say dictate our\n> > terminology, but in cases where we can make things easier for folks to\n> > understand by using vocabulary in line with their expectations rather\n> > than subverting it, I think that's a worthy goal.\n>\n> That goes both ways.  You can tell that to those who are subverting\n> terminology that have clearly been documented for the past 20 years\n> in our official glossary ;-).\n\nFair enough :)\n\n> > I still find it strange to call \"main\" an object ID ;) even if our\n> > current terminology says that's fine. Heck, the glossary says a name\n> > is a \"unique\" identifier… so there ought not to be more than one way\n> > to spell it, even if there are many notations to refer to it? Alas…\n>\n> I do not think it is OK.  \"main\" is *NOT* an object ID or object\n> name.  \"main\" can be used where an object name or object identifier\n> is called for to uniquely specify an object.\n\nAh… so in that case I think we may be saying some of the same things?\nInteresting.\n\n-- \nD. Ben Knoble\n\n"},{"id":"556588","messageId":"fbe5442b-6f01-4a23-8282-6a940b89da43@app.fastmail.com","threadId":"66664","inReplyTo":"xmqqh5i7j6km.fsf@gitster.g","subject":"Re: [PATCH] glossary: use \"object ID\" as the canonical term","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-27T22:34:54Z","receivedAt":"2026-10-27T22:34:54Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Tue, Oct 27, 2026, at 3:18 PM, Junio C Hamano wrote:\n> \"D. Ben Knoble\" <ben.knoble@gmail.com> writes:\n>\n>> I can't speak for Julia, but I read her attempt here to clarify things\n>> in line with the ways folks usually use \"ID\" vs. \"name.\" Of course we\n>> don't always want to let what other people say dictate our\n>> terminology, but in cases where we can make things easier for folks to\n>> understand by using vocabulary in line with their expectations rather\n>> than subverting it, I think that's a worthy goal.\n>\n> That goes both ways.  You can tell that to those who are subverting\n> terminology that have clearly been documented for the past 20 years\n> in our official glossary ;-).\n\nI'll only say that I genuinely thought this might be a fairly\nuncontroversial change. Obviously I was wrong about that :)\n\nI'll drop this.\n\n- Julia\n\n"},{"id":"556597","messageId":"xmqq33tqfx7t.fsf@gitster.g","threadId":"66664","inReplyTo":"CALnO6CCGLFwFH73of8QHnsvFjHZ8d86CRhQgV88z=WeKun6abg@mail.gmail.com","subject":"Re: [PATCH] glossary: use \"object ID\" as the canonical term","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-28T01:08:38Z","receivedAt":"2026-10-28T01:08:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" <ben.knoble@gmail.com> writes:\n\n>> There may have been other discussions, but the discussion thread\n>> that directly led to the said commit is:\n>>\n>> https://lore.kernel.org/git/Pine.LNX.4.63.0508051655480.8418@wgmdd8.biozentrum.uni-wuerzburg.de/\n>\n> That historical context is certainly useful, and definitely explains\n> that any work in this area is fraught. Still, absorbing a discussion\n> from 2005 as a requirement for making improvements might be creating\n> too much of a barrier to entry? idk.\n\nI do not think I ever hinted that it was a requirement (which would\nhave meant that an author to post such a patch without studying the\nhistory behind it was somehow an evil person).\n\nBut now all of us have a readily available reference to the earlier\nstory, we can make a more informed discussion.  As I said elsewhere,\nI wouldn't be surprised if there are many places that pretends as if\nID or Hash were canonical terminology and confuse readers by being\ninconsistent, and we should address such discrepancies as we find\nthem.\n\nThanks.\n\n\n"}]}