libra mergetool
Command reference for `libra mergetool`
Run an external merge resolver for each ordinary content conflict in the current
worktree. The command stages a successful result but does not create the final
merge commit; finish with libra merge --continue.
Synopsis
libra mergetool [--tool <tool>]
libra mergetool --tool-help
How resolution works
For each regular-file conflict, Libra creates an owner-only temporary directory
with BASE (stage 1), LOCAL (stage 2), REMOTE (stage 3), and an editable
MERGED copy of the conflicted worktree file. A resolved MERGED file replaces
the worktree file and its stage 1/2/3 index entries become one stage-0 entry.
By default a MERGED modification-time change proves resolution. An unchanged
file is confirmed only on an interactive terminal; EOF and non-interactive use
remain unresolved. Set mergetool.<tool>.trustExitCode=true only when a tool's
exit status reliably reports resolution; then exit status is the sole signal.
Symlink, mode, and modify/delete conflicts are diagnosed for manual resolution;
they are never silently skipped or passed to a tool. Libra also refuses a
conflicted worktree path when it, or any parent component, is a symbolic link:
it never follows one while reading the initial MERGED copy, creating a
backup, or writing the resolution.
Tool selection and configuration
--tool <tool> overrides merge.tool; otherwise Libra uses merge.tool, then
defaults to vimdiff. Built-ins are vimdiff, nvimdiff, meld, vscode,
and opendiff. Their executable is found on PATH, unless
mergetool.<tool>.path supplies one.
Custom tools use mergetool.<tool>.cmd. Libra deliberately evaluates that
trusted local configuration with sh -c, matching Git, and supplies BASE,
LOCAL, REMOTE, and MERGED only as environment variables. Do not copy a
command from an untrusted repository or issue tracker.
libra config set merge.tool review
libra config set mergetool.review.cmd 'review-tool "$LOCAL" "$REMOTE" "$MERGED"'
libra config set mergetool.review.trustExitCode true
mergetool.keepBackup defaults to true, preserving the old conflict-marker
file as <path>.orig after a successful resolution. The currently supported
mergetool.* keys are keepBackup and per-tool .cmd, .path, and
.trustExitCode; another key fails closed instead of being ignored.
Exit codes
| Code | Meaning |
|---|---|
0 |
Every selected conflict was resolved and staged, or --tool-help was displayed. |
| non-zero | There is no unresolved path, a tool is unavailable/unknown, output is unresolved, or the conflict requires manual handling. |
Examples
# List built-in resolvers and their PATH availability.
libra mergetool --tool-help
# Resolve ordinary conflicts using the configured default.
libra mergetool
# Override the default for this run.
libra mergetool --tool vimdiff
# Finish after every conflict has been resolved and staged.
libra merge --continue