v3 apply: rebase support

[Byron]

Make apply() compatible with how most of the application works today

Follow-up of #10711.

Tasks

Turns out rebasing isn't necessary, because

• it's not a viable strategy to avoid merge conflicts (and we have one: unapply conflicting stacks)
• we don't care about changing where our worktree lives in relation to the target (so it's OK to bring in the future and change the effective base of the the worktree)
• the previous implementation did only rebase when a branch is in the past, but not if it's in the future. Thus the code already has to deal with the workspace base not being exactly what's in the vb.toml.

• test all the scenarios where rebasing isn't necessary
• add rebase support for apply() so it works similarly to how it works today
  • investigate 'base' related behaviour for more intuitive results when applying into an empty branch. When to use merge, when to use rebase.
  • make sure that rebase doesn't happen if it makes no sense, i.e. if there are multiple merge bases (or does it)?

Future Tasks

• a way to rebase entire graphs (cherry-pick merges, re-merge workspace commits), based on the graph

• unapply: make sure to also delete metadata, even if the branch isn't actually in the workspace.
• cherry-pick index as well (but only conflicts) - consider skipping but make sure it doesn't get lost
• make archived more sturdy in the light of applying/unapplying, to consider keeping the original copy of the now integrated part of the stack.
• proper worktree checkout handling - we must not checkout branches that are already checked out in any worktree (see gix code somewhere)
• 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
• 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.
• unapply: must take care of assignments (see research)
• don't apply the target branch!
• 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.
  • But that's OK as we don't currently store stashes anyway for a lack of UI support to try to apply them.

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]

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

A member of the Team first needs to authorize it.