I think you are right that our documentation does not sufficiently communicate what the application does especially in various corner cases.

For my own sake, allow me to articulate the core value proposition once more. GitButler's virtual branches permit two novel use cases:

- A developer can lazily assign diffs/changes to belong to separate logical branches while maintaining their content within the same working dir. Those logical branches can be converted to plain git trees at any time. The canonical use case here is doing a bugfix while working on an unrelated feature - with the proposed workflow one can separate those contributions into discrete PRs while still having the content of both within the working dir.

- A developer can apply and unapply the content of remote branches to their working directory for the purpose of testing & review. This is distinct from rebasing and merging because it does not introduce merging or rebasing into the branch that the developer was originally working on.

In any case, we will work on communicating and documenting the tool better.

Well, one thing we can do is "merge" together multiple non-conflicting branches in your working directory without creating (or, I suppose, having to undo) merge artifacts.

Like if you had three branches and you wanted to see how they will work when they're all merged, and you find an issue in one and want to fix it, GB makes this really simple. You just apply them all and then fix something and make sure it's on the right branch and commit there (and push again if you want).

With Git, you would have to actually do either two merges or a three-head merge, see how it goes, undo the merge, switch to the target branch, commit a fix there, re-merge them all to see if that worked, etc. In Git there isn't a _real_ great way to combine trees without modifying history. We make those things a little more orthogonal.

Just to clarify, yes, in order to work on multiple simultaneous branches, you need a tool that knows what that means, which git does not really. But you can also very easily run 'git checkout main' and do whatever and then go back to GitButler and restore state. It's pretty good at knowing what mode you're in.

Basically all your virtual branches also live in refs/gitbutler/[name] and GB won't touch stuff in refs/heads/ because we like the idea of making sure we're not clobbering things you don't expect us to. You can just think of GitButler as a tool for managing refs/gitbutler branches.

All git tooling work totally fine, even generally if you're using something (like commit) that doesn't really make sense in the context of multiple branches.