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

From: Richard Hansen <rhansen@bbn.com>
Date: Jun 19, 2013, 16:10 UTC
Message-ID: <51C1D7E3.9020305@bbn.com>
In-Reply-To: <51C1CEB4.60206@bbn.com>

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

Show 11 quoted lines

> 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