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

[Richard Hansen <rhansen@bbn.com>]

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