[PATCH 0/4] documentation cleanups for <rev>^{<type>}

The documentation for the <rev>^{<type>} syntax (e.g.,
v1.8.3.1^{tree}) needed some fixing, and while I was at it I thought
I'd be pedantic about tree-ish.  Oh, and let's welcome "committish" to
the party!

-Richard


Richard Hansen (4):
  glossary: add 'treeish' as a synonym for 'tree-ish'
  glossary: define committish (a.k.a. commit-ish)
  glossary: more precise definition of tree-ish (a.k.a. treeish)
  revisions.txt: fix and clarify <rev>^{<type>}

 Documentation/glossary-content.txt | 29 +++++++++++++++++++++++++----
 Documentation/revisions.txt        | 12 ++++++++----
 2 files changed, 33 insertions(+), 8 deletions(-)

-- 
1.8.3.1

Signed-off-by: Richard Hansen <redacted>
---
 Documentation/glossary-content.txt | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 01365d9..a3cc003 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt

@@ -82,6 +82,17 @@ to point at the new commit.
 	to the top <<def_directory,directory>> of the stored
 	revision.
 
+[[def_committish]]committish (also commit-ish)::
+	A <<def_ref,ref>> pointing to an <<def_object,object>> that
+	can be recursively dereferenced to a
+	<<def_commit_object,commit object>>.
+	The following are all committishes:
+	a ref pointing to a commit object,
+	a ref pointing to a <<def_tag_object,tag object>> that points
+	to a commit object,
+	a ref pointing to a tag object that points to a tag object
+	that points to a commit object, etc.
+
 [[def_core_git]]core Git::
 	Fundamental data structures and utilities of Git. Exposes only limited
 	source code management tools.

-- 
1.8.3.1

The documentation contains a mix of the two spellings, and including
both makes it possible for users to search the glossary with their
spelling of choice.

Signed-off-by: Richard Hansen <redacted>
---
 Documentation/glossary-content.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index db2a74d..01365d9 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt

@@ -486,7 +486,7 @@ should not be combined with other pathspec.
 	with refs to the associated blob and/or tree objects. A
 	<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.
 
-[[def_tree-ish]]tree-ish::
+[[def_tree-ish]]tree-ish (also treeish)::
 	A <<def_ref,ref>> pointing to either a <<def_commit_object,commit
 	object>>, a <<def_tree_object,tree object>>, or a <<def_tag_object,tag
 	object>> pointing to a tag or commit or tree object.

-- 
1.8.3.1

Mention dereferencing, and that a commit dereferences to a tree, to
support gitrevisions(7) and rev-parse's error messages.

Signed-off-by: Richard Hansen <redacted>
---
 Documentation/glossary-content.txt | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index a3cc003..9a50fe1 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt

@@ -498,9 +498,19 @@ should not be combined with other pathspec.
 	<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.
 
 [[def_tree-ish]]tree-ish (also treeish)::
-	A <<def_ref,ref>> pointing to either a <<def_commit_object,commit
-	object>>, a <<def_tree_object,tree object>>, or a <<def_tag_object,tag
-	object>> pointing to a tag or commit or tree object.
+	A <<def_ref,ref>> pointing to an <<def_object,object>> that
+	can be recursively dereferenced to a
+	<<def_tree_object,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_committish,committish>>,
+	a ref pointing to a tree object,
+	a ref pointing to a <<def_tag_object,tag object>> that points
+	to a tree object,
+	a ref pointing to a tag object that points to a tag object
+	that points to a tree object, etc.
 
 [[def_unmerged_index]]unmerged index::
 	An <<def_index,index>> which contains unmerged

-- 
1.8.3.1

If possible, <rev> will be dereferenced even if it is not a tag type
(e.g., commit dereferenced to a tree).

Signed-off-by: Richard Hansen <redacted>
---
 Documentation/revisions.txt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 09896a3..bf563cf 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt

