Jacob Keller [off-list ref] writes:
From: Jacob Keller <redacted>
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 <redacted>
---
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.
On Tue, 2015-09-22 at 13:40 -0700, Junio C Hamano wrote:
Jacob Keller [off-list ref] writes:
quoted
From: Jacob Keller <redacted>
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 <redacted>
---
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.
Yes, let's go with that.
Regards,
Jake
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? it might seem that "notes/foo" ends up
as "refs/notes/notes/foo" which is not really what we mean.
Regards,
Jake