Prompting Agents for Git Rebase Conflicts

Agent rebase conflict handoff is not “rewrite the whole branch.” It means passing only the conflicted files for the stopped commit, with success defined as clean markers → git add → (gated) git rebase --continue. Grounded in git-rebase. No pricing, plans, affiliates, or invented product UI.

When rebase hits a conflict, Git stops on the problematic commit and leaves conflict markers. The documented choices are (1) resolve then --continue, (2) --abort to restore the pre-rebase state, (3) --skip to drop the current patch. Default agents to (1) only; keep skip/abort, history rewrites, and force-push behind a human gate.

How do you pass conflict files?

One-line answer: List unmerged paths only from git status, and put those files plus a one-line intent into the prompt. Do not dump the whole tree, chat logs, or “just finish the rebase.”

Handoff order aligned with git-rebase:

  1. Status snapshot — git status (or git diff --name-only --diff-filter=U) for conflict paths. See which commit stopped with git rebase --show-current-patch.
  2. Scope lock — Write an allowlist of paths in the prompt (e.g. src/foo.ts, src/bar.ts). Ban edits outside it, bulk formatting, and lockfile churn.
  3. One-line intent — Prefer product intent over “ours/theirs” labels. Example: “Keep upstream API renames; port our new guard onto the new symbols.”
  4. Forbidden commands — Explicitly ban git rebase --skip, git rebase --abort, git push --force, reset --hard, and checking out other branches.
  5. Deliverable — Agent removes markers, applies intent, git add <paths> only. Run --continue after human review, or only after an automated gate (no markers, no out-of-allowlist diff).

Copy-paste prompt skeleton:

Context: git rebase stopped on a conflict. Do NOT skip/abort/force-push.
Allowed paths only:
  - path/a.ts
  - path/b.ts
Intent (one line): <keep upstream rename; port our guard onto new names>
Steps:
  1) Read only allowed paths; resolve conflict markers (<<<<<< ======= >>>>>>)
  2) git add <allowed paths only>
  3) Stop. Report: resolved files, remaining markers (must be none), git status
Do not edit other files. Do not run git rebase --continue until I say so.

Do not pass: secrets/.env, unrelated huge diffs, open-ended “bring the whole repo up to date.” If the agent is isolated in a worktree, fix cwd to that worktree (git-worktree-agent axis).

What counts as success?

One-line answer: Allowed paths have no conflict markers, unmerged paths are staged, there is no diff outside the allowlist, and only then does git rebase --continue move to the next commit or finish the rebase.

Success checklist:

CheckPass criteria
MarkersNo <<<<<<< / ======= / >>>>>>> left in allowed files (rg / git grep)
IndexConflict paths git added; git status shows no unmerged paths
Scopegit diff --cached --name-only ⊆ allowlist; no format/lock/generated churn
IntentOne-line Intent matches the hunks (renames, guard placement)
ContinueHuman (or gate) runs --continue. Commit-message editor policy is team-local
RegressionAgreed minimum tests/build pass when applicable. “Agent said done” is not evidence

Per the docs, --continue restarts rebasing after a merge conflict is resolved. If resolution emptied the patch, --skip may be correct instead—but skip discards that commit’s changes, so it is not the default success path. If the agent reports “no changes left,” a human inspects git status / git diff and chooses skip, continue, or abort.

Treat as failure:

  1. Edits or deletes outside the allowlist
  2. git add with markers still present
  3. Blind “take entire side” that contradicts Intent
  4. Attempts at --skip / --abort / force-push
  5. Commits on a branch that is not the in-progress rebase

When must a human resolve?

One-line answer: Stop agent handoff when semantic conflicts, security, history, or shared branches are on the line—resolve manually or --abort.

Human-only cases:

SituationWhy
Schema, migrations, auth, payments, permissionsWrong side → data/auth incidents
Secrets, keys, license/legal textAuto-merge and log leakage risk
Binaries, generated trees, huge lockfilesHard to judge intent; expensive review
Same line needs both meaningsOne-line Intent is not enough; domain owner decides
Interactive todo edits (--edit-todo), squash/fixup reorderHistory rewrite; outside default agent scope
Rebase of already-pushed shared branch + forceCollaboration / CODEOWNERS territory
Many successive conflict stops or scope explosionHuman gate per stop; never “solve everything” in one prompt
Agent proposes skip or the patch becomes emptySkip drops a commit; human confirms

Practice rules:

  1. One stop at a time — only current unmerged paths. After continue, if another conflict appears, issue a new prompt with a fresh allowlist.
  2. Abort is the safety net — unclear intent or scope drift → git rebase --abort, then split work or resolve by hand.
  3. Skip is exceptional — only after a human confirms “discard this commit on purpose.”
  4. Separate review axis — how a human reads the resolved diff before merge: agent-diff-review. Worktree isolation: git-worktree-agent.

Warning: Do not tell the agent “if you hit conflicts, skip and finish.” In git-rebase, --skip is an explicit choice to skip the current patch.

FAQ

How should I explain ours/theirs to the agent?

Label confusion is common during rebase. Prefer a one-line Intent (keep upstream renames; port our guard) over side names. Attach git rebase --show-current-patch when helpful.

Can the agent run git rebase --continue?

Yes if the team has automated gates for markers, allowlist, and status. Default recommendation: agent through git add, human for continue. Continue may open a commit-message editor (merge backend).

How is this different from generic merge-conflict guides?

Marker → add is similar, but rebase replays commits in order, so --continue / --skip / --abort mean different things. This post focuses on the rebase stop + agent prompt boundary.

What if there are too many conflicts?

--abort, split the branch, or rebase in smaller upstream steps. Do not dump dozens of files into one prompt.

Sources