3-way merge

The workflow at a glance

1. Open the merge from TortoiseGit (Edit conflicts), from git mergetool, from the home screen, or with /base: /mine: /theirs: /merged: on the command line.
2. DiffScope merges every non-overlapping change and selects the first conflict.
3. For each conflict, pick Mine, Theirs, a combination or Base. Press F7 to move to the next one.
4. Edit the output by hand if neither side is quite right.
5. Save with Ctrl+S and close the window. The exit code tells the calling tool whether the merge is resolved.

The four panes

Mine

Your version (git's LOCAL, TortoiseGit's %mine). Read-only.

Base

The common ancestor both versions started from. Read-only.

Theirs

The incoming version (git's REMOTE, TortoiseGit's %theirs). Read-only.

Output

The merge result, and the only pane you can edit. Its header shows the file it will be saved to, the encoding and line endings it will be written with, and how many conflicts are still unresolved.

All four panes scroll together. Drag the bar between the top row and the output to give either more room. The overview strip on the right marks every change and conflict; click it to jump.

Colours show where each change came from: changes made only in mine, only in theirs, or the same change made on both sides. Conflicts are marked in red until you resolve them. In a resolved conflict, the side you took is highlighted and the side you dropped is dimmed.

Auto-merge

When the merge opens, DiffScope has already applied every change that does not overlap with a change on the other side, and every change both sides made the same way. The status bar shows how many, for example 4 changes merged automatically. If nothing conflicts, a message says so and you only need to review and save.

The /automerge switch that some tools pass is accepted, but it changes nothing: DiffScope always merges non-conflicting changes.

The whitespace and case options (-w, -b, -i) also apply to merges, so changes that differ only in whitespace or case can be merged without a conflict. See the command-line reference.

Resolving conflicts

An unresolved conflict shows a placeholder line in the output: ⚠ unresolved conflict — choose Mine, Theirs, Base or a combination. A bar above it holds the choices for that conflict. You can resolve the current conflict in several ways:

• Use the toolbar buttons, the keys above, or the buttons in the conflict's bar in the output pane.
• Double-click a conflict in the Mine or Theirs pane to take that side.
• Shift+click a toolbar button (Mine, Theirs, Mine + Theirs, Theirs + Mine or Base) to apply it to every remaining unresolved conflict.
• You can change your mind: pick another choice for a resolved conflict, or unresolve it.

F7 / Alt+↓ moves to the next conflict and Shift+F7 / Alt+↑ to the previous one. Unresolved conflicts come first; when none are left, the keys step through the resolved ones. The toolbar counter shows how many are left, for example 2 of 5 conflicts left.

Editing the output

Double-click any output line to edit it, with the same keys as the text compare editor: Enter splits a line, Backspace and Delete join lines, Esc closes the editor. A conflict has to be resolved before you can edit its lines; pick the closest choice first, then adjust it. Edited conflicts are labelled (edited).

Ctrl+Z and Ctrl+Y undo and redo both resolutions and edits.

Saving the result

Ctrl+S writes the output to the merged file. If the merge was started without an output file, DiffScope asks where to save it.

• Encoding and BOM are taken from mine.
• Line endings follow the main line ending of mine (then theirs, then base). Whether the file ends with a newline also follows mine.

Saving with unresolved conflicts

If conflicts are left, DiffScope warns you and offers Save with Markers. Each unresolved conflict is then written with git-style conflict markers, and the merge counts as unresolved when you close the window:

<<<<<<< mine
your lines
=======
their lines
>>>>>>> theirs

The labels after the markers are the titles of the panes (for example the names TortoiseGit passes), or mine and theirs when there are none.

diff3 style

Start the merge with --diff3 to include the base version in each conflict, as git merge-file --diff3 does:

<<<<<<< mine
your lines
||||||| base
the original lines
=======
their lines
>>>>>>> theirs

Closing and exit codes

A merge window sets the process exit code when it closes. Tools such as git mergetool use it to decide whether the file is resolved:

If you close a merge that is not saved, or still has conflicts, DiffScope asks: Save and Close, Close without Saving or Cancel. If you already saved a clean result and then made more edits, closing without saving keeps the clean file on disk, and the exit code is still 0.

How TortoiseGit and git use it

• git mergetool with trustExitCode = true marks the file resolved on exit code 0. On 1 it reports merge of <file> failed and leaves the file conflicted. Without trustExitCode, git only checks whether the file changed, which is also true when conflict markers were saved. Always set it; see git setup.
• TortoiseGit waits for DiffScope to close. After you have saved a clean result, mark the file resolved in TortoiseGit (right-click › TortoiseGit › Resolve…).

Merging without a window is covered in headless mode: it writes the result with markers and returns 0 for a clean merge, 1 when conflicts are left, and 2 on errors.

Limits

• All three inputs must be text files. Binary files and folders cannot be merged.
• The output folder must already exist.