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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 19, 2013, 22:36 UTC
Message-ID: <7vwqppwwwj.fsf@alter.siamese.dyndns.org>
In-Reply-To: <51C22F77.8050004@bbn.com>

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.