[PATCH] glossary: add definitions for dereference & peel

[PATCH] glossary: add definitions for dereference & peel

[Victoria Dye via GitGitGadget]

From: Victoria Dye <vdye@github.com>

Add 'gitglossary' definitions for "dereference" (as it used for both symrefs
and objects) and "peel". These terms are used in options and documentation
throughout Git, but they are not clearly defined anywhere and the behavior
they refer to depends heavily on context. Provide explicit definitions to
clarify existing documentation to users and help contributors to use the
most appropriate terminology possible in their additions to Git.

Update other definitions in the glossary that use the term "dereference" to
link to 'def_dereference'.

Signed-off-by: Victoria Dye <vdye@github.com>
---
    glossary: add definitions for dereference & peel
    
    As promised in [1], this patch adds definitions for "peel" and
    "dereference" in the glossary, based on how they're currently used
    throughout Git. As a result, the definitions are somewhat broad
    (although I did my best to explicitly describe the different contexts in
    which they're used). My hope is that this will at least reduce confusion
    around this terminology. These definitions can also serve as a starting
    point if, in the future, another contributor wants to deprecate certain
    usages of these terms to make them less ambiguous.
    
     * Victoria
    
    [1]
    https://lore.kernel.org/git/21dfe606-39f5-4154-aaa4-695e5f6f784d@github.com/

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1610%2Fvdye%2Fvdye%2Fglossary-peel-dereference-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1610/vdye/vdye/glossary-peel-dereference-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1610

 Documentation/glossary-content.txt | 50 +++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 14 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 65c89e7b3eb..41dd5721def 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -98,9 +98,8 @@ to point at the new commit.
 	revision.
 
 [[def_commit-ish]]commit-ish (also committish)::
-	A <<def_commit_object,commit object>> or an
-	<<def_object,object>> that can be recursively dereferenced to
-	a commit object.
+	A <<def_commit_object,commit object>> or an <<def_object,object>> that
+	can be recursively <<def_dereference,dereferenced>> to a commit object.
 	The following are all commit-ishes:
 	a commit object,
 	a <<def_tag_object,tag object>> that points to a commit
@@ -125,6 +124,24 @@ to point at the new commit.
 	dangling object has no references to it from any
 	reference or <<def_object,object>> in the <<def_repository,repository>>.
 
+[[def_dereference]]dereference::
+	Referring to a <<def_symref,symbolic ref>>: the action of accessing the
+	<<def_ref,reference>> pointed at by a symbolic ref. Recursive
+	dereferencing involves repeating the aforementioned process on the
+	resulting ref until a non-symbolic reference is found.
++
+Referring to a <<def_tag_object,tag object>>: the action of accessing the
+<<def_object,object>> a tag points at. Tags are recursively dereferenced by
+repeating the operation on the result object until the result has either a
+specified <<def_object_type,object type>> (where applicable) or any non-"tag"
+object type.
++
+Referring to a <<def_commit_object,commit object>>: the action of accessing
+the commit's tree object. Commits cannot be dereferenced recursively.
++
+Unless otherwise specified, "dereferencing" as it used in the context of Git
+commands or protocols is implicitly recursive.
+
 [[def_detached_HEAD]]detached HEAD::
 	Normally the <<def_HEAD,HEAD>> stores the name of a
 	<<def_branch,branch>>, and commands that operate on the
@@ -444,6 +461,12 @@ exclude;;
 	of the logical predecessor(s) in the line of development, i.e. its
 	parents.
 
+[[def_peel]]peel::
+	Synonym for object <<def_dereference,dereference>>. Most commonly used
+	in the context of tags, where it refers to the process of recursively
+	dereferencing a <<def_tag_object,tag object>> until the result object's
+	<<def_object_type,type>> is something other than "tag".
+
 [[def_pickaxe]]pickaxe::
 	The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore
 	routines that help select changes that add or delete a given text
@@ -620,12 +643,11 @@ The most notable example is `HEAD`.
 	copies of) commit objects of the contained submodules.
 
 [[def_symref]]symref::
-	Symbolic reference: instead of containing the <<def_SHA1,SHA-1>>
-	id itself, it is of the format 'ref: refs/some/thing' and when
-	referenced, it recursively dereferences to this reference.
-	'<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic
-	references are manipulated with the linkgit:git-symbolic-ref[1]
-	command.
+	Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> id
+	itself, it is of the format 'ref: refs/some/thing' and when referenced,
+	it recursively <<def_dereference,dereferences>> to this reference.
+	'<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic references
+	are manipulated with the linkgit:git-symbolic-ref[1] command.
 
 [[def_tag]]tag::
 	A <<def_ref,ref>> under `refs/tags/` namespace that points to an
