MergeScope

Visual Git merge conflict resolution — against the common ancestor.

MergeScope is a standalone Windows desktop app (Tauri 2 + React + Monaco) that shows what each side changed relative to the BASE, instead of only comparing the two final files:

• Current vs Base (left panel)
• Base vs Incoming (right panel)
• Editable merged result (bottom panel)

It plugs into the standard git mergetool protocol, so it works from the Git CLI, worktrees, Fork, GitKraken, VS Code terminals and any client that supports external merge tools.

Full technical specification: MergeScope_Especificacao_Tecnica.md

Highlights

• Two independent diffs anchored on the common ancestor, kept vertically in sync: hatched filler blocks (TortoiseGit-style) pad each panel where the other side inserted lines, so equal base content sits at equal heights, and scrolling mirrors between panels.
• Each panel is titled with the detected branch name of its side (ours / theirs for merge, rebase and cherry-pick) instead of HEAD/CURRENT.
• Conflict graph with classification per group: current-only, incoming-only, independent, same-change, overlapping, delete-modify.
• Safe changes (single-sided, identical, independent) are auto-applied and flagged for review; real conflicts stay as marker blocks — nothing is picked silently.
• Resolution actions: Accept Current / Incoming / Both (either order) / Base / Reject — plus All from Current / All from Incoming to take every change in the file from one side — and free manual editing of the result with undo/redo, search and syntax highlighting.
• Click any change in the diff panels (or a region in the result) to focus that conflict; the resolution actions then target it.
• Conflict list sidebar, keyboard navigation, Command Palette (Ctrl+Shift+P), and a Settings panel (Ctrl+,).
• Fully customizable: interface language (English / Português-BR), UI and editor fonts and sizes, remappable keyboard shortcuts, and themes — dark/light/system/high-contrast plus a custom theme with per-token color editing (diff colors, text, accents, and more).
• Encoding and EOL fidelity: UTF-8 (with/without BOM), CRLF/LF and trailing newline are preserved on save; mixed EOL is flagged.
• Atomic writes (temp file + rename on the same volume), external-change detection (hash) before saving, optional backup.
• Exit codes follow the mergetool contract: 0 saved, 1 canceled/unresolved, 2 invalid args, 3 read failure, 4 write failure.
• 100% local processing: no network, no telemetry (see docs/decisions).

Repository layout

apps/desktop           # Tauri app (React frontend + src-tauri Rust backend)
packages/merge-engine  # TypeScript merge analysis engine (diff, graph, resolutions)
fixtures/              # Spec §28.4 test fixtures (one directory per scenario)
docs/                  # Architecture, integrations, ADRs
scripts/               # Icon generation, git mergetool setup

Building

Prerequisites: Node.js ≥ 20, Rust (MSVC toolchain), VS 2022 Build Tools (C++).

npm install
npm test                                # engine + UI store tests (vitest)
cargo test                              # run inside apps/desktop/src-tauri
npm run tauri build --workspace @mergescope/desktop   # release exe + NSIS installer

Artifacts:

• apps/desktop/src-tauri/target/release/mergescope.exe
• apps/desktop/src-tauri/target/release/bundle/nsis/MergeScope_1.0.1_x64-setup.exe

For UI development without Rust: npm run dev opens a browser demo session with representative conflict data.

Using with Git

Quick setup (after installing/building):

scripts\setup-git-mergetool.ps1 -ExePath "C:\Program Files\MergeScope\MergeScope.exe"

Or manually:

git config --global merge.tool mergescope
git config --global mergetool.mergescope.cmd '"C:/Program Files/MergeScope/MergeScope.exe" --base "$BASE" --current "$LOCAL" --incoming "$REMOTE" --result "$MERGED" --wait'
git config --global mergetool.mergescope.trustExitCode true
git config --global mergetool.prompt false

Then, whenever a merge/rebase/cherry-pick conflicts:

git mergetool

Diagnostics: mergescope doctor. CLI reference: mergescope --help.

Client-specific guides: Git · Fork · GitKraken

Fork (Windows)

