check-ref-format question

check-ref-format question

[Geoff Russell]

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.

Cheers,
Geoff.

Re: check-ref-format question

[Michael J Gruber]

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?

Michael

Re: check-ref-format question

[Sverre Rabbelier]

Heya,

On Wed, May 13, 2009 at 16:13, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> The code has always behaved like C since its inception but I don't know
> the rationale behind the 2 level requirement. Daniel, Junio?

Methinks that since it is a plumbing command it is up to the porcelain
to translate "master" into "refs/heads/master" or
"refs/remotes/origin/master" (or whatever is appropriate) before
dispatching to check-ref-format?

-- 
Cheers,

Sverre Rabbelier

Re: check-ref-format question

[Daniel Barkalow]

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*

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

[Michael J Gruber]

'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

Re: check-ref-format question

[Geoff Russell]

On Wed, May 13, 2009 at 11:43 PM, Michael J Gruber
<git@drmicha.warpmail.net> 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.)

Sorry, my mistake I was running in 2 windows on 2 machine and got
confused. Ignore
line 3 in my example.

>
> B) "master" certainly looks like a valid refname, the doc seems to imply
> that it should pass the check.

$ git --version
git version 1.6.2.3
$ git check-ref-format xxxx && echo OK
$ git check-ref-format master && echo OK
$ git check-ref-format master/xxxx && echo OK
OK

I'm confused.

Geoff.


>
> 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?
>
> Michael
>

Re: check-ref-format question

[Michael J Gruber]

Geoff Russell venit, vidit, dixit 14.05.2009 02:26:
> On Wed, May 13, 2009 at 11:43 PM, Michael J Gruber
> <git@drmicha.warpmail.net> 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.)
> 
> Sorry, my mistake I was running in 2 windows on 2 machine and got
> confused. Ignore
> line 3 in my example.
> 
>>
>> B) "master" certainly looks like a valid refname, the doc seems to imply
>> that it should pass the check.
> 
> $ git --version
> git version 1.6.2.3
> $ git check-ref-format xxxx && echo OK
> $ git check-ref-format master && echo OK
> $ git check-ref-format master/xxxx && echo OK
> OK
> 
> I'm confused.
> 
> Geoff.

Please read on to my item C), and check the documentation patch which I
submitted. If you're still confused after that I need to revise my patch ;)

> 
> 
>>
>> 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?
>>
>> Michael
>>

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

[Geoff Russell]

On Thu, May 14, 2009 at 1:13 AM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> '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.
>
> [....snip]
> +. 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.
>
> [ ...snip]

Ah, okay. This is clear. Many thanks.

Cheers,
Geoff