How no-mistakes Validates Branches Before Pushing: A Three-Stage Safety Pipeline

no-mistakes validates branches through a coordinated three-stage pipeline that rebases onto the latest remote default, checks for potential work loss via force-push safety analysis, and executes pushes only with lease protection to guarantee no upstream commits are ever discarded.

The no-mistakes tool from the kunchenguid/no-mistakes repository implements rigorous branch validation to ensure every push operation is safe. By analyzing the source code in internal/pipeline/steps, we can see exactly how the tool prevents data loss through systematic checks before any Git push. The validation guarantees that a branch can only be pushed when the operation cannot lose work that already exists on the remote.

The Three-Stage Validation Pipeline

The validation logic spans three coordinated stages orchestrated across rebase.go, forcepush.go, and push.go. Each stage addresses a specific failure mode that could lead to lost work or messy history.

Stage 1: Rebasing onto the Remote Default Branch

Before any push, the pipeline fetches the remote default branch (origin/<default>) and rebases the feature branch onto it. This ensures the branch is built on the most recent upstream commits and eliminates merge conflicts that would arise from outdated bases.

The critical safety check here is detectBundledLocalDefaultCommits in internal/pipeline/steps/rebase.go. If the local default branch is ahead of the remote and those commits are ancestors of the feature branch, the function returns a NeedsApproval gate. This blocks the automatic push and forces human intervention to prevent silently bundling local default work into a feature branch push.

Stage 2: Force-Push Safety Decision

After rebasing, the pipeline calls resolveForcePushDecision in internal/pipeline/steps/forcepush.go to determine whether a force-push is safe. This function evaluates the current remote head against the lease anchor (lastSeenSHA) that the pipeline observed during its last fetch.

The function categorizes the push into three outcomes:

• New branch – The remote ref does not exist, so a plain push is allowed.
• Up-to-date – The remote already points to the commit we intend to push; the step skips the push entirely.
• Force-push with lease – When the remote head differs from lastSeenSHA, the function validates safety by comparing the current remote head with the lease anchor.

If the remote head does not match lastSeenSHA, the function runs remoteCommitsNotIncorporated, which fetches the remote tip and uses git rev-list --cherry-pick --right-only to identify commits on the remote that are not represented by the new head (by patch-id) and are not reachable from the known baseSHA. If any such commits exist, the function returns a forcePushWouldDiscardError, causing the push step to abort.

Stage 3: Final Push Execution

In internal/pipeline/steps/push.go, the pipeline constructs and executes the actual Git command based on the previous safety decision. If the decision indicates a force-push is required and safe, the code appends the --force-with-lease=<lastSeenSHA> flag to ensure the remote rejects the push if it has advanced beyond the lease anchor.

// From internal/pipeline/steps/push.go
if !decision.upToDate {
    args := []string{"push", pushURL, fmt.Sprintf("%s:%s", newHeadSHA, ref)}
    if !decision.newBranch {
        // Safe force-push with lease protection
        args = append([]string{"push", "--force-with-lease=" + decision.remoteSHA}, args...)
    }
    if out, err := gitRun(args...); err != nil {
        return stepResult{Status: stepFailed, Err: fmt.Errorf("push error: %w", err)}
    }
}

If the decision is up-to-date, the step skips execution. If new branch, it performs a plain push without force flags.

Key Implementation Files

The validation logic is distributed across specific files in the repository:

• internal/pipeline/steps/push.go – Orchestrates the push step, calls the safety decision, and runs the final git push command.
• internal/pipeline/steps/forcepush.go – Implements resolveForcePushDecision, lsRemoteSHA, and the remoteCommitsNotIncorporated check that prevents unsafe force-pushes.
• internal/pipeline/steps/rebase.go – Performs the rebase onto the remote default branch and calls detectBundledLocalDefaultCommits to catch bundled local commits.
• internal/pipeline/steps/forcepush_decision_test.go – Unit tests covering all branches of the force-push decision logic.
• internal/pipeline/steps/forcepush_safety_test.go – Integration-style tests verifying the safety check against real git repositories.

Summary

• Rebase validation ensures the branch is built on the latest remote default and detects bundled local default commits via detectBundledLocalDefaultCommits.
• Force-push safety evaluates three outcomes (new branch, up-to-date, or force-push) and uses git rev-list --cherry-pick to verify no remote commits would be discarded.
• Lease protection executes force-pushes only with --force-with-lease=<lastSeenSHA>, preventing overwrites of unseen remote work.
• Abort conditions return forcePushWouldDiscardError or NeedsApproval gates whenever the validation detects potential data loss.

Frequently Asked Questions

What happens if the remote branch has new commits I haven't seen?

If the remote head has advanced beyond the lastSeenSHA lease anchor, resolveForcePushDecision calls remoteCommitsNotIncorporated to compare commits by patch-id. If any remote commits are not incorporated into your local branch, the function returns a forcePushWouldDiscardError and aborts the push to prevent data loss.

How does no-mistakes detect bundled local default branch commits?

During the rebase stage in internal/pipeline/steps/rebase.go, the function detectBundledLocalDefaultCommits checks if your local default branch is ahead of the remote and whether those commits are ancestors of your feature branch. If so, it returns a NeedsApproval status, forcing human intervention before the push can proceed.

What is the difference between a regular push and a force-push with lease in no-mistakes?

A regular push occurs only when creating a new branch or when the remote is already up-to-date with your local commit. A force-push with lease is used when the remote diverges but the pipeline has verified safety; it appends --force-with-lease=<lastSeenSHA> to ensure the push fails if the remote has changed since the pipeline last observed it, preventing accidental overwrites of others' work.

Where is the primary push validation logic implemented?

The validation logic is distributed across three main files in internal/pipeline/steps: rebase.go handles pre-push rebasing and bundled commit detection, forcepush.go contains the safety decision logic including resolveForcePushDecision, and push.go executes the final Git command with appropriate lease protection.

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