A sketch on how to edit workspaces on a high-level

[Byron]

Takeaways

• There is an Editor that does all the heavy lifting and has access to the repo and workspace, with the workspace containing metadata as well.
• The editor performs simple operations, with a lot of it boiling down to a replace()
  • What to replace is governed by selections, which can be obtained from real-world ways of referring to commits (their SHA1), or references or stacks by name or stack-id.
  • Selections can be replaced with nothing for removals, or with one or more commits that have been prepared before.
  • higher-level operations like insert can probably be implement based on the replace primitive, if there is an advantage.
• The editor can return the new graph that represents all edits, as well as the edits that would be applied
  • worktree updates or the result of the (possibly dry-run of a) safe_checkout
  • all this can be introspected, and/or handed to the user for review
• finally, materialise these edits to take them 'would be' to reality

Technicalities

• The Graph as underlying data structure is useful as it has classification of commits, and as it can be traversed 'upwards'. This helps to select which commits are affected by edits.
• Edits should probably only be allowed within what's reachable by the workspace projection
• As the Graph and the workspace are their own data structures, editor-specific data has to be 'attached' using a separate mapping. Anything can be 'selected' by SegmentIndex and CommitIndex, maybe along with other markers as needed.

This will need a lot of tests, even once the API is sketched out and found to be suitable.

What changed since the brainstorming session

• edits are materialised directly, and the editor is consumed as part of producing these edits. That way it will be easier to implement, and user-input is expected to be provided as part of a repeated edit, on fresh data.

[vercel]

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

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
gitbutler-web	Ignored	Preview		Nov 4, 2025 4:43pm