Diff and Merge Tools

Using as a Git difftool / mergetool

GitComet can be used as a standalone diff and merge tool invoked by git difftool and git mergetool.

It supports both headless mode for algorithm-only workflows and GUI mode for an interactive GPUI window.

Setup / uninstall

The recommended way to integrate GitComet with Git is to let GitComet configure the tool entries for you.

# Configure Git globally to use GitComet for both difftool and mergetool
gitcomet setup

# Remove GitComet integration safely
gitcomet uninstall

Use --local to target only the current repository instead of global Git config.

Use --dry-run to print the commands before applying changes.

setup registers both headless and GUI variants with guiDefault=auto, so Git chooses GUI when a display is available and falls back to headless otherwise.

setup and uninstall are designed to be idempotent.

Difftool mode

Use difftool mode when GitComet should compare two file versions.

gitcomet difftool --local <path> --remote <path> [--path <display_name>] [--label-left <label>] [--label-right <label>]

When Git invokes GitComet as a difftool, GitComet can also read LOCAL and REMOTE from the environment as a fallback.

Mergetool mode

Use mergetool mode when GitComet should help resolve a merge conflict into the merged output file.

gitcomet mergetool --local <path> --remote <path> --merged <path> [--base <path>] [--label-local <label>] [--label-remote <label>] [--label-base <label>]

GitComet also reads LOCAL, REMOTE, MERGED, and BASE from the environment when invoked by Git.

--base is optional for add/add conflicts.

Add --gui to open the interactive merge window instead of resolving on the command line.

Merge options

Automatic resolution

gitcomet mergetool --auto attempts to resolve every conflict without opening a window. After the initial three-way merge it runs a set of heuristic passes:

• identical-side detection — both sides made the same change, so either is correct
• single-side-change detection — one side still matches the base and the other moved
• whitespace-only normalization — the sides differ only in whitespace
• subchunk splitting — a large conflicted block is split into line-level chunks, which often merge cleanly on their own

If every conflict is resolved, GitComet writes clean output and exits 0. If any conflict remains, it writes conflict markers and exits 1, which is the convention git mergetool already expects. That makes the flag usable from scripts and CI, where the exit status is the whole answer.

Pair it with --conflict-style diff3 or zdiff3. The heuristics compare each side against the common ancestor, so without base content in the file there is much less for them to work with.

--auto-merge is accepted as a Meld-compatible alias.

Automatic resolution is deliberately conservative: it only fires where the outcome is unambiguous, and anything it is not confident about is left conflicted for you to decide. The interactive window applies the same high-confidence rules when a file opens, but leaves whitespace-only resolution behind an explicit Auto-solve action, since whitespace-insensitive comparison can hide a real change in an indentation-sensitive language.

Compatibility

GitComet supports KDiff3- and Meld-style invocation forms, including:

• --L1, --L2, and --L3
• -o, --output, and --out
• --base
• positional arguments

That makes GitComet suitable as a drop-in replacement in existing difftool and mergetool setups.

See also

• The GitComet merge tool — how assisted conflict resolution works, and what the three-way view offers.
• GitComet vs KDiff3 — the argument-level compatibility, and what carries over.