Branch with name `x/y` cannot be created if branch with name `x` exists

[shunichironomura]

Version

0.19.5

Operating System

macOS

Distribution Method

dmg (Mac OS - Apple Silicon)

Describe the issue

If there is already a branch with name x and you try to create a branch with name x/y with but branch new x/y, it outputs the following error and the branch creation fails:

❯ but branch new x
✓ Created branch x

❯ but branch new x/y
Error: The ref file "/Users/nomura/tmp/gb-fs-in-branch/.git/refs/heads/x/y" could not be read in full

Caused by:
    Not a directory (os error 20)

I see the same error when creating the branch x/y from GitButler UI.

Note that the branch creation is successful if branch x does not exist:

# Branch `xx` does not exist so it succeeds
❯ but branch new xx/yy
✓ Created branch xx/yy

If you run but teardown and try to create branch x/y with git, it also fails:

❯ git switch -c x/y
fatal: cannot lock ref 'refs/heads/x/y': 'refs/heads/x' exists; cannot create 'refs/heads/x/y'

If you don't create branch x via GitButler, you can create branch x/y:

❯ git init
Initialized empty Git repository in /Users/nomura/tmp/gb-fs-in-branch-git/.git/

❯ git switch -c b
Switched to a new branch 'b'

❯ git switch -c b/a
Switched to a new branch 'b/a'

(Git version 2.53.0)

So I suspect the way GitButler create a branch whose name contains a forward slash / is different from Git, and that causes this difference in behavior.

A similar issue can be found here:

• Cannot use forward slash(/) in branch name #8767

How to reproduce (Optional)

No response

Expected behavior (Optional)

No response

Relevant log output (Optional)

[Byron]

Thanks a lot for reporting!

I think the problem here is that Git must have some special treatment in these cases where it automatically prefers to use (or always uses) .git/packed-refs to allow x and x/y to exist at the same time. After all, loose references are inheriting the 'limitation' of the filesystem where an element in a path can't be a directory or file at the same time.

With that said, it might not be worth fixing this in favor of the arrival of Git 3.0, which switches to the ref-table backend which much like packed-refs doesn't have the problem.
gitoxide would have to provide an implementation as well, and thus can forgo any kind of special treatment that it would currently need to make this work.

[shunichironomura]

@Byron Thank you!

After more analysis, I found that it does not work even in Git (version 2.53.0).

In the steps I described above, I didn't create any commit after initializing the Git repository, resulting in creating no branch even after running git switch -c.

I confirmed that you cannot create x/y if branch x exists even in plain Git operation.

❯ git init
Initialized empty Git repository in /Users/nomura/tmp/git-fs/.git/

❯ git commit --allow-empty -m "initial commit"
[main (root-commit) 1935dd0] initial commit

❯ git switch -c x
Switched to a new branch 'x'

❯ git commit --allow-empty -m "commit to branch x"
[x 4c81573] commit to branch x

❯ git switch main
Switched to branch 'main'

❯ git branch
  x    * main

❯ git switch -c x/y
fatal: cannot lock ref 'refs/heads/x/y': 'refs/heads/x' exists; cannot create 'refs/heads/x/y'

So actually GitButler's behavior is consistent with Git's. So I don't think it is a bug after all.

Apologies for the false report. Feel free to close this issue.

[Byron]

Thank you for double-checking, it's much appreciated!

Let's leave it open for others to more easily fine, hopefully. In theory gitoxide could make this work by being clever about packed-refs, so if this becomes priority there could be a way forward even without reftables.

[nshcr]

I'd like to report an issue here that I mentioned on Discord a few days ago, which is very similar to this one. I'm confident it's a GitButler bug, caused by GitButler not properly removing its no-longer-used proprietary refs, rather than an issue related to consistency with Git's behavior.

In short: when a remote branch is applied, GitButler creates a ref with the same name under its own refs namespace. After the corresponding remote branch is integrated, that ref should no longer exist. However, GitButler still keeps the same-named ref in its namespace, which leads to the x/y vs x branch naming conflict described in this issue - and the user encounters it in a completely non-obvious way.

This problem can usually be resolved by removing the conflicting "ghost" ref using git update-ref -d.

The full reproduction steps can be seen in the video:

Screen.Recording.2026-03-08.at.09.46.11.-.01.mov

Relevant Discord message link: https://discord.com/channels/1060193121130000425/1073202153163857920/1478654880196329556

[Byron]

@nshcr Thanks a lot for reporting!

As this seems to be behaviour of apply, could you try again with the new "apply" implementation?

I don't think it has this special behaviour.
Besides that, I am looking into a fix for the old code, hoping it's local to 'apply'

[nshcr]

@Byron Thanks for the explanation. Indeed, after I enabled the "New apply to workspace", I haven't observed GitButler creating extra refs anymore. However, the existing ghost refs also don't seem to disappear just by enabling this experimental option.

Unless there's a cleanup script that can safely remove them, I'm hesitant to delete them manually. One of the repositories I've been managing with GitButler for a long time has more than thirty such refs - and unless I'm certain they're no longer used, I really don't dare remove them.

I hope these experimental options can stabilize soon, so I won't feel so uneasy about enabling them :P.

[Byron]

I believe these refs/gitbutler/ refs are unused and have no purpose. Previously these were UUID-branches I think, and it was all very confusing to me as to what happened. All I know is that the branches that are applied are normal Git branches without anything special about them.
Maybe try deleting that one test-branch from the video to gain certainty, after all the above is just an assumptions and we all know how these work ;).