glossary: add definitions for dereference & peel
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Victoria Dye committed
Nov 13, 2023 at 23:17 UTC
893dce2ffbd4e38191f10c67781518acbc3f7b32
1 file changed
+35
-14
Documentation/glossary-content.txt
+35
-14
@@ -98,9 +98,8 @@ to point at the new commit.
98
revision.
99
100
[[def_commit-ish]]commit-ish (also committish)::
101
- A <<def_commit_object,commit object>> or an
102
- <<def_object,object>> that can be recursively dereferenced to
103
- a commit object.
101
+ A <<def_commit_object,commit object>> or an <<def_object,object>> that
102
+ can be recursively <<def_dereference,dereferenced>> to a commit object.
103
The following are all commit-ishes:
104
a commit object,
105
a <<def_tag_object,tag object>> that points to a commit
@@ -125,6 +124,25 @@ to point at the new commit.
124
dangling object has no references to it from any
125
reference or <<def_object,object>> in the <<def_repository,repository>>.
126
127
+[[def_dereference]]dereference::
128
+ Referring to a <<def_symref,symbolic ref>>: the action of accessing the
129
+ <<def_ref,reference>> pointed at by a symbolic ref. Recursive
130
+ dereferencing involves repeating the aforementioned process on the
131
+ resulting ref until a non-symbolic reference is found.
132
++
133
+Referring to a <<def_tag_object,tag object>>: the action of accessing the
134
+<<def_object,object>> a tag points at. Tags are recursively dereferenced by
135
+repeating the operation on the result object until the result has either a
136
+specified <<def_object_type,object type>> (where applicable) or any non-"tag"
137
+object type. A synonym for "recursive dereference" in the context of tags is
138
+"<<def_peel,peel>>".
139
++
140
+Referring to a <<def_commit_object,commit object>>: the action of accessing
141
+the commit's tree object. Commits cannot be dereferenced recursively.
142
++
143
+Unless otherwise specified, "dereferencing" as it used in the context of Git
144
+commands or protocols is implicitly recursive.
145
+
146
[[def_detached_HEAD]]detached HEAD::
147
Normally the <<def_HEAD,HEAD>> stores the name of a
148
<<def_branch,branch>>, and commands that operate on the
@@ -444,6 +462,10 @@ exclude;;
462
of the logical predecessor(s) in the line of development, i.e. its
463
parents.
464
465
+[[def_peel]]peel::
466
+ The action of recursively <<def_dereference,dereferencing>> a
467
+ <<def_tag_object,tag object>>.
468
+
469
[[def_pickaxe]]pickaxe::
470
The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore
471
routines that help select changes that add or delete a given text
@@ -620,12 +642,11 @@ The most notable example is `HEAD`.
642
copies of) commit objects of the contained submodules.
643
644
[[def_symref]]symref::
623
- Symbolic reference: instead of containing the <<def_SHA1,SHA-1>>
624
- id itself, it is of the format 'ref: refs/some/thing' and when
625
- referenced, it recursively dereferences to this reference.
626
- '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic
627
- references are manipulated with the linkgit:git-symbolic-ref[1]
628
- command.
645
+ Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> id
646
+ itself, it is of the format 'ref: refs/some/thing' and when referenced,
647
+ it recursively <<def_dereference,dereferences>> to this reference.
648
+ '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic references
649
+ are manipulated with the linkgit:git-symbolic-ref[1] command.
650
651
[[def_tag]]tag::
652
A <<def_ref,ref>> under `refs/tags/` namespace that points to an
@@ -661,11 +682,11 @@ The most notable example is `HEAD`.
682
<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.
683
684
[[def_tree-ish]]tree-ish (also treeish)::
664
- A <<def_tree_object,tree object>> or an <<def_object,object>>
665
- that can be recursively dereferenced to a tree object.
666
- Dereferencing a <<def_commit_object,commit object>> yields the
667
- tree object corresponding to the <<def_revision,revision>>'s
668
- top <<def_directory,directory>>.
685
+ A <<def_tree_object,tree object>> or an <<def_object,object>> that can
686
+ be recursively <<def_dereference,dereferenced>> to a tree object.
687
+ Dereferencing a <<def_commit_object,commit object>> yields the tree
688
+ object corresponding to the <<def_revision,revision>>'s top
689
+ <<def_directory,directory>>.
690
The following are all tree-ishes:
691
a <<def_commit-ish,commit-ish>>,
692
a tree object,