Architecture Note: Implementing Visual Interactive Rebase in Tower

The Problem: Visualizing History Rewrites

Git's native interactive rebase requires users to edit a text-based "todo" list in a terminal editor, which is prone to syntax errors and provides no visual feedback on the resulting graph until the process is complete. Tower solves this by abstracting the git rebase -i sequence into a drag-and-drop interface, ensuring that the rewritten history is predictable and validated before execution.

Requirements

The system must allow users to reorder, squash, edit, or drop commits while maintaining strict adherence to Git's internal state machine. Key requirements include:

• Read Access: Ability to parse .git/objects and .git/refs to build the commit chain.
• Write Access: Permission to modify the temporary rebase-todo file and update the branch reference (ref) being rewritten.
• Safety: Prevention of accidental history loss by leveraging ORIG_HEAD for recovery.

Smallest Suitable Design

The feature is implemented via three decoupled components to minimize the risk of repository corruption:

1. The Todo Generator: Walks the commit chain from the current HEAD back to the specified base commit. It translates this chain into a list of instructions (pick, squash, edit, reword, drop) compatible with the Git backend.
2. The Visual Editor: A UI layer that represents the todo list as a draggable table. Dragging a row changes the commit order; a dropdown menu changes the action. This layer does not touch the repository directly.
3. The Executor: The bridge to the CLI. It writes the final validated instructions to .git/rebase-merge/git-rebase-todo and invokes git rebase --continue, capturing stdout/stderr to report progress or errors to the user.

Trust and Data Boundaries

To maintain repository integrity, Tower enforces strict boundaries on where it modifies data:

Boundary	Access Level	Scope
Commit Objects	Read-Only	.git/objects (used for graph rendering)
Rebase State	Read/Write	Temporary todo files in .git/rebase-merge/
Branch Refs	Write	The specific ref being rebased (e.g., refs/heads/feature)
Remote Refs	No Access	Remote branches are never touched during the rebase process.

Operational Checks

Before the Executor triggers the Git process, Tower performs three critical checks:

• Syntax Validation: Ensures every line in the generated todo file matches the required pattern: ^(pick|reword|edit|squash|fixup|drop)\s+[0-9a-f]{40}.
• Reachability Check: Verifies that every commit SHA in the todo list is still an ancestor of the current HEAD to prevent "missing commit" errors.
• Graph Preview: Simulates the resulting commit sequence to show the user the expected outcome before the actual rewrite begins.

Failure Modes and Recovery

Interactive rebasing is a destructive operation. Tower handles common failures as follows:

• Merge Conflicts: When Git pauses due to a conflict, Tower detects the state, highlights the conflicted files, and provides a resolution dialog. The user can then choose to continue or abort.
• Concurrent Modifications: If an external process modifies the branch ref during the rebase, Tower detects the mismatch between the current ref and ORIG_HEAD, aborts the operation, and restores the original state.
• Detached HEAD: If the user is not on a named branch, Tower disables the interactive rebase option to avoid ambiguity regarding which ref should be updated.

Conditions for Design Change

The current architecture assumes a linear commit history. The design would require significant changes if the following were introduced:

• Non-linear Rebasing: Supporting --rebase-merges would require the Todo Generator to handle merge edges and the UI to move from a list to a graph-based editor.
• Server-Side Validation: If Tower were to integrate with remote protection rules (e.g., preventing rebases on protected branches), the trust boundary would extend to the remote API for pre-flight checks.

Practical Verification

To verify the implementation of a squash operation:

1. Open a local repository with a branch containing at least three commits.
2. Select Interactive Rebase and set the base to a commit three positions back.
3. In the UI, change the action of the second commit from pick to squash.
4. Execute the rebase.
5. Verification: Check the log view; the commit count should decrease by one, and the resulting commit message should be a concatenation of the two squashed commits.

Rollback: If the result is unsatisfactory, run git reset --hard ORIG_HEAD in the terminal to return the branch to its pre-rebase state.