[PATCH] Documentation: clarify / requirement in 'git check-ref-format'

[Michael J Gruber <git@drmicha.warpmail.net>]

'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:
> 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