Adopt equivalent server-rebased branches

[skarim]

After a stack was rebased on GitHub, gh stack rebase and gh stack sync fetched the rewritten branch tips but would not adopt them because the local branches had diverged from their remote-tracking refs. The commands then tried to rebase or push the stale local branches, often failing even though the server-side rebase had completed successfully.

This change snapshots branch tips before fetching and adopts a server-side rewrite only when the local branch was unchanged, the remote stack is still properly ordered, and git range-diff confirms the same commits in the same order. If both sides changed, commits differ, or the history contains merges, the command stops instead of overwriting either side.

Both rebase and sync now update local branches and stack metadata directly when a safe equivalent server rewrite is detected.

Testing

• go vet ./...
• go test -race -count=1 ./...
• Real-Git coverage for server-side rebase adoption through both rebase and sync
• Coverage for local-only changes, concurrent rewrites, reordered or changed commits, merge commits, and rollback after a partial ref-update failure

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[Copilot]

Pull request overview

Adds safe adoption of equivalent server-rebased stack branches.

Changes:

• Snapshots branch tips and validates rewritten histories with git range-diff.
• Integrates adoption into rebase and sync, including rollback handling.
• Adds tests and user documentation.

Show a summary per file

File	Description
cmd/utils.go	Implements snapshotting and remote-tip adoption.
cmd/utils_test.go	Tests adoption and rollback scenarios.
cmd/rebase.go	Adopts remote rewrites during rebase.
cmd/rebase_test.go	Adds end-to-end rebase and sync coverage.
cmd/sync.go	Integrates adoption into synchronization.
internal/git/git.go	Exposes range equivalence checking.
internal/git/gitops.go	Implements git range-diff validation.
internal/git/gitops_test.go	Tests equivalence, ordering, and merges.
internal/git/mock_ops.go	Adds range-diff mock support.
README.md	Documents adoption behavior.
docs/src/content/docs/reference/cli.md	Updates CLI reference.
docs/src/content/docs/guides/ui.md	Documents server-rebase workflow.
skills/gh-stack/SKILL.md	Updates agent command guidance.

Review details

Comments suppressed due to low confidence (2)

cmd/utils.go:998

• The earlier SHA comparison is not atomic with these destructive updates. Another Git process can advance a branch after it is checked at line 878, and ResetHard/branch -f will then overwrite that new local work even though the adoption path promises to stop when the local side changed. Update refs with an expected-old SHA (ideally as one ref transaction), and guard the checked-out branch before resetting its worktree.

		if update.branch == currentBranch {
			updateErr = git.ResetHard(update.remoteRef)
		} else {
			updateErr = git.UpdateBranchRef(update.branch, update.remoteSHA)
		}

cmd/utils.go:1005

• Rollback failures are discarded here. If restoring an already-adopted branch fails, the command reports only the later update failure and leaves the stack partially rewritten without telling the user which ref needs recovery. Collect and include every rollback error in the returned error (or make the updates transactional).

				if previous.branch == currentBranch {
					_ = git.ResetHard(previous.localSHA)
				} else {
					_ = git.UpdateBranchRef(previous.branch, previous.localSHA)

• Files reviewed: 13/13 changed files
• Comments generated: 1
• Review effort level: Medium