Branch names with slashes

Branch names with slashes

[Leonardo Kim]

Hi

Branch names can contain slashes, so we can use 'development/foo' as a
branch name. If I choose 'development' as a branch name, it doesn't
work. There is a directory named development at '.git/refs/heads'
directory. So we cannot create a file named development for
'refs/heads/development'.

An error message may occurs like below. Unfortunately, It is not of help to me.
'error: 'refs/heads/development/foo' exists; cannot create
'refs/heads/development'.

I think that dealing with a file system and an error message above is
not sufficient for a novice like me. I hope that it should be
improved.

Thanks for your response.
Leonardo YongUk KIM

Re: Branch names with slashes

[Michael Haggerty]

On 12/14/2011 11:17 AM, Leonardo Kim wrote:
> Branch names can contain slashes, so we can use 'development/foo' as a
> branch name. If I choose 'development' as a branch name, it doesn't
> work. There is a directory named development at '.git/refs/heads'
> directory. So we cannot create a file named development for
> 'refs/heads/development'.
> 
> An error message may occurs like below. Unfortunately, It is not of help to me.
> 'error: 'refs/heads/development/foo' exists; cannot create
> 'refs/heads/development'.

Assuming that the wording of the error message is not considered part of
the external API, it is trivial to change it.  What do you suggest?

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/

Re: Branch names with slashes

[Neal Kreitzinger]

On 12/14/2011 4:17 AM, Leonardo Kim wrote:
> Branch names can contain slashes, so we can use 'development/foo' as
> a branch name. If I choose 'development' as a branch name, it doesn't
> work. There is a directory named development at '.git/refs/heads'
> directory. So we cannot create a file named development for
> 'refs/heads/development'.
>
> An error message may occurs like below. Unfortunately, It is not of
> help to me. 'error: 'refs/heads/development/foo' exists; cannot
> create 'refs/heads/development'.
>
> I think that dealing with a file system and an error message above is
> not sufficient for a novice like me. I hope that it should be
> improved.
>
FYI, We also use slashes in our branchnames to leverage some of the 
benefits of a path-like namespace like pattern matching and the logical
expression of hierarchies using descriptive compound names. (We use git 
1.7.1 on linux.) Here's something to keep in mind: You have to plan 
(think ahead) for your naming conventions so that the namespaces will 
maintain uniqueness at a peer level over time that cannot be confused as 
subdirs under .git/refs/heads. For example:

branchnames:
/mysystem/generic
/mysystem/generic/project1

will not work because /mysystem/generic appears to be a parent dir to
/mysystem/generic/project1 under .git/refs/heads.  The solution is:

/mysystem/generic/base
/mysystem/generic/project1

these branches can coexist because they are unique without one appearing
to be a parent dir of the other.  IOW, their namespaces are peers in
their entirety. To carry the example a little further,

/mysystem/generic/project1/part2
will not work because once again it appears to be a subdir of an 
existing branchname (ref).  However,
/mysystem/generic/project1-part2
will work.

I think the reason for this is that if you look at .git/refs/heads you
will see that these slash delimited branch names are actually stored as
subdirs in the filesystem sense.  Therefore, git will get confused and
error out as it tries to find branchnames that are not entirely unique
by their full path namespace under .git/refs/heads because a branch
namespace that is a prefix (in the filesystem sense) of another branch 
name would occupy the same path under .git/refs/heads without being 
distinguishable as unique, and vice versa.

Hope this helps. (Maybe someone else will find a clearer way to explain
this.)

v/r,
neal

Re: Branch names with slashes

[Michael Haggerty]

