V3 for branch creation

[Byron]

Create V3 versions for creating new branches, using the new data structures exclusively.
Theoretically, this is the time where we consider creating a workspace reference for metadata.
However, it critical to understand how this interacts with starting out on a noraml branch, particularly if no target is set yet.
The new version of this would work similarly or better than the current implementation, but interacts correctly with single-branch mode as well, without meddling with the user's data more than needed.

Insights gained

• dependent branches can be created anywhere, but if there is a workspace we can set the order.
  • if there is no workspace, then dependent branches must be exclusive on each commit to identify ordering
  • if there is a workspace, we store the order in workspace metadata
  • it would be good to have a way for the UI to check if a branch name exists (and what that name would be after sanitisation), so the error popup goes away and we know clearly the branch will be named.
  • All that's needed is a full ref name, and a commit that it should point to - from there we can figure out the rest. Optionally, there should be a way to say if it should be above or below something.
• independent branches
  • if the workspace ref exists and is managed, create a new stack-id along with the new ref on the lower bound. Update the metadata accordingly.
  • if the workspace ref doesn't exist, create a workspace ref at the current HEAD, and set the target_id in ref_metadata::Workspace (to be created), it's to keep the official base even if the workspace advances. There should be no need to create a workspace commit yet, but we could just create one for good measure.
    • Not creating the workspace commit would mean there is no useless commit, and that all operations that affect the workspace commit need to be able to create it on demand. Maybe that would be better, as it's as lazy as possible, while making the system more flexible. I.e. users can create this setup themselves and it will work correctly even without workspace metadata.
• avoid implicit workspace creation
  • Do what you can with what's there, and help users decide how to create a workspace.
  • there are plenty of options on how to do that, and the user has to decide if and which target branch to use.

Tasks

• fix worksaround VB.toml adapter bug
• fix Graph post-processing panic
• create dependent branches
  • in ad-hoc workspace/single-branches
  • in existing workspaces
  • above-and-below existing stacked refs (specification ambiguity unless there is a ref-name as anchor)
    • assure dependent branch names are also UPDATED according to what's really there afterwards.
      That way, reality can reconcile what we have stored (even though that loses information)
  • error-cases single branch
  • error-cases workspaces
  • in anonymous workspaces
  • assure no test-coverage is lost (stack/tests/mod.rs)
• independent branches
  • in existing workspaces
  • in anonymous workspaces
  • in ad-hoc workspaces - doesn't work, missing base
• tests with workspace commit

Known Shortcoming

• Cannot create new dependent branch below the bottom-most commit of a stack even though that's theoretically possible. Can be fixed if needed.

Research

• create independent branch: create_virtual_branch()
• create dependent branch: create_branch(stack_id, order_info)

Performance Tasks

• 🏎️ Expensive computations only for a single stack (the one that updated)
• 🏎️ Use per-commit metadata to avoid recomputing changeset IDs for each commit, enabling processing more and more commits with the 1s compute budget.
• 🏎️ graph-based merge-base computation would be much faster if a bitmap was used. Could be intrinsic or separate, with intrinsic certainly being better.

Not to forget

• ⚠️Right now there is no occasion where branch-metadata would be deleted, so it's likely to go stale. Ideally we will be able to delete it as soon as it leaves our 'sphere of influence', but at the latest once the local branch doesn't exist anymore. Probably best to have a GC/cleanup step of sorts.
• ⚠️single-branch mode currently doesn't limit itself to only show what's not reachable by extra-target
• There might be an issue with the way it uses searches - a tip with a search might be blocked at an existing commit, discovered by a tip with a different search, and even though the thing it searches is reachable through that, it stops looking.
• the amount of commits of remotes ahead of their local branch doesn't seem to always match git (particularly when it's a lot of them)
• ⚠️ current implementation supports multiple workspaces in theory, but it's not tested with them as the underlying ref-metadata is still VB-toml. So before supporting this, we probably already want to have migrated away from vb.toml, to then port the ref-metadata to something that can support more workspaces (also for testing).
• ⚠️ we probably don't correctly handle workspaces that include other workspaces.
• ⚠️ we probably don't handle dot-repositories correctly, by merit of not really having them in mind. At least they shouldn't be in the way of handling normal remotes.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
gitbutler-components	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 1, 2025 6:27pm

[vercel]

@Byron is attempting to deploy a commit to the GitButler Team on Vercel.

A member of the Team first needs to authorize it.