V3 apply/unapply

[Byron]

With stashing available, a single-branch aware version of branch apply and unapply is possible.

Follow-up of #9874.

Tasks

• Permutations: starting point
  • test unborn
  • starting point without WS ref
  • starting point with WS ref but not WS-commit or metadata
  • starting point with WS ref and WS commit
• Permutations: base position
  • base below
  • base above
• but_workspace::checkout()
  • apply conflict
  • apply worktree snapshot conflict
  • unapply worktree snapshot conflict
• Validate StackID handling in VB.toml adapter (assure it can keep unapplied branches correctly)
  • We need all the tests so at a later point we can possibly localise the stack-id and keep it with each branch instead.
• without single-branch mode, it's possible to have a workspace with just one stack, or even no stacks at all.
• try to fix but-graph issue

Shortcomings

• Worktree change in a detached HEAD can't be stashed as there is no reference to associated the stash with.

Notes

General Rules

• The workspace is a conflict-free zone
  • nothing that operates on the conflict must write conflicts into the index.
    This is as conflicts are currently hidden from view.
• Symmetry
  • If apply is doing something, then unapply undoes exactly that, or in other words State + apply + unapply == State
• There is no single-branch workspace when starting in single-branch mode
  • A workspace consists of at least two branches and a workspace commit
  • The workspace commit is optional if there is only one commit involved, i.e. when it's just a bunch of branches on top of a single commit
• Workspace Commit ALWAYS for even for a single branch
  • The workspace backend can deal with anything, but commit() currently can't.
  • Have to add commit() and uncommit() as well to all apply-unapply tests so these can later be re-tested with different behaviour.
  • Implied by the previous rule

Follow-Ups

• commit with auto-workspace-commit creation
  • At the same time, it needs uncommit() that is symmetric

Thus:

• snapshots of worktree changes will be made to apply by forcing merge-conflicts to be... auto-resolved.
  This is a problem, but we can't have conflicts as the UI doesn't show them right now, nor does it allow interacting with them.

Unapply

• Conflicting paths are passed added as extra commit at first, without additional special handling in apply just to be able to handle them.
  • This means assignments aren't taken care of in all cases (but we will see how all this interacts with stack-ids)

Research

Unapply: Assignments - with stashing

• uncommitted but assigned changes should create a snapshot commit
• when applying the same branch this snapshot is applied

However, the user should be able to interact with these.

Unapply: Assignments - with WIP commit

• uncommitted but assigned changes should create a WIP commit
  • or just unassign these assignments and they are back in the unassigned changes of the workspace
• MVP apply: do nothing with the WIP commit
• final version: apply restores the assignments from the WIP commit (which then is tracked with metadata)

Unapply with worktree changes

• worktree changes that don't re-apply cleanly

Possible Follow-Ups

• Find a way to display and handle conflicts in the UI (Gitizen).
  • this would allow us to write conflicts as well and deal with them.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
gitbutler-components	Ready	Preview	Comment	Aug 28, 2025 3:30am

[vercel]

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

A member of the Team first needs to authorize it.