git butler gives me an error whenever I try to create a 'main' branch

[moist-cupcake]

$ but --version
but 0.19.6

$ but branch new main
Error: Reference 'main' cannot be created as segment at ffb4ab121cf49d38c97e3d2752e5df9f8127873e

This is consistent with this branch name in both the CLI and the GUI.

It used to work so I guess I did something to the workspace but have no idea how to untangle it. What I tried so far was:

but teardown
git branch -D the 3 gitbutler branches
but setup

But still the problem is there.

[moist-cupcake]

OK, the workaround was to checkout a new repository, copy my changes to it and submit from there and then remove the old repository. In case someone else runs into this. There is probably a less onerous workaround too

[Byron]

Thanks a lot for reporting, and sorry for the inconvenience.

I have a feeling that this issue is related to #13032, as a new segment could not be created for other reasons.

[slarse]

Hi,

I've found there is an issue with creating branches with but branch new if they've previously been created via Git (but after but setup). We don't gracefully handle that at the moment.

$ git branch main
$ but branch new main
Error: Reference 'main' cannot be created as segment at fc2b003ba7f388ee251963d085c97a3d2caf6ca1
$ git branch -D main
Deleted branch main (was 27b755a33f).
$ but branch new main
✓ Created branch main

This may be the problem here, at least the symptoms match up.

I've got but branch pegged for various bug fixes and improvements, this being one of them.

[Byron]

Ah, right.

Creating the branch with Git puts it directly onto the commit that gitbutler/workspace points to. And as the branch exists already, the current error message basically indicates that our own create_reference couldn't make good sense of it, hoped that the existing branch would already be in the workspace, but it errors as it ultimately wasn't.

Here I created foobarbaz with Git, and I see exactly the same error message also from the UI.

There just is no way to deal with this as the branch isn't in the workspace, but I can imagine to provide a better error message in that case. Maybe one could just say that the branch already exists, and is outside of the workspace.

[slarse]

@Byron My example happened to use the workspace commit, but that's not where I initially encountered this issue. It affects any branch created with Git, after initial workspace setup.

[test-repo-99]$ but status
Last fetch was 5d ago. Initiated a background sync...
╭┄zz [unstaged changes]
┊     no changes
┊
┊╭┄pu [push-1]
┊●   88ce6de bla
├╯
┊
┴ 60dd738 [origin/main] 2026-02-23 Update README in GUI

Hint: run `but help` for all commands
[test-repo-99]$ git branch test 88ce6de
[test-repo-99]$ git rev-parse test
88ce6dea0d4f9348153e1ca618b1c8d0f8d385bc
[test-repo-99]$ git rev-parse gitbutler/workspace
58bf2ee20033de6137107ac0ed52d2f17efef0ff
[test-repo-99]$ but branch new test
Initiated a background sync...
Error: Reference 'test' cannot be created as segment at 60dd73885f3371ab2c1f78ced86976b9bb4ace3a
[test-repo-99]$ git branch -D test
Deleted branch test (was 88ce6de).
[test-repo-99]$ but branch new test
Initiated a background sync...
✓ Created branch test

Just wanted to point out that it's not related to the workspace commit as such.

Just so you don't put too much effort in here, I'm tracking a bunch more bugs in the branch commands on Linear and have them pegged for a possibly full rewrite.

[Byron]

Just so you don't put too much effort in here, I'm tracking a bunch more bugs in the branch commands on Linear and have them pegged for a possibly full rewrite.

Oh wow, alright then :D.
Since tests exist for all cases to support, I think rewriting it to better mesh with the changed environment might be a good choice here. I will be sure possibly missing tests are there, it's surprising that a pre-existing branch creates so much trouble.
It would lack metadata, and that is what's often needed to disambiguate.

[moist-cupcake]

FWIW I would have been happy with some human-readable instructions telling me what the next steps were that I could take

[moist-cupcake]

I'm seeing this again...

gina@Airabella:~/Source/pinky-src(git:workspace!)$ but status
╭┄zz [unstaged changes]
┊   vm A admin/reports/prod-check-2026-04-09_0635Z-analysis.md
┊
┊╭┄cl [cli_tweaks]
┊●   f0ff4ae fix(cli): dorky ordering
├╯
┊
┴ 93d924f [origin/main] 2026-04-08 1.2.7

Hint: run `but diff` to see uncommitted changes and `but stage <file>` to stage them to a branch
gina@Airabella:~/Source/pinky-src(git:workspace!)$ but branch new main
Error: Reference 'main' cannot be created as segment at 93d924f4edd9ca516057f4fedf725661f8dff06e

Is there a way for me to get you more detailed information that is useful to you?

[slarse]

@moist-cupcake Could you explain what you are trying to achieve? Why are you trying to create a branch called main on a regular basis? I believe that there is some disconnect between what you are trying to do, and how GitButler is designed to operate.

The explanation that @Byron and I have come up with is that you already have a branch called main, which is why GitButler is refusing to create a new one. The error message just isn't very informative. Seeing as your target branch is origin/main, this seems a very likely explanation (run git branch and you'll probably see that you already have main).

As your local main is very likely to be setup to track your target branch origin/main, applying main to your workspace does not make sense. So that's where I think there is a disconnect between your mental model, and GitButler's intended operation. With the fixes we have planned, the only thing that will change here is that the error message will read something like "Branch 'main' already exists [...]", so what you're trying to do still won't work.

[moist-cupcake]

I do suspect I am not using it as you intended!

However as you can see when I run 'but status' here: #13104 (comment), it is not showing me a main branch but is then failing with an error when I try to create the main branch.

To answer your question, my intention was to create a local main branch that I could commit to, so I could then push them upstream. This has worked for me in the past.

Sort of reading between the lines, I think you are saying that there is a gitbutler namespace for branches, which is what I see when I run 'but status' and also the git namespace for branches and using the same name in both will cause this error. Now that I know that is going to cause an error, I can avoid it.

Perhaps the error message you are going to add can mention that?

Anyway, thank you for helping me to understand this, it has felt very confusing to me!

[slarse]

@moist-cupcake This explains a lot! The gist of it is that the workflow you're looking for (what we call "single branch mode") is not yest supported, but it is being worked on. @krlvi could you perhaps fill in some details on the status of that? I'm a bit out of the loop on it.

However as you can see when I run 'but status' here: #13104 (comment), it is not showing me a main branch but is then failing with an error when I try to create the main branch.

but status only shows your workspace. GitButler is designed around working with multiple branches in a single Git worktree, and we maintain a head commit that is the merge of all of those branches. You can read more about it here if you're interested.

But even so, we additionally hide the local branch tracking your target branch (i.e. main tracking origin/main) from any part, even if you run but branch list --all. You're currently not meant to use it whatsoever. However, we recognize that many users want this, hence the work on single branch mode!

Sort of reading between the lines, I think you are saying that there is a gitbutler namespace for branches, which is what I see when I run 'but status' and also the git namespace for branches and using the same name in both will cause this error. Now that I know that is going to cause an error, I can avoid it.

Not exactly, branches are all just Git refs in the end. There is no distinction between a branch created via Git and one created via GitButler in the logical sense, but there are some practical differences in terms of metadata which could explain some of the wonky behavior I've run into myself (and intend to look into very soon).

The more important distinction is if the branch is in your workspace or not. If you try to create a new branch with but branch new and it collides with a ref that exists, but is not applied to your workspace, you'd generally run into the confusing error you found above.

So there are two parts to this, 1) you're really looking for the single branch mode functionality, and 2) we have some UX improvements to make to the branch management. Does this seem like a reasonable conclusion?