libra merge

Merge one target into the current branch.

Synopsis

libra merge [--ff-only | --no-ff | --squash | --no-commit] [-m <msg>] [--no-edit] [--stat | -n | --no-stat] [--verify-signatures | --no-verify-signatures] [--no-rerere-autoupdate] [--no-gpg-sign] [--dry-run] [--autostash | --no-autostash] <branch>
libra merge --continue
libra merge --abort
libra merge --restart

Description

libra merge <branch> resolves a local branch, commit hash, or remote-tracking ref such as refs/remotes/origin/main.

If the current branch can be fast-forwarded, Libra moves the branch pointer to the target commit and restores the index and working tree. If the branches have diverged, Libra performs a single-head three-way merge using the merge base.

Clean three-way merges create a two-parent merge commit, update HEAD, rebuild the index, restore the working tree, and write a merge reflog entry. Conflicting three-way merges write line-level conflict markers to the working tree (matching Git — only the diverging hunks are enclosed between <<<<<<< HEAD / ======= / >>>>>>>, with shared context left outside; binary or modify/delete paths fall back to whole-file markers), write unmerged index stages, save Libra merge state, and return LBR-CONFLICT-002 with hints for libra merge --continue and libra merge --abort.

Conflict style (merge.conflictStyle)

The marker format follows the Git-compatible merge.conflictStyle config key (config-only — matching Git, merge has no CLI style flag):

libra config merge.conflictStyle diff3

• merge (default, or unset) — the two-marker style above.
• diff3 — additionally emits the common-ancestor content between a ||||||| base marker and the ======= separator, so you can see what both sides started from.
• Any other value — including the unimplemented zdiff3 — is a hard error when a conflict must be rendered (exit 128), never a silent fall-back to the default style.

The config is honored by both libra merge and libra cherry-pick for line-level text conflicts. Binary and modify/delete conflicts keep their two-part whole-file presentation (Git also emits no base block there), and libra rebase currently renders whole-file markers without a base block regardless of this setting.

Libra still does not implement octopus merges, custom strategies, strategy options, or interactive message editing (--edit/launching an editor). Signature verification (--verify-signatures) is supported but limited to the local vault PGP key (no external GPG keyring).

Options

Common Commands

libra merge feature-x
libra merge refs/remotes/origin/main
libra merge --continue
libra merge --abort
libra merge --dry-run feature-x
libra merge --restart
libra merge --json feature-x

Conflict Lifecycle

When a merge conflicts:

1. Edit files containing conflict markers.
2. Stage each resolved path with libra add <path>.
3. Run libra merge --continue to create the two-parent merge commit.

Run libra merge --abort before continuing to restore the branch, index, and working tree to the pre-merge commit. libra status shows the in-progress merge target and the continue/abort commands while merge state exists.

To throw away a botched resolution attempt and start over in one step, run libra merge --restart: it restores the pre-merge state exactly like --abort (any edits to conflicted files are discarded) and immediately re-runs the same merge against the recorded target commit — deterministic even if the branch has moved since — leaving fresh conflict markers and a fresh merge state. The re-run uses default merge options.

Dry Run

libra merge --dry-run <branch> (a Libra extension — Git has no true merge dry-run) reports what the merge would do without writing anything: no HEAD, index, working-tree, reflog, merge-state, or object-store mutation (auto-merged blobs are computed in memory only). Because it is read-only it also works on a dirty working tree — note the preview does not validate cleanliness, so a real merge may still refuse where the preview succeeded.

Outcomes and exit codes:

The would-conflict exit of 1 is an outcome signal (like merge-file and diff --exit-code), deliberately distinct from the 128 a real conflicting merge exits with — the preview itself succeeded. With --json/--machine the summary carries "dry_run": true and, when conflicting, "would_conflict": true plus conflicted_paths; both keys are absent from every real merge's output (frozen schema).

Human Output

Fast-forward:

Fast-forward

Clean three-way merge:

Merge made by the 'three-way' strategy.

Already up to date:

Already up to date.

After --continue:

Merge completed.

After --abort:

Merge aborted.

Conflict errors are printed through Libra's standard structured error envelope on stderr and include recovery hints.

JSON / Machine Output

Success output keeps the historical files_changed numeric field and adds merge-lifecycle fields only when relevant.

{
  "ok": true,
  "command": "merge",
  "data": {
    "strategy": "three-way",
    "old_commit": "abc1234...",
    "commit": "def5678...",
    "files_changed": 2,
    "up_to_date": false,
    "parents": ["abc1234...", "fedcba9..."]
  }
}

Already-up-to-date merges use strategy: "already-up-to-date", commit: null, files_changed: 0, and up_to_date: true.

--abort sets aborted: true; --continue sets continued: true. Conflict failures return an error envelope on stderr with LBR-CONFLICT-002.

Parameter Comparison: Libra vs Git vs jj

Error Handling