From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 22 Sep 2015 21:23:09 GMT
Subject: Re: [PATCH] notes: document behavior of --ref and --notes DWIMery
Message-ID: <xmqqpp1a1742.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <1442955811.26280.50.camel@intel.com>

"Keller, Jacob E" <jacob.e.keller@intel.com> writes:

> On Tue, 2015-09-22 at 13:40 -0700, Junio C Hamano wrote:
>> How about phrasing it totally differently?
>> 
>> 	The ref specifies the full refname when it begins with
>> 	`refs/notes/`; otherwise `ref/notes/` is prefixed to form a
>> 	full name of the ref.
>> 
>> I think that would remove the need to illustrate with concrete
>> examples like refs/heads/blah.
>> 
>
> Wait, what about the DWIM of notes/<name> goes to refs/notes/<name>..
> do we need to explain that here?

Yeah, throw that in, too.

	... when it begins with `refs/notes/`; when it begins with
	`notes/`, `refs/` and otherwise `refs/notes/` is prefixed to
	form a full name of the ref.

We could emphasize the end result by ending the sentence like so:

	... form a full name of the ref that is under `refs/notes/`.

if you wanted to.  I am neutral (I do not think it would hurt, but I
do not think it adds much clarity).

Thanks.