[PATCH] Documentation: clarify / requirement in 'git check-ref-format'
'git check-ref-format' checks for the presence of at least one '/', the idea being that there should be no refs directly below 'refs/', so there should be a category like 'heads/' or 'tags/' in a refname.
Try and make this clearer in the man page.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
Daniel Barkalow venit, vidit, dixit 13.05.2009 17:03:
Show 52 quoted lines
> On Wed, 13 May 2009, Michael J Gruber wrote:
>
>> Geoff Russell venit, vidit, dixit 13.05.2009 02:09:
>>> 1 $ git --version
>>> git version 1.6.2.3
>>> 2 $ git check-ref-format xxxx && echo OK
>>> 3 $ git-check-ref-format --branch xxxx && echo OK
>>> xxxx
>>> OK
>>> 4 $ git check-ref-format --branch xxxx && echo OK
>>> usage: git check-ref-format refname
>>>
>>>
>>> 2 seems wrong,
>>> I tried 3 after looking at builtin-check-ref-format.c
>>> I couldn't find any test cases in the git/t directory
>>>
>>> From the documenation, I expect "git check-ref-format xxx" to return 0 if xxx is
>>> a valid branch or ref name. git version 1.6.3 gives the same results.
>>
>> There are several things going on:
>>
>> A) In 3 you use a different git than in 1,2,4. You told us the latter is
>> 1.6.2.3, and I'm telling you the former contains v1.6.2.1-310-ga31dca0
>> (which has the new --branch option).
>> This simply checks whether refs/heads/xxxx is sane. (It also resolves
>> @{-1} and such, which is what makes it useful at all.)
>>
>> B) "master" certainly looks like a valid refname, the doc seems to imply
>> that it should pass the check.
>>
>> C) Looking at the code, check-ref-format checks explicitly for the
>> presence of at least 2 levels: foo/bar is good, foo is bad. So, master
>> always had been bad, as well (or bad) as full sha1s!
>>
>> The code has always behaved like C since its inception but I don't know
>> the rationale behind the 2 level requirement. Daniel, Junio?
>
> In general, it's because you use it right before trying to use git
> update-ref $name, and you probably don't really want to change
> refs/master. Unless you know exactly what you're going (in which case,
> you're unlikely to check whether it's okay), you want to have a first
> level that specifies the type of ref and one or more additional levels
> that specify which ref of that type it is.
>
> I believe that, if you've got "master", and you want to do the sensible
> thing with it (i.e., the file you care about is .git/refs/heads/master),
> you want to use rev-parse with some option or other, not check-ref-format,
> but I don't know the plumbing-level shell API very well.
>
> -Daniel
> *This .sig left intentionally blank*Thanks Daniel and Sverre for the clarification, this makes a lot of sense.
Michael
Documentation/git-check-ref-format.txt | 4 ++++
1 files changed, 4 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index bf43454..0b7982e 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -25,6 +25,10 @@ imposes the following rules on how references are named:
grouping, but no slash-separated component can begin with a
dot `.`.
+. They must contain at least one `/`. This enforces the presence of a
+ category like `heads/`, `tags/` etc. but the actual names are not
+ restricted.
+
. They cannot have two consecutive dots `..` anywhere.
. They cannot have ASCII control characters (i.e. bytes whose
--
1.6.3.195.gad816
Geoff Russell