@@ -114,10 +114,14 @@ some output processing may assume ref names in UTF-8.
 
 '<rev>{caret}\{<type>\}', e.g. 'v0.99.8{caret}\{commit\}'::
   A suffix '{caret}' followed by an object type name enclosed in
-  brace pair means the object
-  could be a tag, and dereference the tag recursively until an
-  object of that type is found or the object cannot be
-  dereferenced anymore (in which case, barf).  '<rev>{caret}0'
+  brace pair means dereference the object at '<rev>' recursively until
+  an object of type '<type>' is found or the object cannot be
+  dereferenced anymore (in which case, barf).
+  For example, if '<rev>' is a committish, '<rev>{caret}\{commit\}'
+  specifies the corresponding commit object.
+  Similarly, if '<rev>' is a tree-ish, '<rev>{caret}\{tree\}'
+  specifies the corresponding tree object.
+  '<rev>{caret}0'
   is a short-hand for '<rev>{caret}\{commit\}'.
 +
 'rev{caret}\{object\}' can be used to make sure 'rev' names an

-- 
1.8.3.1

Richard Hansen wrote:

+[[def_committish]]committish (also commit-ish)::

Good.

+       A <<def_ref,ref>> pointing to an <<def_object,object>> that
+       can be recursively dereferenced to a
+       <<def_commit_object,commit object>>.
+       The following are all committishes:
+       a ref pointing to a commit object,
+       a ref pointing to a <<def_tag_object,tag object>> that points
+       to a commit object,
+       a ref pointing to a tag object that points to a tag object
+       that points to a commit object, etc.

Is master~3 a committish?  What about :/foomery?  Look at the other
forms in gitrevisions(7); master:quuxery, master^{tree} are notable
exceptions.

Thanks.

On 2013-06-19 00:19, Ramkumar Ramachandra wrote:

Is master~3 a committish?  What about :/foomery?

Yes; as documented, both of those are refs that point to a commit.

Look at the other forms in gitrevisions(7); master:quuxery,
master^{tree} are notable exceptions.

gitrevisions(7) says that master:quuxery is a ref pointing to a blob or
tree, so it is not a committish.  However, if quuxery is a submodule, I
would expect master:quuxery to point to a commit object and thus be a
committish.  So perhaps the <rev>:<path> description in gitrevisions(7)
should be updated to accommodate submodules.

master^{tree} is guaranteed to be a tree (if such a tree exists), so it
is not a committish.

-Richard

Richard Hansen wrote:

On 2013-06-19 00:19, Ramkumar Ramachandra wrote:

quoted

Is master~3 a committish?  What about :/foomery?

Yes; as documented, both of those are refs that point to a commit.

From gitglossary(7):

ref
    A 40-byte hex representation of a SHA-1 or a name that denotes a
    particular object. They may be stored in a file under $GIT_DIR/refs/
    directory, or in the $GIT_DIR/packed-refs file.

Do master~3 and :/foomery qualify as refs?

quoted

Look at the other forms in gitrevisions(7); master:quuxery,
master^{tree} are notable exceptions.

gitrevisions(7) says that master:quuxery is a ref pointing to a blob or
tree, so it is not a committish.  However, if quuxery is a submodule, I
would expect master:quuxery to point to a commit object and thus be a
committish.  So perhaps the <rev>:<path> description in gitrevisions(7)
should be updated to accommodate submodules.

When quuxery is a submodule, master:quuxery refers to a commit object
that does not exist in the parent repository.  I don't know what we
gain by documenting a comittish you can't even `show`.

Hi,

Richard Hansen wrote:

Usually I would expect that the string "4d1c565" is not a ref, but the
glossary contains a different definition ("A 40-byte hex
representation of a SHA-1 or ...").  I guess we need a shorter name
for "extended SHA-1 syntax" (as described in gitrevisions(7)) that is
a little less confusing.

Perhaps we can sidestep the issue by saying

	A parameter pointing to an <<def_object,object>> that
	can be recursively dereferenced to ...

since the most common use of "commitish" is in describing a command's
syntax.  I'm tempted to go even further and just call that a "commit
parameter", explaining the more pedantic synonym here --- something
like

	[[def_commitish]]commitish (also commit-ish)::
		A commandline parameter to a command that requires a
		<<def_commit,commit>>.
	+
	The following are all commitishes: an expression (see
	linkgit:gitrevisions[7]) directly representing a commit object,
	an expression naming a tag that points to a commit object, a
	tag that points to a tag that points to a commit, etc.

Thanks,
Jonathan

On 2013-06-19 01:56, Ramkumar Ramachandra wrote:

From gitglossary(7):

ref
    A 40-byte hex representation of a SHA-1 or a name that denotes a
    particular object. They may be stored in a file under $GIT_DIR/refs/
    directory, or in the $GIT_DIR/packed-refs file.

Do master~3 and :/foomery qualify as refs?

Yes; they are names that denote a particular object.

quoted

quoted

Look at the other forms in gitrevisions(7); master:quuxery,
master^{tree} are notable exceptions.

gitrevisions(7) says that master:quuxery is a ref pointing to a blob or
tree, so it is not a committish.  However, if quuxery is a submodule, I
would expect master:quuxery to point to a commit object and thus be a
committish.  So perhaps the <rev>:<path> description in gitrevisions(7)
should be updated to accommodate submodules.

When quuxery is a submodule, master:quuxery refers to a commit object
that does not exist in the parent repository.  I don't know what we
gain by documenting a comittish you can't even `show`.

Fair point.

-Richard

On 2013-06-19 11:31, Richard Hansen wrote:

On 2013-06-19 01:56, Ramkumar Ramachandra wrote:

quoted

From gitglossary(7):

ref
    A 40-byte hex representation of a SHA-1 or a name that denotes a
    particular object. They may be stored in a file under $GIT_DIR/refs/
    directory, or in the $GIT_DIR/packed-refs file.

Do master~3 and :/foomery qualify as refs?

Yes; they are names that denote a particular object.

Hmm...  Maybe not.  There is no definition of "name" in gitglossary(7),
but there is "object name", and that says:

    object name
        The unique identifier of an object.  The hash of the object's
        contents using the Secure Hash Algorithm 1 and usually
        represented by the 40 character hexadecimal encoding of the
        hash of the object.

That definition excludes master~3 and :/foomery.  So perhaps we need a
clearer definition of "ref", or add a separate definition of "name" that
is distinct from "object name", or change the definition of "object
name" to be more general (and perhaps define "object ID" to take the
current definition of "object name"?).

In sha1_name.c, master~3 and :/foomery are considered to be "names".  I
think it'd be a good idea if gitglossary(7) matched the code, because
that's the vocabulary Git developers and power users will use.
Unfortunately, in my mind "name" has a connotation that doesn't quite
match what sha1_name.c considers to be a name (I think of "name" as an
arbitrary, more-or-less semanticless label attached to something for the
purpose of convenient identification; the stuff in gitrevisions(7) are
more like operators on a name).

Maybe "object specifier" ("objspec" for short) could be used to refer to
all the ways one could specify an object?  Similarly, commit
specifier/commitspec, tree specifier/treespec, etc.  A treeish would
then be defined as a treespec or something that can be dereferenced to a
treespec.


BTW, I'm not a huge fan of the current definition of "ref" in
gitglossary(7) because to me a ref is ONLY something in .git/refs (or
HEAD, FETCH_HEAD, etc.) -- NOT a SHA1.  But I used "ref" in the
definition of "committish" because that's how the definition of
"tree-ish" was worded.

It's also unfortunate that gitrevisions(7) isn't just about specifying
revisions -- it's about specifying any object.


Anyway, although my patches aren't perfect, I think they improve the
current situation.  If there are no objections I would like to see them
committed.

Thanks,
Richard