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

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

[Richard Hansen]

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

[PATCH 1/4] glossary: add 'treeish' as a synonym for 'tree-ish'

[Richard Hansen]

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 <rhansen@bbn.com>
---
 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

Re: [PATCH 1/4] glossary: add 'treeish' as a synonym for 'tree-ish'

[Junio C Hamano]

Richard Hansen <rhansen@bbn.com> writes:

> 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.

Is it an option to instead find dashless form in our documentation
and turn all of them into tree-ish form with a dash?  I personally
find it cleaner that way.

>
> Signed-off-by: Richard Hansen <rhansen@bbn.com>
> ---
>  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.

Re: [PATCH 1/4] glossary: add 'treeish' as a synonym for 'tree-ish'

[Richard Hansen]

On 2013-06-19 13:09, Junio C Hamano wrote:
> Richard Hansen <rhansen@bbn.com> writes:
> 
>> 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.
> 
> Is it an option to instead find dashless form in our documentation
> and turn all of them into tree-ish form with a dash?  I personally
> find it cleaner that way.

I can s/treeish/tree-ish/g, although I'd still like to keep 'treeish' in
the glossary so that people can find it when they search for the
misspelled version.

Perhaps something like:

-[[def_tree-ish]]tree-ish::
+[[def_tree-ish]]tree-ish (sometimes misspelled treeish)::

would be satisfactory?

While we're on the topic, do you have a preference for commit-ish vs.
committish?  Grepping the code shows comittish to be the overwhelming
favorite, but it's inconsistent with tree-ish.

-Richard


> 
>>
>> Signed-off-by: Richard Hansen <rhansen@bbn.com>
>> ---
>>  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.
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH 1/4] glossary: add 'treeish' as a synonym for 'tree-ish'

[Junio C Hamano]

Richard Hansen <rhansen@bbn.com> writes:

> Perhaps something like:
>
> -[[def_tree-ish]]tree-ish::
> +[[def_tree-ish]]tree-ish (sometimes misspelled treeish)::
>
> would be satisfactory?

If it is a misspelling, I do not think we need to list both.  An
entry "tree-ish" can be found if you were looking for treeish.

If it is not, then "sometimes misspelled" should perhaps is better
"aka".

I do not personally have a very strong preference between the dashed
and dashless forms, but if I really have to pick one over the other,
I would probably go with tree-ish, commit-ish, as these are not real
words.  I do have mild preference of not listing both to keep things
shorter and cleaner.

Re: [PATCH 1/4] glossary: add 'treeish' as a synonym for 'tree-ish'

[Richard Hansen]

On 2013-06-19 13:09, Junio C Hamano wrote:
> Richard Hansen <rhansen@bbn.com> writes:
> 
>> 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.
> 
> Is it an option to instead find dashless form in our documentation
> and turn all of them into tree-ish form with a dash?  I personally
> find it cleaner that way.

My preference is treeish and committish (instead of tree-ish and
commit-ish) because those are the spellings used in the source code.

-Richard

> 
>>
>> Signed-off-by: Richard Hansen <rhansen@bbn.com>
>> ---
>>  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.
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

[PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Richard Hansen]

Signed-off-by: Richard Hansen <rhansen@bbn.com>
---
 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

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Ramkumar Ramachandra]

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.

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Richard Hansen]

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

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Ramkumar Ramachandra]

Richard Hansen wrote:
> 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.

>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?

