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

[Richard Hansen <rhansen@bbn.com>]

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