@@ -661,11 +683,11 @@ The most notable example is `HEAD`.
 	<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.
 
 [[def_tree-ish]]tree-ish (also treeish)::
-	A <<def_tree_object,tree object>> or an <<def_object,object>>
-	that can be recursively dereferenced to a tree object.
-	Dereferencing a <<def_commit_object,commit object>> yields the
-	tree object corresponding to the <<def_revision,revision>>'s
-	top <<def_directory,directory>>.
+	A <<def_tree_object,tree object>> or an <<def_object,object>> that can
+	be recursively <<def_dereference,dereferenced>> to a tree object.
+	Dereferencing a <<def_commit_object,commit object>> yields the tree
+	object corresponding to the <<def_revision,revision>>'s top
+	<<def_directory,directory>>.
 	The following are all tree-ishes:
 	a <<def_commit-ish,commit-ish>>,
 	a tree object,

base-commit: dadef801b365989099a9929e995589e455c51fed
-- 
gitgitgadget

Re: [PATCH] glossary: add definitions for dereference & peel

[Junio C Hamano]

"Victoria Dye via GitGitGadget" <gitgitgadget@gmail.com> writes:

> @@ -125,6 +124,24 @@ to point at the new commit.
>  	dangling object has no references to it from any
>  	reference or <<def_object,object>> in the <<def_repository,repository>>.
>  
> +[[def_dereference]]dereference::
> +	Referring to a <<def_symref,symbolic ref>>: the action of accessing the
> +	<<def_ref,reference>> pointed at by a symbolic ref. Recursive
> +	dereferencing involves repeating the aforementioned process on the
> +	resulting ref until a non-symbolic reference is found.
> ++
> +Referring to a <<def_tag_object,tag object>>: the action of accessing the
> +<<def_object,object>> a tag points at. Tags are recursively dereferenced by
> +repeating the operation on the result object until the result has either a
> +specified <<def_object_type,object type>> (where applicable) or any non-"tag"
> +object type.
> ++

All of the above makes sense.

I would casually mention "peeling" here with cross reference,
if I were writing this section.  There already is enough cross
reference in the other direction pointing this way.

> +Referring to a <<def_commit_object,commit object>>: the action of accessing
> +the commit's tree object. Commits cannot be dereferenced recursively.

I personally consider this is weird misuse of the verb and is rarely
used, but we see it in the description of tree-ish below.

> +Unless otherwise specified, "dereferencing" as it used in the context of Git
> +commands or protocols is implicitly recursive.

Nice to see this spelled out like this.

> @@ -444,6 +461,12 @@ exclude;;
>  	of the logical predecessor(s) in the line of development, i.e. its
>  	parents.
>  
> +[[def_peel]]peel::
> +	Synonym for object <<def_dereference,dereference>>. Most commonly used
> +	in the context of tags, where it refers to the process of recursively
> +	dereferencing a <<def_tag_object,tag object>> until the result object's
> +	<<def_object_type,type>> is something other than "tag".

"object dereference" is not defined anywhere (yet).  "Most commonly
used in the context of tags" implies that objects other than tags
can be "peeled" and "object dereference" is a word to refer to
peeling either "commit" or "tag", but we would want to be a bit more
clear and explicit.  Let's either define "object dereference", or
better yet, avoid saying "object dereference" here and instead say
something like: "Synonym for dereference when used on tags and
commits".

I've never seen "peel" used for commits, though.  So another
improvement might be to say "peel" is "an act of dereferencing a
tag" here.

Thanks.

Re: [PATCH] glossary: add definitions for dereference & peel

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> I've never seen "peel" used for commits, though.  So another
> improvement might be to say "peel" is "an act of dereferencing a
> tag" here.

I am reasonably sure I was the one who coined the term "peel", and
the picture I had in mind when I used it was to peel an onion, which
inherently was about unwrapping many levels repeatedly.  I think
that is why it felt strange to see "peel" used in the context of
using a commit as a tree-ish, which (as your documentation update
clearly said) is doable only once.

Re: [PATCH] glossary: add definitions for dereference & peel