On 12/15/2011 09:40 PM, Neal Kreitzinger wrote:
> On 12/14/2011 4:17 AM, Leonardo Kim wrote:
>> Branch names can contain slashes, so we can use 'development/foo' as
>> a branch name. If I choose 'development' as a branch name, it doesn't
>> work. There is a directory named development at '.git/refs/heads'
>> directory. So we cannot create a file named development for
>> 'refs/heads/development'.
>>
>> An error message may occurs like below. Unfortunately, It is not of
>> help to me. 'error: 'refs/heads/development/foo' exists; cannot
>> create 'refs/heads/development'.
>>
>> I think that dealing with a file system and an error message above is
>> not sufficient for a novice like me. I hope that it should be
>> improved.
>>
> FYI, We also use slashes in our branchnames to leverage some of the
> benefits of a path-like namespace like pattern matching and the logical
> expression of hierarchies using descriptive compound names. (We use git
> 1.7.1 on linux.) Here's something to keep in mind: You have to plan
> (think ahead) for your naming conventions so that the namespaces will
> maintain uniqueness at a peer level over time that cannot be confused as
> subdirs under .git/refs/heads. For example:
> 
> branchnames:
> /mysystem/generic
> /mysystem/generic/project1
> 
> will not work because /mysystem/generic appears to be a parent dir to
> /mysystem/generic/project1 under .git/refs/heads.  The solution is:
> 
> /mysystem/generic/base
> /mysystem/generic/project1
> 
> these branches can coexist because they are unique without one appearing
> to be a parent dir of the other.  IOW, their namespaces are peers in
> their entirety. To carry the example a little further,
> 
> /mysystem/generic/project1/part2
> will not work because once again it appears to be a subdir of an
> existing branchname (ref).  However,
> /mysystem/generic/project1-part2
> will work.
> 
> I think the reason for this is that if you look at .git/refs/heads you
> will see that these slash delimited branch names are actually stored as
> subdirs in the filesystem sense.  Therefore, git will get confused and
> error out as it tries to find branchnames that are not entirely unique
> by their full path namespace under .git/refs/heads because a branch
> namespace that is a prefix (in the filesystem sense) of another branch
> name would occupy the same path under .git/refs/heads without being
> distinguishable as unique, and vice versa.

Everything that you say is correct.  And it is known, at least to a few
git implementers (i.e., not a bug but a conscious design decision).  For
example, the function is_refname_available() is used explicitly to
prevent refnames that conflict in the way that you describe *even if*
the refnames in question are packed and therefore not 1:1 with
filesystem paths.  This is all a limitation of the fact that references
*can* be represented by files and therefore they inherit the filesystem
constraint that a file and subdirectory within a single parent directory
cannot have the same name.

I don't believe that it would be possible to relax this limitations
without at least a little breakage of backwards compatibility.

What is the bottom line?  Feel free to submit patches to improve the
documentation or error reporting.  But I doubt that the underlying
limitation will be removed.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/

Re: Branch names with slashes

[Junio C Hamano]

Michael Haggerty <mhagger@alum.mit.edu> writes:

> I don't believe that it would be possible to relax this limitations
> without at least a little breakage of backwards compatibility.

I do not think it is worth it, but you _could_ update your git to use a
file whose name is "refs/heads/.foo/bar" as the representation of foo/bar
branch and refs.c API, especially the ones close to resolve_ref(), should
be the only ones that need to know about this.  While walking the filesystem
in refs/ hierarchy, any directory you see whose name do not begin with dot
you would treat it as a legacy one and perhaps rename it to match the new
convention on the fly.

> What is the bottom line?  Feel free to submit patches to improve the
> documentation or error reporting.  But I doubt that the underlying
> limitation will be removed.

I do not think so either. It is not even a limitation but is a basic
nature of "hierarchical names".

Re: Branch names with slashes

[Johannes Sixt]

Am 12/14/2011 11:17, schrieb Leonardo Kim:
> Branch names can contain slashes, so we can use 'development/foo' as a
> branch name. If I choose 'development' as a branch name, it doesn't
> work. There is a directory named development at '.git/refs/heads'
> directory. So we cannot create a file named development for
> 'refs/heads/development'.
> 
> An error message may occurs like below. Unfortunately, It is not of help to me.
> 'error: 'refs/heads/development/foo' exists; cannot create
> 'refs/heads/development'.
> 
> I think that dealing with a file system and an error message above is
> not sufficient for a novice like me. I hope that it should be
> improved.

Sorry, I don't see anything in the error message that makes a connection
between refs and a file system; it only says "foo/bar exists; cannot
create foo". I really don't see how this can be improved to avoid confusion.

-- Hannes