10. Diffing, Merging, Checkpoints & Git
What This Subsystem Is and Why It Exists ¶
An agentic editor's whole value proposition is that it changes your code. But code changes are dangerous: the agent might touch 14 files, half of them wrong, while you simultaneously edit a 15th by hand. The subsystem that makes this safe is the change-management layer — the machinery that computes what changed, shows it to you cleanly, lets you accept or reject pieces, lets you undo an entire multi-file run as one atomic operation, and commits the result to version control with a sensible message.
Think of it as the airlock between the model's output and your real working tree. The model breathes a different, riskier atmosphere (it hallucinates, it edits stale files, it sometimes deletes too much). The airlock ensures nothing enters your repo without being diffed, reviewable, and reversible.
Three distinct problems live here:
- Diffing — turning "old file" + "new file" into a minimal, human-readable set of changes. This affects both UX (can a human review it?) and token cost (how much do we send to the model to describe an edit?).
- Merging / reconciliation — what happens when the file the agent edited is no longer the file that's on disk, because the user (or another tool, or a
git pull) changed it mid-run. - Checkpoints + Git — restore points so an entire agent task can be rolled back, plus integration with the real VCS for staging, commit messages, branches, and PRs.
These are not glamorous, but they are the difference between "I trust this tool with my repo" and "I'm scared to let it run."
How It Works, Step by Step ¶
The core edit loop ¶
- Model proposes an edit. Modern editors rarely ask the model for a whole rewritten file (too many tokens, too slow). Instead the model emits a targeted edit — a search/replace block, a unified-diff-style patch, or a structured "edit tool" call with
old_string/new_string. - Editor applies the edit to an in-memory copy, not directly to disk (or applies to disk but immediately snapshots first).
- A diff is computed between the pre-edit baseline and the post-edit content, hunk by hunk.
- The diff is rendered in the UI — inline green/red gutters, a side-by-side view, or a unified patch with per-hunk accept/reject controls.
- A checkpoint is recorded before the change lands, capturing enough state to revert.
- On acceptance, the change becomes the new baseline; on rejection, the baseline is restored.
- Optionally, the accumulated changes are staged and committed to Git with a generated message.
How a diff is actually computed ¶
A text diff is fundamentally the shortest edit script (SES) problem: given sequence A (old lines) and sequence B (new lines), find the minimal set of insertions and deletions to turn A into B. This maps to Longest Common Subsequence (LCS) — the lines that stay are the LCS; everything else is added or removed.
- Myers' algorithm (1986) is the default in Git and most tools. It runs in O(ND) time, where N = total length of both inputs and D = size of the edit script (the "edit distance"). When changes are small, D is small, so it's near-linear. It's optimal in the sense of producing a minimal edit script.
- Histogram diff (Git's faster modern option, derived from "patience") indexes the occurrence count of each line, anchors on rare/unique lines, and recurses. It's faster than Myers in practice and often produces more semantically meaningful hunks — it won't, for example, "shift" a closing brace into the wrong function.
- Patience diff matches only lines that appear exactly once in both versions as anchors, then recurses between anchors. It famously produces cleaner diffs when functions are reordered or when there are many identical lines (like
}or blank lines).
Why diff quality matters beyond aesthetics: when an editor sends an edit to the model (or asks the model to re-apply an edit), the patch is encoded as tokens. A noisy diff that says "deleted 40 lines, added 41 lines" costs far more tokens — and is far harder for both human and model to verify — than a tight diff that says "changed 1 line." Bad hunk boundaries also cause incorrect merges later. So the diff algorithm is on the critical path for cost, latency, and correctness, not just looks.
The "apply model" pattern ¶
Cursor popularized a two-model split that's now common:
- A large, smart model (Claude, GPT-class) decides what to change and emits a sketch — often a lazy diff with
// ... existing code ...placeholders. - A small, fast "apply" model (Cursor has described a specialized, fast model for this) takes that sketch plus the real file and produces the exact full edited file or a precise patch.
This exists because frontier models are great at intent but bad and slow at reproducing long files byte-for-byte. The apply model is fine-tuned for one job: merge a sketchy edit into a real file deterministically. It runs at very high tokens/sec (hundreds to ~1000+ tok/s in Cursor's published numbers) so the edit feels instant. The tradeoff: a second model means a second failure point, so editors validate the apply output (does it still parse? did line counts go insane?) before showing it.
Checkpoints and multi-file undo ¶
A single agent task ("add auth to the app") may edit many files across many turns. Users need to undo the whole thing, not click undo 40 times. The standard implementation:
- Before the run (and often before each step), the editor takes a snapshot of every file it's about to touch — sometimes the entire workspace state for files in scope.
- Each snapshot gets a checkpoint ID tied to a point in the conversation ("restore to here").
- Restoring writes the snapshotted content back to disk and discards intervening edits.
Implementations vary:
- Content snapshots: store the full bytes of each touched file (simple, robust, storage-heavy for big files).
- Shadow Git repo: keep a hidden
.gitseparate from the user's repo andgit commiton every checkpoint, so restore is justgit checkout <sha>. This is cheap (Git dedupes content) and gives you free history. Claude Code and several others lean on shadow/sidecar Git-style approaches; Cursor's checkpoint/restore is conversation-anchored. - Worktree or branch isolation: run the agent in a separate Git worktree or branch so the main working tree is never dirtied until you accept.
Git integration ¶
- Staging: accepted hunks are
git add-ed (often viagit add -p-style partial staging when only some hunks are accepted). - Commit message generation: the editor sends the staged diff (or its summary) to the model with a prompt like "write a conventional-commit message for this diff." It typically caps the diff size (e.g. truncate huge diffs, send file list + representative hunks) to control tokens.
- PR generation: similar, but uses the branch diff (
git diff main...HEAD) plus commit history to draft a title and body, then calls the GitHub/GitLab API orghCLI. - Branch/worktree per task: gives isolation so a long agent run doesn't block you, and so you can throw the whole branch away.
Reconciliation: When the File Changed Under the Agent ¶
This is the hardest correctness problem in the whole subsystem. The agent read foo.ts at version V0, spent 8 seconds thinking, and emits an edit assuming V0 — but you (or a formatter-on-save, or a git pull, or another agent) changed it to V1.
If the editor blindly writes the agent's full-file output, it silently clobbers your edit. If it blindly applies a line-based patch, the line numbers are now wrong and it corrupts the file.
Three-way merge to the rescue ¶
The robust answer is a three-way merge, exactly like Git's:
- Base = the version the agent read (V0).
- Ours = what's on disk now (V1, your concurrent edit).
- Theirs = the agent's intended result.
The merge computes "what did the agent change relative to base" and "what did the user change relative to base," then combines non-overlapping changes automatically and flags overlapping regions as conflicts (the <<<<<<< / ======= / >>>>>>> markers). Because the agent usually edits a different region than you, most of the time the three-way merge applies cleanly.
Detecting concurrent edits ¶
Editors detect that the file moved out from under the agent using:
- File hashes / mtime / version counters: snapshot a hash when the agent reads; compare before writing. Mismatch ⇒ reconcile, don't clobber.
- Editor document version: in VS Code, each
TextDocumenthas a monotonically increasingversion; the extension compares the version it edited against the current one. - Search/replace anchoring: tools like Aider and Claude Code prefer search/replace or
old_string→new_stringedits over line-number patches precisely because they're position-independent — they re-locate the target text in the current file, so concurrent edits elsewhere don't break them. If theold_stringis no longer found (or is ambiguous), the edit fails loudly instead of corrupting.
That last point is a key design philosophy: fail visibly rather than apply wrongly. A rejected edit the user can retry beats a silent miswrite.
Engineering Challenges and Tradeoffs ¶
Latency ¶
- Full-file rewrites are slow to generate and stream. The apply-model / speculative-edit pattern exists to hide this; Cursor has described speculative decoding tricks to stream edits faster.
- Diffing itself is cheap (milliseconds) until files get huge or there are thousands of hunks; histogram diff keeps it fast.
Cost (tokens) ¶
- Sending whole files both ways is the naive, expensive path. Targeted edits + lazy diffs (
// ... existing code ...) can cut the output tokens dramatically. - Commit-message and PR generation must cap diff size; a 5,000-line diff would blow the context window and cost real money, so editors truncate or summarize.
- Prompt caching of the unchanged file prefix reduces re-read cost across turns.
Quality / correctness ¶
- Minimal diffs (Myers) vs. readable diffs (histogram/patience) — sometimes the mathematically smallest edit script is the least human-meaningful.
- Whitespace and formatter-on-save churn create phantom diffs; many tools normalize whitespace or run the formatter before diffing.
Privacy ¶
- Snapshots and shadow repos store your source; they must live locally or in your own infra, not be shipped to a server. Enterprise buyers ask exactly this.
- Diffs sent for commit-message generation contain source code — same data-governance rules as any model call.
Scale ¶
- Workspace-wide snapshots for a monorepo are infeasible as raw copies; content-addressed (Git-like) storage that dedupes is the only sane approach.
- Thousands of simultaneous hunks (e.g. a codemod across 500 files) stress the review UI; editors group by file and lazy-render.
Concrete Technologies and Numbers ¶
- Myers O(ND): N = combined input size, D = edit distance. Default in Git (
--diff-algorithm=myers). - Histogram / patience:
git diff --histogram/--patience. Histogram is Git's recommended fast, high-quality option. - Unified diff format:
@@ -l,s +l,s @@hunk headers; the lingua franca for both UIs and model patches. git apply/patchwith fuzz factors and context lines (default 3 lines of context) for relocating hunks.- Git worktrees (
git worktree add) for per-task isolation without re-cloning. - Content-addressed storage: Git's blob/tree/commit object model dedupes snapshot content via SHA-1/SHA-256.
- Apply-model throughput: Cursor has publicly cited specialized fast-apply models running at very high tokens/sec to make edits feel instant.
How Leading Products Implement It ¶
- Cursor: Pioneered the lazy-edit + fast apply-model split and conversation-anchored checkpoints that let you restore the workspace to an earlier point in a chat. Rich inline diff review with per-hunk accept/reject; an "agent mode" that batches multi-file changes for one review pass.
- GitHub Copilot: Inline completions plus Copilot Chat/Edits and the Copilot coding agent, which works on a branch and opens a real PR — review happens in GitHub's normal PR diff UI, leaning on GitHub's mature review tooling rather than a bespoke one.
- VS Code: Provides the substrate —
TextDocumentversions, the WorkspaceEdit API, the built-in diff editor, and SCM/Git extension APIs. Many agents (including Copilot) ride on these primitives. The diff editor and "refactor preview" tree are reused for AI changes. - Zed: Native, fast editor with a built-in diff view; emphasizes low-latency multibuffer editing so AI edits across files render in one multibuffer you scroll through and accept.
- JetBrains (AI Assistant / Junie): Reuses JetBrains' very strong existing diff/merge tooling (its three-way merge UI is industry-leading) and local-history checkpoints (IDEA has had Local History for years — a built-in time machine independent of Git).
- Sourcegraph (Cody / "agents"): Focused on large-scale, repo-wide changes and batch changes that generate diffs across many repos and turn them into PRs — server-side diffing at scale.
- Continue (open source): Pluggable; applies edits via diffs and shows inline accept/reject; you can swap models freely.
- Aider (terminal): Uses search/replace blocks as its edit format and is Git-native — it auto-commits every AI change as a separate commit so undo is just
git reset. This makes its checkpoint story "your Git history is the checkpoints." - Claude Code (terminal/agent): Uses precise
old_string→new_stringedits (must match uniquely, else fail), shows diffs in the terminal for approval, and provides checkpoint/rewind to undo within a session. - Windsurf (Cascade): Agent-first flow with workspace checkpoints and a review surface for multi-file edits, plus diff-based revert of an agent step.
Where they differ most: who owns review. Copilot's coding agent pushes review into the GitHub PR; Cursor/Windsurf/Zed own an in-editor review surface; Aider/Claude Code push it into Git commits and the terminal. And how edits are encoded: full-file rewrite vs. lazy diff + apply-model (Cursor) vs. search/replace (Aider, Claude Code).
Failure Modes and Mitigations ¶
- Silent clobber of concurrent user edits → mitigate with version/hash checks + three-way merge; fail loudly when the base is stale.
- Patch applies at wrong location (line drift) → prefer position-independent search/replace over line-number patches; use fuzz + context lines; require unique match.
- Lazy-diff "swallowing" code — the model writes
// ... existing code ...and the apply step accidentally drops a real chunk → validate output (parse check, line-count sanity, no unexpected large deletions) before landing. - Phantom whitespace/formatter diffs → normalize whitespace or run the formatter before diffing; ignore EOL/whitespace-only hunks.
- Partial-accept inconsistency — user accepts hunk 2 but not hunk 1, leaving code that doesn't compile → editors recompute dependent hunks or warn; some force whole-file accept for interdependent changes.
- Checkpoint can't restore deleted/renamed files → snapshot must record deletions and renames, not just content edits; shadow-Git handles this naturally.
- Huge diffs break commit/PR generation → cap and summarize the diff sent to the model.
- Snapshot storage blowup in monorepos → content-addressed dedup (Git object model) instead of raw copies.
- Merge conflict markers committed by accident → scan for
<<<<<<</>>>>>>>before allowing commit.
Interview Talking Points ¶
- Diffing is the shortest-edit-script / LCS problem; Myers is O(ND) and minimal, histogram/patience are faster and produce more human-meaningful hunks. Diff quality drives both review UX and token cost.
- Editors avoid full-file rewrites: frontier model emits a lazy/targeted edit, a fast apply-model merges it into the real file deterministically (Cursor's pattern).
- The hardest problem is reconciliation: file changed under the agent. Solve with a three-way merge (base = what agent read, ours = disk now, theirs = agent's result) and detect drift via hashes / document versions.
- Position-independent search/replace edits (Aider, Claude Code) survive concurrent edits and fail loudly instead of corrupting — fail-visible beats apply-wrong.
- Checkpoints give whole-task undo across many files; best implemented as a shadow content-addressed (Git-like) store, or worktree/branch isolation.
- Git integration = partial staging (
add -p), model-generated commit messages / PRs from the diff (with diff-size caps), and branch/worktree per task for isolation. - Products differ on who owns review (in-editor vs. GitHub PR vs. Git commits) and edit encoding (full-file vs. lazy-diff+apply vs. search/replace).
Likely Interview Q&A ¶
Q1. Why not just have the model output the whole edited file every time? Cost, latency, and correctness. Whole-file output costs output tokens proportional to file size on every edit, streams slowly, and forces the model to reproduce hundreds of unchanged lines byte-for-byte — which it sometimes gets wrong. The standard fix is a targeted/lazy edit from the smart model (just the changed region, with // ... existing code ... placeholders) merged into the real file by a small, fast apply-model. This cuts output tokens dramatically, makes edits feel instant, and isolates the "reproduce exact bytes" job into a model fine-tuned for it. The cost is a second failure point, so you validate the apply result (parses? sane line delta?) before landing.
Q2. Explain Myers vs. histogram vs. patience and when you'd pick each. All solve the shortest-edit-script problem via LCS. Myers (O(ND)) is the default and produces a provably minimal edit script — good general choice; near-linear when changes are small. Patience matches only lines that are unique in both versions as anchors, then recurses; it shines when code blocks are reordered or there are many identical lines (braces, blanks), producing diffs that read the way a human thinks about the change. Histogram is patience's faster cousin — it anchors on low-frequency lines and is Git's recommended fast+readable option. For an AI editor I'd lean histogram: the diff isn't just shown to humans, it's also serialized into tokens, so meaningful hunk boundaries reduce both review friction and cost.
Q3. The agent read a file, took 6 seconds, and meanwhile the user edited it. How do you avoid corrupting the file? Detect and reconcile, never clobber. Snapshot a hash/version of the file when the agent reads it; before writing, compare to the current on-disk version. If it changed, run a three-way merge: base = the version the agent read, ours = current disk content, theirs = the agent's intended result. Non-overlapping changes merge automatically; overlaps become conflicts surfaced to the user. Separately, encoding edits as search/replace blocks instead of line-number patches makes most edits position-independent — they re-locate their target text, so an edit elsewhere in the file doesn't break them, and if the target text is gone, the edit fails loudly rather than writing to the wrong place.
Q4. How do you implement "undo the entire agent task" across 12 files? Take a checkpoint before the run (and ideally before each step) capturing every file in scope — including deletions and renames, not just edits. Tie the checkpoint to a point in the conversation. Restore writes the snapshot back and discards intervening changes. For storage, don't copy raw bytes for a monorepo — use a content-addressed, Git-like store (a hidden/shadow repo) so identical content dedupes and restore is just a git checkout <sha>. Worktree- or branch-per-task isolation is an alternative: the agent works off to the side and you discard the branch to "undo."
Q5. How do you generate a commit message or PR without blowing the context window? Send the staged diff to the model with a conventional-commit prompt — but cap it. For large diffs, send the file list plus representative hunks, or a summarized diff, rather than 5,000 raw lines. For PRs, use the branch diff (git diff main...HEAD) plus the commit history so the body reflects the whole change set. Prompt-cache stable parts. Always scan the staged content for leftover conflict markers and secrets before committing.
Q6. Per-hunk accept/reject sounds nice but can produce code that doesn't compile. How do you handle that? Interdependent hunks are the trap: accepting a function call but rejecting the function definition breaks the build. Mitigations: (a) detect dependencies between hunks and warn or force them to be accepted together; (b) recompute remaining hunks against the new baseline after each accept so offsets stay valid; (c) for tightly coupled edits, fall back to whole-file accept; (d) run a quick parse/typecheck after partial acceptance and flag breakage. The goal is to keep the working tree in a consistent state after every accept/reject action.
Q7 (system design). Design the change-application pipeline for a multi-file agent run in a shared monorepo, optimizing for safety and reviewability. I'd run the agent in an isolated Git worktree/branch so the user's main tree is never dirtied mid-run. On each file the agent reads, record a content hash + base snapshot. Edits are expressed as search/replace blocks (position-independent, fail-loud). Before writing, verify the base hash; on mismatch, do a three-way merge and surface conflicts. After each step, commit to a shadow/checkpoint store so any step is reversible. When the run finishes, compute a histogram diff per file, group hunks by file in a single review surface, and offer per-hunk accept/reject with dependency-aware grouping plus a post-accept parse check. On full acceptance, partial-stage accepted hunks (add -p style), generate a commit message from the capped diff, and either commit to the task branch or open a PR. Privacy: all snapshots and shadow history stay local/in the customer's infra; only the minimal diff needed for message generation goes to the model. This gives atomic undo (drop the branch), no clobbering (hash + three-way merge), and reviewability (grouped histogram diffs).
Q8 (system design / tradeoff). Your apply-model occasionally drops code when the smart model writes // ... existing code .... Walk through detecting and preventing this at scale. This is the lazy-diff swallowing failure. Prevention: constrain the edit format so the smart model marks regions explicitly and never paraphrases unchanged code; train/prompt the apply-model to treat placeholders as literal "keep" instructions. Detection (cheap, run on every edit): compare line counts and a structural hash of the unchanged regions before vs. after — if a region that should be untouched changed or shrank unexpectedly, reject. Run a parser/AST check: if the file no longer parses or top-level symbol count dropped without a corresponding deletion in the intended diff, flag it. Guardrail: cap unexpected deletion size — a single "small edit" that removes 200 lines is suspicious and should require explicit confirmation. At scale, log apply-model disagreements (cases where validation rejected the output) as a training/eval signal, and route uncertain applies to a slower, more conservative full-file regeneration as a fallback. The tradeoff is latency vs. safety: the fast path is great 99% of the time, so you keep it but gate it behind cheap validators and a conservative fallback for the rest.