{"thread":{"id":"60499","subject":"[PATCH] glossary: add definitions for dereference & peel","startedAt":"2023-11-09T23:58:01Z","lastAt":"2023-11-14T04:49:52Z","messageCount":6,"participants":["Victoria Dye via GitGitGadget","Junio C Hamano","Kristoffer Haugsbakk"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"484683","messageId":"pull.1610.git.1699574277143.gitgitgadget@gmail.com","threadId":"60499","inReplyTo":null,"subject":"[PATCH] glossary: add definitions for dereference & peel","fromName":"Victoria Dye via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-11-09T23:57:57Z","receivedAt":"2023-11-09T23:58:01Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"From: Victoria Dye <vdye@github.com>\n\nAdd 'gitglossary' definitions for \"dereference\" (as it used for both symrefs\nand objects) and \"peel\". These terms are used in options and documentation\nthroughout Git, but they are not clearly defined anywhere and the behavior\nthey refer to depends heavily on context. Provide explicit definitions to\nclarify existing documentation to users and help contributors to use the\nmost appropriate terminology possible in their additions to Git.\n\nUpdate other definitions in the glossary that use the term \"dereference\" to\nlink to 'def_dereference'.\n\nSigned-off-by: Victoria Dye <vdye@github.com>\n---\n    glossary: add definitions for dereference & peel\n    \n    As promised in [1], this patch adds definitions for \"peel\" and\n    \"dereference\" in the glossary, based on how they're currently used\n    throughout Git. As a result, the definitions are somewhat broad\n    (although I did my best to explicitly describe the different contexts in\n    which they're used). My hope is that this will at least reduce confusion\n    around this terminology. These definitions can also serve as a starting\n    point if, in the future, another contributor wants to deprecate certain\n    usages of these terms to make them less ambiguous.\n    \n     * Victoria\n    \n    [1]\n    https://lore.kernel.org/git/21dfe606-39f5-4154-aaa4-695e5f6f784d@github.com/\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1610%2Fvdye%2Fvdye%2Fglossary-peel-dereference-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1610/vdye/vdye/glossary-peel-dereference-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1610\n\n Documentation/glossary-content.txt | 50 +++++++++++++++++++++---------\n 1 file changed, 36 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 65c89e7b3eb..41dd5721def 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -98,9 +98,8 @@ to point at the new commit.\n \trevision.\n \n [[def_commit-ish]]commit-ish (also committish)::\n-\tA <<def_commit_object,commit object>> or an\n-\t<<def_object,object>> that can be recursively dereferenced to\n-\ta commit object.\n+\tA <<def_commit_object,commit object>> or an <<def_object,object>> that\n+\tcan be recursively <<def_dereference,dereferenced>> to a commit object.\n \tThe following are all commit-ishes:\n \ta commit object,\n \ta <<def_tag_object,tag object>> that points to a commit\n@@ -125,6 +124,24 @@ to point at the new commit.\n \tdangling object has no references to it from any\n \treference or <<def_object,object>> in the <<def_repository,repository>>.\n \n+[[def_dereference]]dereference::\n+\tReferring to a <<def_symref,symbolic ref>>: the action of accessing the\n+\t<<def_ref,reference>> pointed at by a symbolic ref. Recursive\n+\tdereferencing involves repeating the aforementioned process on the\n+\tresulting ref until a non-symbolic reference is found.\n++\n+Referring to a <<def_tag_object,tag object>>: the action of accessing the\n+<<def_object,object>> a tag points at. Tags are recursively dereferenced by\n+repeating the operation on the result object until the result has either a\n+specified <<def_object_type,object type>> (where applicable) or any non-\"tag\"\n+object type.\n++\n+Referring to a <<def_commit_object,commit object>>: the action of accessing\n+the commit's tree object. Commits cannot be dereferenced recursively.\n++\n+Unless otherwise specified, \"dereferencing\" as it used in the context of Git\n+commands or protocols is implicitly recursive.\n+\n [[def_detached_HEAD]]detached HEAD::\n \tNormally the <<def_HEAD,HEAD>> stores the name of a\n \t<<def_branch,branch>>, and commands that operate on the\n@@ -444,6 +461,12 @@ exclude;;\n \tof the logical predecessor(s) in the line of development, i.e. its\n \tparents.\n \n+[[def_peel]]peel::\n+\tSynonym for object <<def_dereference,dereference>>. Most commonly used\n+\tin the context of tags, where it refers to the process of recursively\n+\tdereferencing a <<def_tag_object,tag object>> until the result object's\n+\t<<def_object_type,type>> is something other than \"tag\".\n+\n [[def_pickaxe]]pickaxe::\n \tThe term <<def_pickaxe,pickaxe>> refers to an option to the diffcore\n \troutines that help select changes that add or delete a given text\n@@ -620,12 +643,11 @@ The most notable example is `HEAD`.\n \tcopies of) commit objects of the contained submodules.\n \n [[def_symref]]symref::\n-\tSymbolic reference: instead of containing the <<def_SHA1,SHA-1>>\n-\tid itself, it is of the format 'ref: refs/some/thing' and when\n-\treferenced, it recursively dereferences to this reference.\n-\t'<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic\n-\treferences are manipulated with the linkgit:git-symbolic-ref[1]\n-\tcommand.\n+\tSymbolic reference: instead of containing the <<def_SHA1,SHA-1>> id\n+\titself, it is of the format 'ref: refs/some/thing' and when referenced,\n+\tit recursively <<def_dereference,dereferences>> to this reference.\n+\t'<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic references\n+\tare manipulated with the linkgit:git-symbolic-ref[1] command.\n \n [[def_tag]]tag::\n \tA <<def_ref,ref>> under `refs/tags/` namespace that points to an\n@@ -661,11 +683,11 @@ The most notable example is `HEAD`.\n \t<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.\n \n [[def_tree-ish]]tree-ish (also treeish)::\n-\tA <<def_tree_object,tree object>> or an <<def_object,object>>\n-\tthat can be recursively dereferenced to a tree object.\n-\tDereferencing a <<def_commit_object,commit object>> yields the\n-\ttree object corresponding to the <<def_revision,revision>>'s\n-\ttop <<def_directory,directory>>.\n+\tA <<def_tree_object,tree object>> or an <<def_object,object>> that can\n+\tbe recursively <<def_dereference,dereferenced>> to a tree object.\n+\tDereferencing a <<def_commit_object,commit object>> yields the tree\n+\tobject corresponding to the <<def_revision,revision>>'s top\n+\t<<def_directory,directory>>.\n \tThe following are all tree-ishes:\n \ta <<def_commit-ish,commit-ish>>,\n \ta tree object,\n\nbase-commit: dadef801b365989099a9929e995589e455c51fed\n-- \ngitgitgadget\n"},{"id":"484684","messageId":"xmqq1qcyxxri.fsf@gitster.g","threadId":"60499","inReplyTo":"pull.1610.git.1699574277143.gitgitgadget@gmail.com","subject":"Re: [PATCH] glossary: add definitions for dereference & peel","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-11-10T00:22:41Z","receivedAt":"2023-11-10T00:22:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Victoria Dye via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> @@ -125,6 +124,24 @@ to point at the new commit.\n>  \tdangling object has no references to it from any\n>  \treference or <<def_object,object>> in the <<def_repository,repository>>.\n>  \n> +[[def_dereference]]dereference::\n> +\tReferring to a <<def_symref,symbolic ref>>: the action of accessing the\n> +\t<<def_ref,reference>> pointed at by a symbolic ref. Recursive\n> +\tdereferencing involves repeating the aforementioned process on the\n> +\tresulting ref until a non-symbolic reference is found.\n> ++\n> +Referring to a <<def_tag_object,tag object>>: the action of accessing the\n> +<<def_object,object>> a tag points at. Tags are recursively dereferenced by\n> +repeating the operation on the result object until the result has either a\n> +specified <<def_object_type,object type>> (where applicable) or any non-\"tag\"\n> +object type.\n> ++\n\nAll of the above makes sense.\n\nI would casually mention \"peeling\" here with cross reference,\nif I were writing this section.  There already is enough cross\nreference in the other direction pointing this way.\n\n> +Referring to a <<def_commit_object,commit object>>: the action of accessing\n> +the commit's tree object. Commits cannot be dereferenced recursively.\n\nI personally consider this is weird misuse of the verb and is rarely\nused, but we see it in the description of tree-ish below.\n\n> +Unless otherwise specified, \"dereferencing\" as it used in the context of Git\n> +commands or protocols is implicitly recursive.\n\nNice to see this spelled out like this.\n\n> @@ -444,6 +461,12 @@ exclude;;\n>  \tof the logical predecessor(s) in the line of development, i.e. its\n>  \tparents.\n>  \n> +[[def_peel]]peel::\n> +\tSynonym for object <<def_dereference,dereference>>. Most commonly used\n> +\tin the context of tags, where it refers to the process of recursively\n> +\tdereferencing a <<def_tag_object,tag object>> until the result object's\n> +\t<<def_object_type,type>> is something other than \"tag\".\n\n\"object dereference\" is not defined anywhere (yet).  \"Most commonly\nused in the context of tags\" implies that objects other than tags\ncan be \"peeled\" and \"object dereference\" is a word to refer to\npeeling either \"commit\" or \"tag\", but we would want to be a bit more\nclear and explicit.  Let's either define \"object dereference\", or\nbetter yet, avoid saying \"object dereference\" here and instead say\nsomething like: \"Synonym for dereference when used on tags and\ncommits\".\n\nI've never seen \"peel\" used for commits, though.  So another\nimprovement might be to say \"peel\" is \"an act of dereferencing a\ntag\" here.\n\nThanks.\n"},{"id":"484689","messageId":"xmqqa5rmw5ff.fsf@gitster.g","threadId":"60499","inReplyTo":"xmqq1qcyxxri.fsf@gitster.g","subject":"Re: [PATCH] glossary: add definitions for dereference & peel","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-11-10T05:20:04Z","receivedAt":"2023-11-10T06:16:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> I've never seen \"peel\" used for commits, though.  So another\n> improvement might be to say \"peel\" is \"an act of dereferencing a\n> tag\" here.\n\nI am reasonably sure I was the one who coined the term \"peel\", and\nthe picture I had in mind when I used it was to peel an onion, which\ninherently was about unwrapping many levels repeatedly.  I think\nthat is why it felt strange to see \"peel\" used in the context of\nusing a commit as a tree-ish, which (as your documentation update\nclearly said) is doable only once.\n\n"},{"id":"484698","messageId":"39db75f3-1496-49fc-a346-010ff8ef093c@app.fastmail.com","threadId":"60499","inReplyTo":"pull.1610.git.1699574277143.gitgitgadget@gmail.com","subject":"Re: [PATCH] glossary: add definitions for dereference & peel","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-11-10T08:28:53Z","receivedAt":"2023-11-10T08:29:16Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Fri, Nov 10, 2023, at 00:57, Victoria Dye via GitGitGadget wrote:\n> +[[def_peel]]peel::\n> +\tSynonym for object <<def_dereference,dereference>>. Most commonly used\n> +\tin the context of tags, where it refers to the process of recursively\n> +\tdereferencing a <<def_tag_object,tag object>> until the result object's\n> +\t<<def_object_type,type>> is something other than \"tag\".\n\nAs a user I like that this is classified as a synonym. Because if I wanted\nto ask StackOverflow about how to get to the commit that a tag points to\nthen I would use the term “dereference a tag”.\n\n-- \nKristoffer Haugsbakk\n"},{"id":"484824","messageId":"pull.1610.v2.git.1699917471769.gitgitgadget@gmail.com","threadId":"60499","inReplyTo":"pull.1610.git.1699574277143.gitgitgadget@gmail.com","subject":"[PATCH v2] glossary: add definitions for dereference & peel","fromName":"Victoria Dye via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-11-13T23:17:51Z","receivedAt":"2023-11-13T23:17:57Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"From: Victoria Dye <vdye@github.com>\n\nAdd 'gitglossary' definitions for \"dereference\" (as it used for both symrefs\nand objects) and \"peel\". These terms are used in options and documentation\nthroughout Git, but they are not clearly defined anywhere and the behavior\nthey refer to depends heavily on context. Provide explicit definitions to\nclarify existing documentation to users and help contributors to use the\nmost appropriate terminology possible in their additions to Git.\n\nUpdate other definitions in the glossary that use the term \"dereference\" to\nlink to 'def_dereference'.\n\nSigned-off-by: Victoria Dye <vdye@github.com>\n---\n    glossary: add definitions for dereference & peel\n    \n    As promised in [1], this patch adds definitions for \"peel\" and\n    \"dereference\" in the glossary, based on how they're currently used\n    throughout Git. As a result, the definitions are somewhat broad\n    (although I did my best to explicitly describe the different contexts in\n    which they're used). My hope is that this will at least reduce confusion\n    around this terminology. These definitions can also serve as a starting\n    point if, in the future, another contributor wants to deprecate certain\n    usages of these terms to make them less ambiguous.\n    \n     * Victoria\n    \n    [1]\n    https://lore.kernel.org/git/21dfe606-39f5-4154-aaa4-695e5f6f784d@github.com/\n    \n    \n    Changes since V1\n    ================\n    \n     * Removed references to \"peeling\" a commit; the updated definition\n       discusses \"peeling\" only in the context of tags.\n     * Added a cross-link from \"dereference\" to \"peel\" (one already existed\n       for \"peel\" to \"dereference\").\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1610%2Fvdye%2Fvdye%2Fglossary-peel-dereference-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1610/vdye/vdye/glossary-peel-dereference-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1610\n\nRange-diff vs v1:\n\n 1:  e40fc3e5e04 ! 1:  4d9e0d7fc81 glossary: add definitions for dereference & peel\n     @@ Documentation/glossary-content.txt: to point at the new commit.\n      +<<def_object,object>> a tag points at. Tags are recursively dereferenced by\n      +repeating the operation on the result object until the result has either a\n      +specified <<def_object_type,object type>> (where applicable) or any non-\"tag\"\n     -+object type.\n     ++object type. A synonym for \"recursive dereference\" in the context of tags is\n     ++\"<<def_peel,peel>>\".\n      ++\n      +Referring to a <<def_commit_object,commit object>>: the action of accessing\n      +the commit's tree object. Commits cannot be dereferenced recursively.\n     @@ Documentation/glossary-content.txt: exclude;;\n       \tparents.\n       \n      +[[def_peel]]peel::\n     -+\tSynonym for object <<def_dereference,dereference>>. Most commonly used\n     -+\tin the context of tags, where it refers to the process of recursively\n     -+\tdereferencing a <<def_tag_object,tag object>> until the result object's\n     -+\t<<def_object_type,type>> is something other than \"tag\".\n     ++\tThe action of recursively <<def_dereference,dereferencing>> a\n     ++\t<<def_tag_object,tag object>>.\n      +\n       [[def_pickaxe]]pickaxe::\n       \tThe term <<def_pickaxe,pickaxe>> refers to an option to the diffcore\n\n\n Documentation/glossary-content.txt | 49 +++++++++++++++++++++---------\n 1 file changed, 35 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 65c89e7b3eb..59d8ab85721 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -98,9 +98,8 @@ to point at the new commit.\n \trevision.\n \n [[def_commit-ish]]commit-ish (also committish)::\n-\tA <<def_commit_object,commit object>> or an\n-\t<<def_object,object>> that can be recursively dereferenced to\n-\ta commit object.\n+\tA <<def_commit_object,commit object>> or an <<def_object,object>> that\n+\tcan be recursively <<def_dereference,dereferenced>> to a commit object.\n \tThe following are all commit-ishes:\n \ta commit object,\n \ta <<def_tag_object,tag object>> that points to a commit\n@@ -125,6 +124,25 @@ to point at the new commit.\n \tdangling object has no references to it from any\n \treference or <<def_object,object>> in the <<def_repository,repository>>.\n \n+[[def_dereference]]dereference::\n+\tReferring to a <<def_symref,symbolic ref>>: the action of accessing the\n+\t<<def_ref,reference>> pointed at by a symbolic ref. Recursive\n+\tdereferencing involves repeating the aforementioned process on the\n+\tresulting ref until a non-symbolic reference is found.\n++\n+Referring to a <<def_tag_object,tag object>>: the action of accessing the\n+<<def_object,object>> a tag points at. Tags are recursively dereferenced by\n+repeating the operation on the result object until the result has either a\n+specified <<def_object_type,object type>> (where applicable) or any non-\"tag\"\n+object type. A synonym for \"recursive dereference\" in the context of tags is\n+\"<<def_peel,peel>>\".\n++\n+Referring to a <<def_commit_object,commit object>>: the action of accessing\n+the commit's tree object. Commits cannot be dereferenced recursively.\n++\n+Unless otherwise specified, \"dereferencing\" as it used in the context of Git\n+commands or protocols is implicitly recursive.\n+\n [[def_detached_HEAD]]detached HEAD::\n \tNormally the <<def_HEAD,HEAD>> stores the name of a\n \t<<def_branch,branch>>, and commands that operate on the\n@@ -444,6 +462,10 @@ exclude;;\n \tof the logical predecessor(s) in the line of development, i.e. its\n \tparents.\n \n+[[def_peel]]peel::\n+\tThe action of recursively <<def_dereference,dereferencing>> a\n+\t<<def_tag_object,tag object>>.\n+\n [[def_pickaxe]]pickaxe::\n \tThe term <<def_pickaxe,pickaxe>> refers to an option to the diffcore\n \troutines that help select changes that add or delete a given text\n@@ -620,12 +642,11 @@ The most notable example is `HEAD`.\n \tcopies of) commit objects of the contained submodules.\n \n [[def_symref]]symref::\n-\tSymbolic reference: instead of containing the <<def_SHA1,SHA-1>>\n-\tid itself, it is of the format 'ref: refs/some/thing' and when\n-\treferenced, it recursively dereferences to this reference.\n-\t'<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic\n-\treferences are manipulated with the linkgit:git-symbolic-ref[1]\n-\tcommand.\n+\tSymbolic reference: instead of containing the <<def_SHA1,SHA-1>> id\n+\titself, it is of the format 'ref: refs/some/thing' and when referenced,\n+\tit recursively <<def_dereference,dereferences>> to this reference.\n+\t'<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic references\n+\tare manipulated with the linkgit:git-symbolic-ref[1] command.\n \n [[def_tag]]tag::\n \tA <<def_ref,ref>> under `refs/tags/` namespace that points to an\n@@ -661,11 +682,11 @@ The most notable example is `HEAD`.\n \t<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.\n \n [[def_tree-ish]]tree-ish (also treeish)::\n-\tA <<def_tree_object,tree object>> or an <<def_object,object>>\n-\tthat can be recursively dereferenced to a tree object.\n-\tDereferencing a <<def_commit_object,commit object>> yields the\n-\ttree object corresponding to the <<def_revision,revision>>'s\n-\ttop <<def_directory,directory>>.\n+\tA <<def_tree_object,tree object>> or an <<def_object,object>> that can\n+\tbe recursively <<def_dereference,dereferenced>> to a tree object.\n+\tDereferencing a <<def_commit_object,commit object>> yields the tree\n+\tobject corresponding to the <<def_revision,revision>>'s top\n+\t<<def_directory,directory>>.\n \tThe following are all tree-ishes:\n \ta <<def_commit-ish,commit-ish>>,\n \ta tree object,\n\nbase-commit: dadef801b365989099a9929e995589e455c51fed\n-- \ngitgitgadget\n"},{"id":"484845","messageId":"xmqq1qct0wie.fsf@gitster.g","threadId":"60499","inReplyTo":"pull.1610.v2.git.1699917471769.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] glossary: add definitions for dereference & peel","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-11-14T04:49:45Z","receivedAt":"2023-11-14T04:49:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Victoria Dye via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>      * Removed references to \"peeling\" a commit; the updated definition\n>        discusses \"peeling\" only in the context of tags.\n>      * Added a cross-link from \"dereference\" to \"peel\" (one already existed\n>        for \"peel\" to \"dereference\").\n> ...\n> +[[def_peel]]peel::\n> +\tThe action of recursively <<def_dereference,dereferencing>> a\n> +\t<<def_tag_object,tag object>>.\n> +\n\nThis was a bit surprising to me as I thought we would say \"peel the\ntag once\" vs \"peel the tag repeatedly\", but upon inspecting the\nexisting code, documentation, and messages, we seem to mean by \"to\npeel\" to dereference a tag repeatedly until it no longer is a tag,\nwhich the new entry above exactly is (although \"until the non-tag\nobject is revealed\" is missing).\n\nThanks.  Will queue.\n\n"}]}