diff --git a/web/docs/how-to/customizing-settings.md b/web/docs/how-to/customizing-settings.md index 44dca631..2d57866b 100644 --- a/web/docs/how-to/customizing-settings.md +++ b/web/docs/how-to/customizing-settings.md @@ -52,7 +52,7 @@ Toggle line numbers, the minimap, word wrap, and whitespace visibility. Pick a s **Commit settings** turn on auto-stage, which we do not recommend, set a commit message template, and add validation rules such as a maximum length or a requirement for conventional commits. -**Merge settings** choose the default strategy, the conflict style, and whether Treq stashes your work before an operation. +**Merge settings** choose the default strategy, the [conflict style](/learn/concepts/git/zdiff3), and whether Treq stashes your work before an operation. | Setting | Options | | --- | --- | diff --git a/web/docs/tutorials/merging-workspaces.md b/web/docs/tutorials/merging-workspaces.md index ef9336c3..9ac8c576 100644 --- a/web/docs/tutorials/merging-workspaces.md +++ b/web/docs/tutorials/merging-workspaces.md @@ -22,7 +22,7 @@ Review the summary carefully, then confirm the merge. After the merge completes, ## Handling Conflicts -Treq only opens the merge preview once the workspace has no conflicts against the target branch. If conflicts exist, resolve them in the workspace first: open the affected files, resolve the conflict markers, and commit the resolution. +Treq only opens the merge preview once the workspace has no conflicts against the target branch. If conflicts exist, resolve them in the workspace first: open the affected files, resolve the conflict markers, and commit the resolution. Git's [zdiff3](/learn/concepts/git/zdiff3) conflict style can make those markers easier to read before you edit. For agent-driven stacks, see [How to Fix Merge Conflicts Created by Coding Agents](/learn/how-to/merge-conflicts-with-coding-agents). For large conflicts, pause and make sure the target branch is up to date before continuing. Pull the latest main branch, resolve conflicts in the workspace, and retry once tests pass. The merge preview becomes available as soon as the workspace is conflict-free. diff --git a/web/learn/concepts/git/index.mdx b/web/learn/concepts/git/index.mdx index acabf8f3..c0a03dee 100644 --- a/web/learn/concepts/git/index.mdx +++ b/web/learn/concepts/git/index.mdx @@ -35,6 +35,11 @@ Start with Git's data model, then learn how to manage parallel and dependent bra href: "/learn/concepts/git/merge-vs-rebase", label: "Merge vs Rebase", }, + { + type: "link", + href: "/learn/concepts/git/zdiff3", + label: "What is zdiff3?", + }, { type: "link", href: "/learn/concepts/git/cherry-pick-vs-rebase", diff --git a/web/learn/concepts/git/merge-vs-rebase.mdx b/web/learn/concepts/git/merge-vs-rebase.mdx index f9a792e9..458894ba 100644 --- a/web/learn/concepts/git/merge-vs-rebase.mdx +++ b/web/learn/concepts/git/merge-vs-rebase.mdx @@ -109,11 +109,12 @@ Each option throws away something different. Merge commits keep the shape. Squas Block force pushes on shared branches. If feature branches can be rewritten, say so out loud, so reviewers know whether it is safe to build on one. -After a big rebase, use `git range-diff` to check the rewritten series still says what you meant. Run the full test suite after you resolve conflicts, whichever strategy you picked. +After a big rebase, use `git range-diff` to check the rewritten series still says what you meant. Run the full test suite after you resolve conflicts, whichever strategy you picked. [zdiff3](./zdiff3) makes conflict markers easier to read when both sides share surrounding lines. ## Next Steps - [Cherry-pick vs Rebase](./cherry-pick-vs-rebase): distinguish selected patch copying from branch rewriting +- [What is zdiff3?](./zdiff3): shrink conflict markers while keeping the merge base - [What are Stacked PRs?](./stacked-prs): manage branches that depend on one another - [Stacked PR Workflow](/learn/workflows/git/stacked-pr): apply rebasing to a pull-request stack - [Parallel Development Workflow](/learn/workflows/git/parallel-development): combine integration policy with concurrent branch work diff --git a/web/learn/concepts/git/zdiff3.mdx b/web/learn/concepts/git/zdiff3.mdx new file mode 100644 index 00000000..f40567ec --- /dev/null +++ b/web/learn/concepts/git/zdiff3.mdx @@ -0,0 +1,148 @@ +--- +sidebar_position: 6 +description: Git's zdiff3 conflict style shows the merge base and shrinks conflict markers by moving shared prefix and suffix lines outside the conflict. +--- + +import DefinitionCard from "@site/src/components/DefinitionCard"; + +# What is zdiff3? + +_Zealous Diff3 shows the merge base and pulls identical boundary lines out of the conflict markers._ + +When a [merge or rebase](./merge-vs-rebase) stops on conflicting edits, Git writes conflict markers into the file. The default layout shows only your side and the incoming side. **zdiff3** keeps the three-way view from `diff3` and then shrinks the marked region so you resolve the lines that actually disagree. + +## Introduction + +Git's `merge.conflictStyle` setting controls how conflicted files look while you resolve them. It does not change how Git computes the merge result. It only changes how much history Git prints between the conflict markers. + +The default style is `merge`. It shows `ours` and `theirs`. That is enough when you already know both edits. It fails when you need the pre-divergence text to decide which lines to keep, combine, or rewrite. + +## Understanding the Concept + +A **three-way merge** compares three snapshots: your tip, the tip being merged, and their common ancestor. When both tips changed the same region differently, Git cannot auto-combine them and leaves a conflict for you to resolve. + + + +The **`diff3`** conflict style adds that ancestor as a middle section marked with `|||||||`. You see what the file looked like before either branch edited it. That context is often the difference between guessing and reconstructing intent. + + + +**zdiff3** (Zealous Diff3) extends that layout. After Git builds the three sections, it finds identical lines at the start or end of the conflicting hunk and moves those shared boundaries outside the markers. Think of the markers as a highlighter that covers only the disputed middle, not the surrounding lines both sides already agree on. + + + +| Style | Shows base? | Conflict region | +| --- | --- | --- | +| `merge` | No | Full overlapping edit from yours and theirs | +| `diff3` | Yes | Full overlapping edit, including shared edges | +| `zdiff3` | Yes | Overlap trimmed of identical prefix and suffix lines | + +`diff3` and `zdiff3` present the same three sides. The difference is which lines sit inside the markers. `diff3` leaves the whole contiguous block marked. `zdiff3` strips the agreed edges so the markers surround the minimal divergent core. + +## Applying It in Practice + +Require Git 2.35 or later, then set the style globally: + +```bash +git config --global merge.conflictStyle zdiff3 +``` + +Or set it for one repository: + +```bash +git config merge.conflictStyle zdiff3 +``` + +If a conflict is already written with another style, regenerate one file: + +```bash +git checkout --conflict=zdiff3 path/to/file +``` + +Compare the three presentations on the same conflict. Both sides keep the same surrounding lines and only disagree in the middle: + +Default `merge`: + +```text +1, +foo, +bar, +<<<<<<< HEAD +======= +quux, +woot, +>>>>>>> side +baz, +3, +``` + +`diff3` adds the ancestor, but still marks the shared edges: + +```text +1, +<<<<<<< HEAD +foo, +bar, +baz, +||||||| 60c6bd0 +# add more here +======= +foo, +bar, +quux, +woot, +baz, +>>>>>>> side +3, +``` + +`zdiff3` keeps the base and moves `foo`, `bar`, and `baz` outside the markers: + +```text +1, +foo, +bar, +<<<<<<< HEAD +||||||| 60c6bd0 +# add more here +======= +quux, +woot, +>>>>>>> side +baz, +3, +``` + +You still decide how to combine the middle. The shared frame no longer looks like part of the dispute. + +## Engineering Considerations + +`zdiff3` is a presentation choice. It does not auto-resolve conflicts, change merge strategies, or replace tests after you finish editing. Resolve the markers, stage the files, and continue the merge or rebase as usual. + +Prefer `zdiff3` when conflicts span multi-line regions with identical wrappers on both sides: shared imports, braces, trailing returns, or list delimiters. Prefer plain `diff3` only when you want every line of the overlapping block kept inside the markers for inspection. Prefer `merge` when you already know both sides and want the shortest marker text. + +Editors and merge tools may reformat or hide conflict sections. Confirm that your tool still shows the `|||||||` base section when you rely on three-way context. If a GUI collapses the base, fall back to the working-tree file or regenerate with `git checkout --conflict=zdiff3`. + +## Scaling and Operations + +Set `merge.conflictStyle` in a shared team docs page or onboarding checklist so local clones agree on conflict presentation. Mismatched styles do not break merges, but they change what reviewers see when they open a conflicted file. + +CI and bots that parse conflict markers should accept both two-section and three-section layouts. Scripts that assume only `<<<<<<<`, `=======`, and `>>>>>>>` will miss the `|||||||` base section under `diff3` and `zdiff3`. + +Agent-driven parallel work raises conflict volume. Better markers do not replace isolation. Use separate [worktrees](./git-worktrees), rebase early, and keep shared contracts owned by one branch. See [How to Fix Merge Conflicts Created by Coding Agents](/learn/how-to/merge-conflicts-with-coding-agents). + +## Next Steps + +- [Parallel Development Workflow](/learn/workflows/git/parallel-development): run concurrent branches without shared-checkout collisions +- [Auto-Rebasing AI Workspaces](/learn/how-to/auto-rebase-ai-branches): keep dependent agent branches current before conflicts pile up +- [Customizing Settings](/docs/how-to/customizing-settings): set conflict style and merge preferences in Treq +- [Merging Workspaces](/docs/tutorials/merging-workspaces): resolve conflicts before Treq opens the merge preview diff --git a/web/learn/how-to/auto-rebase-ai-branches.md b/web/learn/how-to/auto-rebase-ai-branches.md index 3aa578ff..08ae6c81 100644 --- a/web/learn/how-to/auto-rebase-ai-branches.md +++ b/web/learn/how-to/auto-rebase-ai-branches.md @@ -90,7 +90,7 @@ Pending working-copy edits can block or complicate synchronization. Commit, move ## Common failure cases -**Rebase succeeds, behavior breaks.** A conflict marker resolution kept the wrong side. Re-read conflicted files and add a regression test. +**Rebase succeeds, behavior breaks.** A conflict marker resolution kept the wrong side. Re-read conflicted files and add a regression test. [zdiff3](/learn/concepts/git/zdiff3) makes those markers easier to read when both sides share surrounding lines. **Force push without lease.** Concurrent updates on the remote branch can be overwritten, so always push with `--force-with-lease`. diff --git a/web/learn/how-to/merge-conflicts-with-coding-agents.md b/web/learn/how-to/merge-conflicts-with-coding-agents.md index 3ce74754..43d0ca3c 100644 --- a/web/learn/how-to/merge-conflicts-with-coding-agents.md +++ b/web/learn/how-to/merge-conflicts-with-coding-agents.md @@ -52,7 +52,7 @@ git rebase auth/schema # resolve, test, push ``` -During conflict resolution: +During conflict resolution, open the conflicted files and edit them. Git's [zdiff3](/learn/concepts/git/zdiff3) conflict style shows the merge base and shrinks shared edges out of the markers: ```bash git status @@ -107,6 +107,7 @@ When a bookmark conflict appears after remote updates, resolve it from the botto ## Related +- [What is zdiff3?](/learn/concepts/git/zdiff3) - [Auto-Rebasing AI Workspaces](/learn/how-to/auto-rebase-ai-branches) - [Parallel Coding Agents Without Branch Chaos](/learn/parallel-coding-agents) - [Merge vs Rebase](/learn/concepts/git/merge-vs-rebase)