>> 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`.

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Richard Hansen]

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.

> 
>>> 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

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Richard Hansen]

On 2013-06-19 11:31, Richard Hansen wrote:
> 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.

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

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Jonathan Nieder]

Hi,

Richard Hansen wrote:

> --- 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>>.

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

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Junio C Hamano]

Richard Hansen <rhansen@bbn.com> writes:

> Signed-off-by: Richard Hansen <rhansen@bbn.com>
> ---
>  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.
> +

<object-type>-ish does not have anything to do with a ref.  Even
when an object is dangling in your object store without being
reachable from any of your refs, it keeps its own "ish"-ness.

"ish"-ness is a property of the object itself.

 * A commit object has a single top-level tree, and when a command
   wants a tree object, you can often pass it a commit (historically
   some commands were more strict and refused to work on a commit
   when they wanted a tree).  In other words, a commit can be used
   in place for a tree.  A commit object is a tree-ish.

 * A tag object, when it points (recursively) at a commit object,
   can often be used in place for a commit object.  Such a tag
   object is a commit-ish.

 * A tag object, when it points (recursively) at a tree object, can
   often be used in place for a tree object.  Such a tag object is a
   tree-ish.  Note that such a tag object cannot be a commit-ish.

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Richard Hansen]

On 2013-06-19 13:14, Junio C Hamano wrote:
> <object-type>-ish does not have anything to do with a ref.  Even
> when an object is dangling in your object store without being
> reachable from any of your refs, it keeps its own "ish"-ness.

Ah, so your personal definition of "ref" matches my personal definition
of "ref", and this definition doesn't match gitglossary(7).  :)

> 
> "ish"-ness is a property of the object itself.
> 
>  * A commit object has a single top-level tree, and when a command
>    wants a tree object, you can often pass it a commit (historically
>    some commands were more strict and refused to work on a commit
>    when they wanted a tree).  In other words, a commit can be used
>    in place for a tree.  A commit object is a tree-ish.
> 
>  * A tag object, when it points (recursively) at a commit object,
>    can often be used in place for a commit object.  Such a tag
>    object is a commit-ish.
> 
>  * A tag object, when it points (recursively) at a tree object, can
>    often be used in place for a tree object.  Such a tag object is a
>    tree-ish.  Note that such a tag object cannot be a commit-ish.

I agree with all of this; the issue is the definition of "ref" in
gitglossary(7).  That definition should be fixed.  In the meantime, I'll
rework the patch series to avoid using the word "ref" when defining
committish and tree-ish.

-Richard

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Junio C Hamano]

Richard Hansen <rhansen@bbn.com> writes:

> On 2013-06-19 13:14, Junio C Hamano wrote:
>> <object-type>-ish does not have anything to do with a ref.  Even
>> when an object is dangling in your object store without being
>> reachable from any of your refs, it keeps its own "ish"-ness.
>
> Ah, so your personal definition of "ref" matches my personal definition
> of "ref", and this definition doesn't match gitglossary(7).  :)

Huh?  The only thing I I said was that "*-ish" does not have
anything to do with a ref.  I didn't say anything about definition
of "ref".

You are the one who brought "ref" into description of *-ish, with
this:

> +[[def_committish]]committish (also commit-ish)::
> +	A <<def_ref,ref>> pointing to an <<def_object,object>> that
> +	can be recursively dereferenced to a

All I am saying is that an object does not have to be pointed by any
ref to be any-ish.  ish-ness is an attribute of an object, not an
ref.  You do not say refs/heads/master (which is a ref) is a
commit-ish or a tree-ish.  The object pointed at by that ref is
always a commit and is a commit-ish and a tree-ish.

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Richard Hansen]

On 2013-06-19 17:05, Junio C Hamano wrote:
> Richard Hansen <rhansen@bbn.com> writes:
> 
>> On 2013-06-19 13:14, Junio C Hamano wrote:
>>> <object-type>-ish does not have anything to do with a ref.  Even
>>> when an object is dangling in your object store without being
>>> reachable from any of your refs, it keeps its own "ish"-ness.
>>
>> Ah, so your personal definition of "ref" matches my personal definition
>> of "ref", and this definition doesn't match gitglossary(7).  :)
> 
> Huh?  The only thing I I said was that "*-ish" does not have
> anything to do with a ref.  I didn't say anything about definition
> of "ref".

The phrase

    when an object is dangling in your object store without being
    reachable from any of your refs

implies something about your definition of a ref that is inconsistent
with gitglossary(7).  See below.

> 
> You are the one who brought "ref" into description of *-ish, with
> this:
> 
>> +[[def_committish]]committish (also commit-ish)::
>> +	A <<def_ref,ref>> pointing to an <<def_object,object>> that
>> +	can be recursively dereferenced to a

And I did that to be consistent with the definition of tree-ish, which
currently says:

    tree-ish
        A ref pointing to either a commit object, a tree object, or a
        tag object pointing to a tag or commit or tree object.

Notice the term "ref" in the above definition.  This definition says
that a tree-ish is a particular kind of ref -- NOT a property of an
object as you claim.  I'm not saying you're wrong -- I actually agree
with you completely -- I'm just saying that your definition of ref
doesn't match the definition of ref in gitglossary(7).

The current definition of ref says:

    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.

Depending on how one interprets "name" (which is not defined in
gitglossary(7)) in the above definition of ref, claiming that
"master:README" is a ref is consistent with gitglossary(7).  It is NOT,
however, consistent with what you -- or anyone else I know -- think of
as a ref.

> 
> All I am saying is that an object does not have to be pointed by any
> ref to be any-ish.  ish-ness is an attribute of an object, not an
> ref.  You do not say refs/heads/master (which is a ref) is a
> commit-ish or a tree-ish.  The object pointed at by that ref is
> always a commit and is a commit-ish and a tree-ish.

I understand and agree completely and always have.

Here's what I'm trying to say:

  * Given the current definition of "ref" in gitglossary(7), claiming
    that a foo-ish is a ref is not entirely incorrect.
  * If the definition of "ref" is altered to match the general
    understanding of a "ref", then claiming that a foo-ish is a ref is
    wrong.  Very wrong.

I was trying to be minimal and consistent with my changes, but
unfortunately it seems like more changes are necessary.  When I next
have time, I'll send some revised patches to include the following changes:

  * replace the current definition of "ref" with something that matches
    general understanding
  * eliminate the use of "ref" in the definitions of tag object, tree
    object, and tree-ish
  * create a term that means "a thing understood by rev-parse that
    uniquely identifies an object" (perhaps "object specifier"?) that
    can be used in gitglossary(7) and elsewhere

-Richard

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Junio C Hamano]

Richard Hansen <rhansen@bbn.com> writes:

> Here's what I'm trying to say:
>
>   * Given the current definition of "ref" in gitglossary(7), claiming
>     that a foo-ish is a ref is not entirely incorrect.

Ahh.  If you had quoted this a few exchanges ago:

    [[def_ref]]ref::
            A 40-byte hex representation of a <<def_SHA1,SHA-1>> or a name that
            denotes a particular <<def_object,object>>. They may be stored in
            a file under `$GIT_DIR/refs/` directory, or
            in the `$GIT_DIR/packed-refs` file.

I would have immediately understood what you were trying to say.
Sorry about a wasted back-and-forth.

The above is an utterly confused explanation.  It explains object
names and mentions as a sidenote that object names _can_ be held in
refs.

It does not say what a ref is, in other words.

Before 'packed-refs' was introduced, the right definition would have
been

	A file under `$GIT_DIR/refs/` directory that holds an object
	name.

And packed-refs is a way to coalesce such files into a single file
to make it easier/faster to access.

In today's world (after packed-refs was introduced), probably

	A name that begins with refs/ (e.g. refs/heads/master) that
	can point at an object name.

        The namespace of refs is hierarchical and different
        subhierarchy is used for different purposes (e.g. the
        refs/heads/ hierarchy is used to represent local branches).

is an appropriate rewrite of the above.

If we also want to explain the implementation details of refs, then
additionally at the end of the first paragraph, add:

	... at an object name, by storing its 40-byte hex
	representation.  They are implemented as either a file in
	$GIT_DIR/refs/ directory (called "loose refs") or an entry
	in $GIT_DIR/packed-refs file (called "packed refs"); when a
	loose ref exists, a packed ref of the same name is ignored.

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Richard Hansen]

On 2013-06-19 18:36, Junio C Hamano wrote:
> Ahh.  If you had quoted [...] a few exchanges ago I would have
> immediately understood what you were trying to say.

Sorry about that, my bad.

> In today's world (after packed-refs was introduced), probably
> 
> 	A name that begins with refs/ (e.g. refs/heads/master) that
> 	can point at an object name.
> 
>         The namespace of refs is hierarchical and different
>         subhierarchy is used for different purposes (e.g. the
>         refs/heads/ hierarchy is used to represent local branches).
> 
> is an appropriate rewrite of the above.

Some thoughts about the above definition:
  * Aren't HEAD, FETCH_HEAD, ORIG_HEAD also refs?
  * That definition excludes symrefs.
  * It may be worthwhile to mention that refs are part of the
    repository.
  * Is a ref a name?  Or is it the binding of a name to an object/ref?

How about:

    ref
        A binding of a name to an object or other ref (in which case it
        is a symref).  Refs are stored in the repository.

        The ref namespace is hierarchical.  Different subhierarchies
        are used for different purposes (e.g. the refs/heads/ hierarchy
        is used to represent local branches).

> 
> If we also want to explain the implementation details of refs, then
> additionally at the end of the first paragraph, add:
> 
> 	... at an object name, by storing its 40-byte hex
> 	representation.  They are implemented as either a file in
> 	$GIT_DIR/refs/ directory (called "loose refs") or an entry
> 	in $GIT_DIR/packed-refs file (called "packed refs"); when a
> 	loose ref exists, a packed ref of the same name is ignored.

It would be good to document this somewhere, but I'm not sure the
glossary is the right place for it.  Maybe gitrepository-layout(5)?

-Richard

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Junio C Hamano]

Richard Hansen <rhansen@bbn.com> writes:

> On 2013-06-19 18:36, Junio C Hamano wrote:
>> Ahh.  If you had quoted [...] a few exchanges ago I would have
>> immediately understood what you were trying to say.
>
> Sorry about that, my bad.
>
>> In today's world (after packed-refs was introduced), probably
>> 
>> 	A name that begins with refs/ (e.g. refs/heads/master) that
>> 	can point at an object name.
>> 
>>         The namespace of refs is hierarchical and different
>>         subhierarchy is used for different purposes (e.g. the
>>         refs/heads/ hierarchy is used to represent local branches).
>> 
>> is an appropriate rewrite of the above.
>
> Some thoughts about the above definition:
>   * Aren't HEAD, FETCH_HEAD, ORIG_HEAD also refs?

That is a shade of gray.  "refs" are names we use as the starting
point to construct extended SHA-1 expressions to refer to objects,
and in that sense they are.  It would be complete to mention these
as special cases.

>   * That definition excludes symrefs.

True.  "... that can directly point at an object, or point at
another ref (the latter is called a symbolic ref)."

>   * It may be worthwhile to mention that refs are part of the
>     repository.
>   * Is a ref a name?  Or is it the binding of a name to an object/ref?

I am not particularly interested in pedantry, but I think in the way
we used the word "ref", it is a name.  "refs/heads/master" is the
full name of the ref and it can be abbreviated to 'master' when not
ambiguous.  And there is a mechanism to read what the the ref has to
learn the name of the object (*not* object/ref) it refers to (the
name of that mechanism being "ref resolution").

To a layperson, a ref is one of the ways you can name an object
with.

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Ramkumar Ramachandra]

Richard Hansen wrote:
>   * Aren't HEAD, FETCH_HEAD, ORIG_HEAD also refs?

HEAD is a symbolic ref [*1*], FETCH_HEAD is not a ref [*2*], and
ORIG_HEAD is a ref.

>     ref
>         A binding of a name to an object or other ref (in which case it
>         is a symref).  Refs are stored in the repository.

What is "binding of a name"?  It's a file that contains exactly one
line: a 40-character SHA-1 hex.  End of story.  Like I explained in
[*1*], I see no advantage in grouping symbolic refs with refs.

>         The ref namespace is hierarchical.  Different subhierarchies
>         are used for different purposes (e.g. the refs/heads/ hierarchy
>         is used to represent local branches).

Good.

[Footnotes]

*1*: HEAD is the one and only symbolic ref, unless you create more by
hand using `git symbolic-ref`.  Unfortunately, no other symbolic ref
can ever be on the same footing as HEAD: the sources hard-code "HEAD"
in a large number of places, and reworking it to truly support
symbolic refs is probably not worth the pain at all.  If you want to
convince yourself that this is true, run `git symbolic-ref H HEAD` and
then try to resolve H@{u}: HEAD@{u} resolves fine, doesn't it?

*2*: It's not an "ordinary file" like COMMIT_EDITMSG either, in that
rev-parse can operate on it.  It is not a ref because it contains
references to several objects; cat it and see for yourself.

Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Ramkumar Ramachandra]

Richard Hansen wrote:
> In the meantime, I'll
> rework the patch series to avoid using the word "ref" when defining
> committish and tree-ish.

This is a good way forward.  I'm curious about what you're planning on
substituting it with though: the "extended SHA-1 expression" that
Jonathan hinted at?

[PATCH 3/4] glossary: more precise definition of tree-ish (a.k.a. treeish)

[Richard Hansen]

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 <rhansen@bbn.com>
---
 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

[PATCH 4/4] revisions.txt: fix and clarify <rev>^{<type>}

[Richard Hansen]

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 <rhansen@bbn.com>
---
 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