Using the slash character in Git branch name

244
votes

I'm pretty sure I saw somewhere in a popular Git project the branches had a pattern like "feature/xyz".

However when I try to create a branch with the slash character, I get an error:

$ git branch labs/feature
error: unable to resolve reference refs/heads/labs/feature: Not a directory
fatal: Failed to lock ref for update: Not a directory

Same problem for (my initial attempt):

$ git checkout -b labs/feature

How does one create a branch in Git with the slash character?

7
gitbranch
Actually it looks like you have problem with your HEAD. It looks like git thinks your HEAD is a link to the branch labs/feature which hasn't been created. I've no idea how this could have happened, but it means that your attempt to create a branch called foo/bar based off it, it's not working. Any idea how your HEAD came unstuck? – CB Bailey
I'm sorry for the confusion, its "labs/feature", not "foo/bar", edited example. – user58777
FWIW anything before the slash will generate a directory under .git/refs/heads ie if you do git checkout -b feature/123 then inside your projectRootFolder/.git/refs/heads directory you'll see a directory named: feature where inside that directory you'll see a branch named 123. Later if you create another feature/124 then inside the feature directory, you'll see a branch named 124 – Honey

7 Answers

248
votes

Are you sure branch labs does not already exist (as in this thread)?

You can't have both a file, and a directory with the same name.

You're trying to get git to do basically this:

% cd .git/refs/heads
% ls -l
total 0
-rw-rw-r-- 1 jhe jhe 41 2009-11-14 23:51 labs
-rw-rw-r-- 1 jhe jhe 41 2009-11-14 23:51 master
% mkdir labs
mkdir: cannot create directory 'labs': File exists

You're getting the equivalent of the "cannot create directory" error.
When you have a branch with slashes in it, it gets stored as a directory hierarchy under .git/refs/heads.

115
votes

It is possible to have hierarchical branch names (branch names with slash). For example in my repository I have such branch(es). One caveat is that you can't have both branch 'foo' and branch 'foo/bar' in repository.

Your problem is not with creating branch with slash in name.

$ git branch foo/bar
error: unable to resolve reference refs/heads/labs/feature: Not a directory
fatal: Failed to lock ref for update: Not a directory

The above error message talks about 'labs/feature' branch, not 'foo/bar' (unless it is a mistake in copy'n'paste, i.e you edited parts of session). What is the result of git branch or git rev-parse --symbolic-full-name HEAD?

45
votes

I forgot that I had already an unused labs branch. Deleting it solved my problem:

git branch -d labs
git checkout -b labs/feature

Explanation:

Each name can only be a parent branch or a normal branch, not both. Thats why the branches labs and labs/feature can't exists both at the same time.

The reason: Branches are stored in the file system and there you also can't have a file labs and a directory labs at the same level.

35
votes

Sometimes that problem occurs if you already have a branch with the base name.

I tried this:

git checkout -b features/aName origin/features/aName

Unfortunately, I already had a branch named features, and I got the exception of the question asker.

Removing the branch features resolved the problem, the above command worked.

1
votes

Branch name is case sensitive and so if there are folders created in Azure by your release manager, folder names should match exactly. Learned it hard way raising it with manager.

0
votes

just had the same issue, but i could not find the conflicting branch anymore.

in my case the repo had and "foo" branch before, but not anymore and i tried to create and checkout "foo/bar" from remote. As i said "foo" did not exist anymore, but the issue persisted.

In the end, the branch "foo" was still in the .git/config file, after deleting it everything was alright :)

-2
votes

I could be wrong, but I thought that slashes only appeared in branch names when they related to a remote repo, for example origin/master.