1. Open File → Preferences → Integration (Git section).
2. Set Merge tool to Custom.
3. Fill in the fields below (adjust the path if MergeScope was installed for a different Windows user):

Executable:
C:\Users\<your-user>\AppData\Local\MergeScope\mergescope.exe

Arguments:
--base "$BASE" --current "$LOCAL" --incoming "$REMOTE" --result "$MERGED" --wait

If you are using a local release build instead of the installer, use apps\desktop\src-tauri\target\release\mergescope.exe as the executable.

When Fork reports a conflict, right-click the conflicted file and choose Open in External Merge Tool (the exact label can vary by Fork version). Resolve it in MergeScope, select Save & Close, then return to Fork and stage/mark the file as resolved.

GitKraken (Windows)

GitKraken does not let you point at an arbitrary merge-tool executable directly, but it can delegate to Git's configured merge tool. So the setup is two steps: register MergeScope in Git, then tell GitKraken to use Git's configuration.

1. Register MergeScope as Git's global merge tool. Run the helper script:

scripts\setup-git-mergetool.ps1 -ExePath "$env:LOCALAPPDATA\MergeScope\mergescope.exe"

or apply the same three settings by hand (adjust the path to your install):

git config --global merge.tool mergescope
git config --global mergetool.mergescope.cmd '"C:/Users/<your-user>/AppData/Local/MergeScope/mergescope.exe" --base "$BASE" --current "$LOCAL" --incoming "$REMOTE" --result "$MERGED"'
git config --global mergetool.mergescope.trustExitCode true

Git maps its own variables onto MergeScope's arguments: $LOCAL → --current (ours), $REMOTE → --incoming (theirs), $BASE → --base (common ancestor), $MERGED → --result (the working file written back). trustExitCode = true lets Git trust MergeScope's exit code (0 resolved, 1 canceled) instead of asking in the terminal.

2. Point GitKraken at that configuration. Open Preferences → External Tools, and under Merge Tool set External Merge Tool to Git Config Default.

3. Resolve conflicts. When GitKraken shows a conflicted file, click Open in external merge tool. Resolve it in MergeScope, choose Save & Close, and GitKraken picks up the resolved file automatically.

Diff tool: you can leave External Diff Tool on <Use Merge Tool>, but MergeScope is a 3-way merge tool and is not suited as a plain 2-file diff tool — Git provides no output file for diffs, and MergeScope requires --result. Leave GitKraken's built-in diff for regular diffs.

Fallback (older GitKraken versions without the External Tools screen): open GitKraken's built-in terminal and run git mergetool (or git mergetool path/to/file for a single file).

Keyboard shortcuts

Action	Shortcut
Save	Ctrl+S
Cancel/close	Esc
Next conflict	Alt+Down
Previous conflict	Alt+Up
Accept Current	Alt+1
Accept Incoming	Alt+2
Accept Both	Alt+3
Command Palette	Ctrl+Shift+P
Settings	Ctrl+,
Find (focused pane)	Ctrl+F

All shortcuts (except Find, handled by the editor) are remappable in Settings → Shortcuts.

Customization

Open the Settings panel from the ⚙ button in the top bar, the Ctrl+, shortcut, or the Command Palette. Everything persists to %APPDATA%/MergeScope/settings.json:

• Appearance — pick a theme, or choose Custom to edit every color token (background, text, accent, diff added/removed, conflict, …) live.
• Font — set the interface and editor font family and size independently.
• Language — switch between English and Português (Brasil).
• Shortcuts — click a command's shortcut to record a new key chord; Backspace clears it and ↺ restores the default.

Status

MVP (spec phases 0–2): functional and verified end-to-end on Windows — git mergetool launch, real conflict resolution, atomic save with CRLF/BOM fidelity, exit codes, NSIS installer. See docs/decisions/adr.md for scope decisions and docs/architecture/overview.md for the module map. Roadmap phases 3–4 (repository launcher, move detection, macOS/Linux, semantic plugins) are not implemented yet.

Contributing

Contributions are welcome — see CONTRIBUTING.md for setup, conventions, and how to add translations, themes, and shortcuts.

License

MIT — see LICENSE.