How the no-mistakes Rebase Step Fetches Fresh Remote State Safely

The no-mistakes rebase step prevents overwrites of unseen remote commits by detecting force-pushes before fetching, synchronizing the default branch unconditionally, and selectively updating branch-tracking refs to preserve the lease anchor used by subsequent push operations.

The rebase step serves as the entry point for every pipeline run in kunchenguid/no-mistakes, establishing a verified foundation for all subsequent git operations. As implemented in internal/pipeline/steps/rebase.go, this step employs a multi-layered fetching strategy that balances currency with safety, ensuring the local worktree reflects the latest upstream state without risking data loss.

Detecting Force-Pushes Before Network Operations

Before initiating any network requests, the step evaluates whether the contributor has rewritten branch history. At line 48 of internal/pipeline/steps/rebase.go, the code invokes isForcePushAgainstRemote to check if the current operation constitutes a force-push against the remote repository.

This early detection is critical because it determines the behavior of all subsequent fetch operations. When isForcePushAgainstRemote returns true, the step deliberately avoids refreshing the branch-tracking ref that the later push step uses as a lease anchor. According to the source comments at lines 55-63, this prevents the lease's fast-path from silently discarding out-of-band remote commits, addressing the hazards originally identified in issues #281 and #305.

Unconditional Default Branch Synchronization

Regardless of the force-push status, the step always fetches the latest upstream state of the default branch. Lines 50-52 invoke git.FetchRemoteBranch for origin/<default-branch> on every run:

sctx.Log("fetching latest upstream state...")
if err := git.FetchRemoteBranch(ctx, sctx.WorkDir, "origin", defaultBranch); err != nil {
    sctx.LogFile(fmt.Sprintf("warning: could not fetch origin/%s: %v", defaultBranch, err))
}

This unconditional fetch guarantees that the rebase operation uses the most recent upstream tip, even when the contributor's local copy is stale or when working on a feature branch far behind the default branch.

Conditional Branch Ref Fetching Strategy

The handling of branch-specific remote-tracking refs depends on both the force-push status and the remote configuration. For normal pushes (non-force-push scenarios) where the current branch differs from the default branch, the step proceeds to fetch the branch-specific ref at lines 64-71.

When working with a standard upstream (where pushRemote == "origin"), the step calls git.FetchRemoteBranch. However, when the repository uses a fork remote (pushRemote != "origin"), the step instead invokes git.FetchRemoteBranchToRef to update the fork-specific ref (forkBranchTrackingRef):

if !forcePush && branch != "" && branch != defaultBranch {
    if pushRemote == "origin" {
        // Standard upstream.
        _ = git.FetchRemoteBranch(ctx, sctx.WorkDir, "origin", branch)
    } else {
        // Fork remote – fetch into the fork‑specific ref.
        _ = git.FetchRemoteBranchToRef(ctx, sctx.WorkDir,
            pushRemote, branch, branchTarget)
    }
}

Protecting the Lease Anchor on Force-Push

When a force-push is detected, the step intentionally leaves the fork-branch tracking ref stale. This behavior, implemented at lines 55-63, serves a critical safety function: the subsequent push step relies on git.PushWithLease anchored to the last observed SHA.

By preserving the stale ref during a force-push scenario, the lease mechanism can detect any out-of-band commits that arrived since the last fetch. If new commits exist on the remote, the lease check fails and aborts the force-push, preventing the contributor from accidentally overwriting work they have not seen.

Constructing Rebase Targets from Verified State

Only after the remote state is fully synchronized does the step construct the list of rebase targets. At lines 97-101, the code builds rebaseTargetsForBranch and forcePushRebaseTargets based on the freshly fetched refs:

// Build rebase targets based on fetched state
rebaseTargets := rebaseTargetsForBranch(branch, defaultBranch, fetchedRefs)
if forcePush {
    rebaseTargets = forcePushRebaseTargets(rebaseTargets, sctx.Run.BaseSHA)
}

The step then proceeds with either an automatic agent-assisted rebase or a conflict-aware dry-run, confident that all target SHAs represent verified remote state.

Summary

• Early force-push detection via isForcePushAgainstRemote at line 48 determines fetch behavior before any network operations occur.
• Unconditional default branch fetching ensures the rebase always references the latest upstream tip, regardless of local state.
• Conditional branch fetching updates remote-tracking refs only for normal pushes, using git.FetchRemoteBranch for standard remotes and git.FetchRemoteBranchToRef for forks.
• Lease anchor protection deliberately preserves stale refs during force-pushes, allowing git.PushWithLease to detect and prevent overwrites of unseen commits.
• Deferred target construction at lines 97-101 ensures all rebase operations use verified, freshly fetched state.

Frequently Asked Questions

What happens when the rebase step detects a force-push?

When isForcePushAgainstRemote identifies a force-push at line 48, the step skips updating the branch-tracking ref that serves as the lease anchor for the subsequent push operation. This intentional staleness ensures that git.PushWithLease can detect any out-of-band commits that arrived on the remote since the last fetch, aborting the push if unseen work would be overwritten.

Why does the step fetch the default branch unconditionally?

The step invokes git.FetchRemoteBranch for origin/<default-branch> on every run (lines 50-52) to guarantee that rebase operations always use the latest upstream tip. This prevents scenarios where a contributor's locally cached default branch is stale, ensuring accurate merge-base calculations and conflict detection regardless of how long the local repository has been disconnected.

How does the rebase step handle fork remotes differently?

When pushRemote != "origin", indicating a fork workflow, the step uses git.FetchRemoteBranchToRef instead of the standard git.FetchRemoteBranch. This specialized fetch updates the fork-specific tracking ref (forkBranchTrackingRef) rather than the standard origin refs, ensuring that lease anchors correctly reference the fork's state while maintaining separation from the upstream origin repository.

What prevents the rebase step from overwriting remote commits I haven't seen?

The step combines force-push detection with lease anchor management to prevent overwrites. By preserving the previous remote-tracking ref state when force-pushes are detected (lines 55-63), the subsequent git.PushWithLease operation compares against the last observed SHA rather than a freshly fetched one. If new commits exist on the remote, the lease check fails, forcing a manual resolution rather than silently discarding the unseen work.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}