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 command-line workflows and GUI mode for an interactive window. You can also resolve conflicts directly inside the repository browser.

Interactive conflict resolution

1. Select a conflicted file in your repository, or launch git mergetool --gui after completing the setup below.
2. Review the aligned inputs and editable output. In a three-way view, Base is the common ancestor, Ours is the local input, and Theirs is the incoming input. During a rebase, check the pane labels carefully: Git's ours/theirs roles follow the rebase operation.
3. GitComet automatically resolves identical edits and other high-confidence cases when the file opens. The status summary reports total, auto-solved, and unsolved blocks.
4. Use Shift+F2 and Shift+F3 to visit unresolved conflicts. Pick an input, keep both, or edit the result. Both combines ours followed by theirs, so review the resulting order.
5. In the repository browser, choose Save & stage to write the resolved file and mark it resolved in Git. Save writes the result without staging. The standalone mergetool uses Save & close to write the merged output and finish.
6. Continue the interrupted merge, rebase, or cherry-pick after all conflicted files are resolved.

Save actions remain disabled while the output still has unresolved conflicts. The keyboard choices depend on the view:

U makes the active conflict unresolved again. When large moves need manual alignment, select the corresponding source lines and press Cmd+Y / Ctrl+Y. Clear manual alignments with Cmd+Shift+Y / Ctrl+Shift+Y. See Keyboard Shortcuts for navigation and focus rules.

Setup / uninstall

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

Use the installed gitcomet command, or the full path to your executable if you installed an AppImage, portable archive, or macOS disk image manually.

# 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.

uninstall removes the Git integration, not the application. Setup backs up shared Git settings when necessary; uninstall restores them only if they still have the value managed by setup, preserving settings you changed afterward.

After setup, run these commands inside a repository:

# Review unstaged changes in a window
git difftool --gui

# Review staged changes in a window
git difftool --gui --cached

# Resolve files left conflicted by a merge, rebase, or cherry-pick
git mergetool --gui

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.

Without --gui, direct difftool invocation prints a diff to standard output. To compare arbitrary files in a window:

gitcomet difftool --gui --local before.txt --remote after.txt

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

Explicit flags take precedence. When those flags are absent, GitComet reads merge.conflictstyle and diff.algorithm from Git configuration before falling back to the defaults above.

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.

The interactive window applies high-confidence rules when a file opens and leaves whitespace-only differences for you to decide. The command-line --auto mode also enables whitespace normalization, which can hide meaningful indentation changes. Review its output before committing, especially for indentation-sensitive languages.

Exit status

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.