Architecture Note: TowerGit Interactive Rebase Feature

Requirements

TowerGit’s interactive rebase must let a user visually pick, reorder, edit, squash, or drop commits on a local branch while guaranteeing that the original state can be restored if the operation is cancelled. The workflow should be confined to the local repository until the user explicitly pushes, and it must surface any merge conflicts through TowerGit’s built‑in conflict resolution UI.

Smallest Suitable Design

The minimal implementation consists of a modal window that appears when the user selects “Interactive Rebase” from a branch’s context menu.

• Commit list: a linear, scrollable view of each commit in the chosen range, displayed with its abbreviated hash and subject line.
• Action controls: for each entry, checkboxes or toggle buttons labelled pick, edit, squash, and drop. Drag‑and‑drop handles allow reordering.
• Preview pane: when a commit is selected, a read‑only diff shows the changes introduced by that commit.
• Action bar: buttons labelled Start Rebase and Cancel. Starting the operation creates a temporary ref (refs/towergit/rebase‑<uuid>) that points to the current HEAD.

All UI state lives in the modal; no background processes are spawned until the user clicks Start Rebase.

Trust and Data Boundaries

The feature operates exclusively on the local repository:

• It reads commit objects from .git/objects and writes only to the temporary ref and the reflog.
• No network calls are made until the user explicitly invokes a push after the rebase finishes.
• The temporary ref is isolated from normal branch refs; on abort or completion it is deleted, leaving the original refs untouched.

Thus the trust boundary is the user’s local machine; TowerGit never trusts remote state during the rebase.

Operational Checks Before Starting

Before enabling the Start Rebase button, TowerGit performs the following validations:

1. Confirm that HEAD points to a branch (not a detached HEAD) unless the user has opted for a detached‑HEAD rebase.
2. Verify that no other rebase, merge, or cherry‑pick operation is currently active by checking for the presence of rebase-apply, rebase-merge, or MERGE_HEAD files in .git.
3. Ensure the index is clean (no unresolved merge conflicts) by inspecting git diff-index --quiet HEAD --.
4. If any check fails, the UI displays an inline explanation and disables the start button.

Failure Modes and Recovery

Two primary failure categories exist:

• Merge conflict during replay: TowerGit pauses the rebase, leaves the index in a conflicted state, and opens its conflict resolution pane. The user can resolve the conflict, then choose Continue to proceed or Abort to cancel.
• Unexpected termination** (e.g., power loss, crash): the temporary ref remains, and HEAD points to a state labeled “rebasing”. Recovery is possible by running either git rebase --abort or git reset --hard ORIG_HEAD from the command line, or by using TowerGit’s “Abort Rebase” menu item, which restores the original branch tip via the reflog entry created at the start of the operation.

In both cases, the original commits remain reachable via reflog for at least the default 90‑day grace period, allowing a manual reset if needed.

Conditions That Would Change the Design

The current design assumes a purely local, user‑driven workflow. If TowerGit were to support interactive rebases on shared or public branches, additional safeguards would become necessary:

• Server‑side force‑push protection checks (e.g., verifying that the remote branch is not protected or that the user has explicit override permission).
• Integration with CI systems to block rebases after a successful build, preventing history rewrite after artifacts have been published.
• A distributed conflict‑resolution workflow where conflicting changes are presented to all affected contributors before the rebase can be finalized.

These requirements would shift the architecture toward a server‑mediated approval model, where the modal UI would act as a client that proposes a rebase plan and waits for server acknowledgment before mutating any refs.

Practical Verification Steps

To confirm that the feature behaves as described, a tester can follow these steps in a throw‑away repository:

1. Create a repository with at least five commits: git init test-repo && cd test-repo && for i in {1..5}; do echo "Commit $i" > file.txt && git add file.txt && git commit -m "Commit $i"; done
2. Open TowerGit, select the master branch, and choose “Interactive Rebase” from the context menu.
3. Verify that the modal shows a list of the five commits with pick/edit/squash/drop controls and a diff preview pane.
4. Select the second and third commits, change their action to squash, and click Start Rebase.
5. After the rebase completes, check that the commit count is now four and that the new commit message contains the squashed messages (use git log --oneline).
6. Confirm that the original commits are still reachable via git reflog.
7. To test conflict handling, edit file.txt in both the first and fourth commits, then repeat the rebase. TowerGit should halt and show its conflict resolution UI.
8. Abort the rebase via the menu or git rebase --abort and verify that git rev-parse master returns the original hash before the rebase began.

These steps exercise the UI, the temporary ref mechanism, conflict handling, and abort/recovery paths without relying on any external systems.