[Kristoffer Haugsbakk]

On Fri, Nov 10, 2023, at 00:57, Victoria Dye via GitGitGadget wrote:
> +[[def_peel]]peel::
> +	Synonym for object <<def_dereference,dereference>>. Most commonly used
> +	in the context of tags, where it refers to the process of recursively
> +	dereferencing a <<def_tag_object,tag object>> until the result object's
> +	<<def_object_type,type>> is something other than "tag".

As a user I like that this is classified as a synonym. Because if I wanted
to ask StackOverflow about how to get to the commit that a tag points to
then I would use the term “dereference a tag”.

-- 
Kristoffer Haugsbakk

[PATCH v2] glossary: add definitions for dereference & peel

[Victoria Dye via GitGitGadget]

From: Victoria Dye <vdye@github.com>

Add 'gitglossary' definitions for "dereference" (as it used for both symrefs
and objects) and "peel". These terms are used in options and documentation
throughout Git, but they are not clearly defined anywhere and the behavior
they refer to depends heavily on context. Provide explicit definitions to
clarify existing documentation to users and help contributors to use the
most appropriate terminology possible in their additions to Git.

Update other definitions in the glossary that use the term "dereference" to
link to 'def_dereference'.

Signed-off-by: Victoria Dye <vdye@github.com>
---
    glossary: add definitions for dereference & peel
    
    As promised in [1], this patch adds definitions for "peel" and
    "dereference" in the glossary, based on how they're currently used
    throughout Git. As a result, the definitions are somewhat broad
    (although I did my best to explicitly describe the different contexts in
    which they're used). My hope is that this will at least reduce confusion
    around this terminology. These definitions can also serve as a starting
    point if, in the future, another contributor wants to deprecate certain
    usages of these terms to make them less ambiguous.
    
     * Victoria
    
    [1]
    https://lore.kernel.org/git/21dfe606-39f5-4154-aaa4-695e5f6f784d@github.com/
    
    
    Changes since V1
    ================
    
     * Removed references to "peeling" a commit; the updated definition
       discusses "peeling" only in the context of tags.
     * Added a cross-link from "dereference" to "peel" (one already existed
       for "peel" to "dereference").

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1610%2Fvdye%2Fvdye%2Fglossary-peel-dereference-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1610/vdye/vdye/glossary-peel-dereference-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1610

Range-diff vs v1:

 1:  e40fc3e5e04 ! 1:  4d9e0d7fc81 glossary: add definitions for dereference & peel
     @@ Documentation/glossary-content.txt: to point at the new commit.
      +<<def_object,object>> a tag points at. Tags are recursively dereferenced by
      +repeating the operation on the result object until the result has either a
      +specified <<def_object_type,object type>> (where applicable) or any non-"tag"
     -+object type.
     ++object type. A synonym for "recursive dereference" in the context of tags is
     ++"<<def_peel,peel>>".
      ++
      +Referring to a <<def_commit_object,commit object>>: the action of accessing
      +the commit's tree object. Commits cannot be dereferenced recursively.
     @@ Documentation/glossary-content.txt: exclude;;
       	parents.
       
      +[[def_peel]]peel::
     -+	Synonym for object <<def_dereference,dereference>>. Most commonly used
     -+	in the context of tags, where it refers to the process of recursively
     -+	dereferencing a <<def_tag_object,tag object>> until the result object's
     -+	<<def_object_type,type>> is something other than "tag".
     ++	The action of recursively <<def_dereference,dereferencing>> a
     ++	<<def_tag_object,tag object>>.
      +
       [[def_pickaxe]]pickaxe::
       	The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore


 Documentation/glossary-content.txt | 49 +++++++++++++++++++++---------
 1 file changed, 35 insertions(+), 14 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 65c89e7b3eb..59d8ab85721 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -98,9 +98,8 @@ to point at the new commit.
 	revision.
 
 [[def_commit-ish]]commit-ish (also committish)::
-	A <<def_commit_object,commit object>> or an
-	<<def_object,object>> that can be recursively dereferenced to
-	a commit object.
+	A <<def_commit_object,commit object>> or an <<def_object,object>> that
+	can be recursively <<def_dereference,dereferenced>> to a commit object.
 	The following are all commit-ishes:
 	a commit object,
 	a <<def_tag_object,tag object>> that points to a commit
@@ -125,6 +124,25 @@ to point at the new commit.
 	dangling object has no references to it from any
 	reference or <<def_object,object>> in the <<def_repository,repository>>.
 
+[[def_dereference]]dereference::
+	Referring to a <<def_symref,symbolic ref>>: the action of accessing the
+	<<def_ref,reference>> pointed at by a symbolic ref. Recursive
+	dereferencing involves repeating the aforementioned process on the
+	resulting ref until a non-symbolic reference is found.
++
+Referring to a <<def_tag_object,tag object>>: the action of accessing the
+<<def_object,object>> a tag points at. Tags are recursively dereferenced by
+repeating the operation on the result object until the result has either a
+specified <<def_object_type,object type>> (where applicable) or any non-"tag"
+object type. A synonym for "recursive dereference" in the context of tags is
+"<<def_peel,peel>>".
++
+Referring to a <<def_commit_object,commit object>>: the action of accessing
+the commit's tree object. Commits cannot be dereferenced recursively.
++
+Unless otherwise specified, "dereferencing" as it used in the context of Git
+commands or protocols is implicitly recursive.
+
 [[def_detached_HEAD]]detached HEAD::
 	Normally the <<def_HEAD,HEAD>> stores the name of a
 	<<def_branch,branch>>, and commands that operate on the
@@ -444,6 +462,10 @@ exclude;;
 	of the logical predecessor(s) in the line of development, i.e. its
 	parents.
 
+[[def_peel]]peel::
+	The action of recursively <<def_dereference,dereferencing>> a
+	<<def_tag_object,tag object>>.
+
 [[def_pickaxe]]pickaxe::
 	The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore
 	routines that help select changes that add or delete a given text
@@ -620,12 +642,11 @@ The most notable example is `HEAD`.
 	copies of) commit objects of the contained submodules.
 
 [[def_symref]]symref::
