Re: [PATCH] notes: document behavior of --ref and --notes DWIMery

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 22, 2015, 20:40 UTC
Message-ID: <xmqq8u7y2nnq.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <1442953476-24537-1-git-send-email-jacob.e.keller@intel.com>

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

Show 15 quoted lines

> From: Jacob Keller <jacob.keller@gmail.com>
>
> The --notes and --ref parameter for selecting which notes ref to operate
> on are based off of expand_notes_ref functionality. The documentation
> mentioned that an unqualified ref argument would be taken as under
> `refs/notes/`. However, this does not clearly indicate that
> `refs/heads/master` will expand to `refs/notes/refs/heads/master`, so
> document this behavior.
>
> Add a further test for the expected behavior of git notes --ref
> refs/heads/master get-ref as well, to ensure future patches do not break
> this assumption.
>
> Signed-off-by: Jacob Keller <jacob.keller@gmail.com>
> ---

Looks OK to a cursory read, but I find "even if it is qualified under some other location" a bit tiring to read without adding much value. To readers who consider "other" in that phrase to be clear enough (i.e. "location other than refs/notes"), it is totally redundant. To other readers who feel "other" in that phrase to be under qualified (i.e. "location other than what???"), it is not informative enough. Middle-ground readers who would not know if "refs/a" is inside or outside some "other" location, it is confusing.

After all, "a/b" is qualified under some location (i.e. a/) other than "refs/notes/", and it does mean "refs/notes/a/b".

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.