check-ref-format: include refs/ in the argument or to strip it?
- From
Jonathan Nieder <jrnieder@gmail.com>
- Date
- Aug 22, 2014, 15:41 UTC
- Message-ID
- <20140822154151.GK20185@google.com>
- In-Reply-To
- <047d7b624d36142d46050131f336@google.com>
Hi,
Michael Haggerty wrote[1]:
> Jonathan Nieder wrote:
Show 11 quoted lines
>> 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.
[...]
Show 15 quoted lines
> 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." ------------