-	Symbolic reference: instead of containing the <<def_SHA1,SHA-1>>
-	id itself, it is of the format 'ref: refs/some/thing' and when
-	referenced, it recursively dereferences to this reference.
-	'<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic
-	references are manipulated with the linkgit:git-symbolic-ref[1]
-	command.
+	Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> id
+	itself, it is of the format 'ref: refs/some/thing' and when referenced,
+	it recursively <<def_dereference,dereferences>> to this reference.
+	'<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic references
+	are manipulated with the linkgit:git-symbolic-ref[1] command.
 
 [[def_tag]]tag::
 	A <<def_ref,ref>> under `refs/tags/` namespace that points to an
@@ -661,11 +682,11 @@ The most notable example is `HEAD`.
 	<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.
 
 [[def_tree-ish]]tree-ish (also treeish)::
-	A <<def_tree_object,tree object>> or an <<def_object,object>>
-	that can be recursively dereferenced to a tree object.
-	Dereferencing a <<def_commit_object,commit object>> yields the
-	tree object corresponding to the <<def_revision,revision>>'s
-	top <<def_directory,directory>>.
+	A <<def_tree_object,tree object>> or an <<def_object,object>> that can
+	be recursively <<def_dereference,dereferenced>> to a tree object.
+	Dereferencing a <<def_commit_object,commit object>> yields the tree
+	object corresponding to the <<def_revision,revision>>'s top
+	<<def_directory,directory>>.
 	The following are all tree-ishes:
 	a <<def_commit-ish,commit-ish>>,
 	a tree object,

base-commit: dadef801b365989099a9929e995589e455c51fed
-- 
gitgitgadget

Re: [PATCH v2] glossary: add definitions for dereference & peel

[Junio C Hamano]

"Victoria Dye via GitGitGadget" <gitgitgadget@gmail.com> writes:

>      * Removed references to "peeling" a commit; the updated definition
>        discusses "peeling" only in the context of tags.
>      * Added a cross-link from "dereference" to "peel" (one already existed
>        for "peel" to "dereference").
> ...
> +[[def_peel]]peel::
> +	The action of recursively <<def_dereference,dereferencing>> a
> +	<<def_tag_object,tag object>>.
> +

This was a bit surprising to me as I thought we would say "peel the
tag once" vs "peel the tag repeatedly", but upon inspecting the
existing code, documentation, and messages, we seem to mean by "to
peel" to dereference a tag repeatedly until it no longer is a tag,
which the new entry above exactly is (although "until the non-tag
object is revealed" is missing).

Thanks.  Will queue.