check-ref-format: include refs/ in the argument or to strip it?

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

Michael Haggerty wrote[1]:
> Jonathan Nieder wrote:

>> The check-ref-format documentation is pretty unclear, but the
>> intent is that it would be used like
>>
>>	git check-ref-format heads/master
>>
>> (see the surviving examples in contrib/examples/). That way, it can
>> enforce the rule (from git-check-ref-format(1))
>>
>>	2. They must contain at least one /. This enforces the presence
>>	of a category like heads/, tags/ etc. but the actual names
>>	are not restricted.
[...]
> Thanks for the explanation and the pointer.
>
> I suppose that was a usage that was more popular in the past than
> now. I can hardly remember anyone talking about references like
> "heads/master" or "tags/v1". It seems to me that when somebody wants
> to be unambiguous they usually use the whole reference name
> "refs/heads/master" or "refs/tags/v1". When they want to be succinct
> they usually use just "master" or "v1".
>
> To me it seems incongruous to have the "heads/master" syntax
> supported at this deep level of plumbing. In most cases, the caller
> could get the same effect by prepending "refs/" to the string and
> then calling check_refname_format with a new
> REFNAME_REQUIRE_CATEGORY option that requires both a "refs/" prefix
> and a total of at least *three* levels.

I agree that this piece of UI is pretty weird.  Worse, it's
underdocumented.

I wonder if it would make sense to have the check-ref-format commandline
utility require two slashes when its argument begins with "refs/" (still
requiring only one slash when it doesn't, for backward compatibility)
and to start encouraging people to pass refnames with refs/ to it.

The alternative would be something like the following, which doesn't
seem too appealing.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
[1] https://code-review.googlesource.com/1017

 Documentation/git-check-ref-format.txt | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index fc02959..447e9fb 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -15,8 +15,8 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Checks if a given 'refname' is acceptable, and exits with a non-zero
-status if it is not.
+Checks if refs/<refname> is an acceptable ref name, and exits
+with a non-zero status if it is not.
 
 A reference is used in Git to specify branches and tags.  A
 branch head is stored in the `refs/heads` hierarchy, while
@@ -91,14 +91,14 @@ OPTIONS
 	components).  The default is `--no-allow-onelevel`.
 
 --refspec-pattern::
-	Interpret <refname> as a reference name pattern for a refspec
-	(as used with remote repositories).  If this option is
-	enabled, <refname> is allowed to contain a single `*`
-	in place of a one full pathname component (e.g.,
-	`foo/*/bar` but not `foo/bar*`).
+	Interpret refs/<refname> as a reference name pattern
+	for a refspec (as used with remote repositories).
+	If this option is enabled, <refname> is allowed
+	to contain a single `*` in place of a one full pathname
+	component (e.g., `foo/*/bar` but not `foo/bar*`).
 
 --normalize::
-	Normalize 'refname' by removing any leading slash (`/`)
+	Normalize <refname> by removing any leading slash (`/`)
 	characters and collapsing runs of adjacent slashes between
 	name components into a single slash.  Iff the normalized
 	refname is valid then print it to standard output and exit
@@ -118,7 +118,7 @@ $ git check-ref-format --branch @{-1}
 * Determine the reference name to use for a new branch:
 +
 ------------
-$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch") ||
+$ ref=$(git check-ref-format --normalize "heads/$newbranch") ||
 die "we do not like '$newbranch' as a branch name."
 ------------
 
--