libra diff

Compare differences between HEAD, the index, the working tree, or two revisions.

Synopsis

libra diff [<pathspec>...]
libra diff <commit> [<commit>] [--] [<pathspec>...]
libra diff <commit>..<commit> | <commit>...<commit> [--] [<pathspec>...]
libra diff --staged [<commit>] [<pathspec>...]
libra diff --old <commit> --new <commit> [<pathspec>...]
libra diff [--name-only | --name-status | --numstat | --stat | --shortstat | --summary]
           [-s | --no-patch] [--exit-code] [--check] [-R] [-z]
libra diff [--algorithm <name>] [--output <file>]

Description

libra diff shows changes between different states of the repository. By default it compares the index against the working tree (unstaged changes). With --staged, it compares HEAD against the index (staged changes). With --old and --new, it compares two arbitrary commits.

The diff engine supports multiple algorithms (histogram by default, with myers and myersMinimal as alternatives). Output can be directed to a file with --output, and several summary formats are available (--name-only, --name-status, --numstat, --stat, --shortstat, --summary). A status-only check is possible with -s/--no-patch and --exit-code, and -z/--null makes the name/numstat outputs NUL-terminated for safe scripting. --word-diff[=<mode>] re-renders the patch at word granularity (matching Git's structure; like all Libra diffs, the exact word grouping can differ from Git on ambiguous changes, and hunk headers keep Libra's unified-diff format).

Pathspec arguments filter the diff to only show changes in matching files or directories.

Options

Option Details

--old / --new

Compare two specific commits. --new requires --old to also be specified:

# Compare two commits
libra diff --old HEAD~3 --new HEAD

# Compare a tag to HEAD
libra diff --old v1.0 --new HEAD

--staged

Show what has been staged for the next commit:

libra diff --staged
libra diff --staged src/

--algorithm

Select the diff algorithm. Histogram (the default) generally produces more readable diffs for code:

libra diff --algorithm myers
libra diff --algorithm myersMinimal

--output

Write diff output to a file. Useful for saving diffs for review:

libra diff --output changes.patch
libra diff --staged --output staged.diff

Summary formats:

# Just file names
libra diff --name-only

# File names with status letters
libra diff --name-status
# Output: M	src/main.rs
#         A	src/new_file.rs

# Machine-friendly counts
libra diff --numstat
# Output: 5	2	src/main.rs

# Visual bar graph
libra diff --stat
# Output:  src/main.rs | 7 +++++--

Common Commands

# Show unstaged changes
libra diff

# Show staged changes
libra diff --staged

# Compare two commits
libra diff --old HEAD~1 --new HEAD

# Show diff stats for a subdirectory
libra diff --stat src/

# Patch with a different amount of context (0, or more than the default 3)
libra diff -U0
libra diff --unified=5 src/main.rs

# Ignore whitespace-only changes (re-indentation shows nothing)
libra diff -w

# Ignore only changes in the amount of whitespace (a  b == a b)
libra diff -b

# Ignore changes that are only blank lines
libra diff --ignore-blank-lines

# Save diff to a file
libra diff --output my.patch

# JSON output for agents
libra --json diff --staged

Human Output

Supported output modes:

• Default unified diff (with ANSI color when terminal is detected)
• --name-only
• --name-status
• --numstat
• --stat
• --shortstat (just the trailing summary line of --stat, with zero-count clauses omitted)
• --summary (condensed create/delete/rename summary; renames appear with -M, mode-only changes are not surfaced)
• -s / --no-patch suppresses the patch body (for status-only checks)
• --exit-code still prints the diff but exits 1 when there are differences
• -z / --null NUL-terminates --name-only/--name-status/--numstat records (status and path become separate NUL fields under --name-status)
• --quiet suppresses stdout and uses exit 1 to signal that differences exist

--output <file> writes human-readable output to a file. In --quiet mode the file is still written, but differences still return exit 1. In --json mode this flag is ignored and output always goes to stdout.

Output is automatically paged when connected to a terminal.

Structured Output (JSON)

{
  "ok": true,
  "command": "diff",
  "data": {
    "old_ref": "index",
    "new_ref": "working tree",
    "files": [
      {
        "path": "tracked.txt",
        "status": "modified",
        "insertions": 1,
        "deletions": 0,
        "hunks": [
          {
            "old_start": 1,
            "old_lines": 1,
            "new_start": 1,
            "new_lines": 2,
            "lines": [" tracked", "+updated"]
          }
        ]
      }
    ],
    "total_insertions": 1,
    "total_deletions": 0,
    "files_changed": 1
  }
}

The status field is one of: added, deleted, modified, or renamed. A renamed entry (only produced under -M/--find-renames) additionally carries rename_from (the original path; path holds the new name) and similarity (the similarity index as a whole percent), e.g.:

{
  "path": "src/new.txt",
  "status": "renamed",
  "rename_from": "src/old.txt",
  "similarity": 90,
  "insertions": 1,
  "deletions": 1,
  "hunks": [ /* ... */ ]
}

A binary file (unless --text) carries binary as a [old_size, new_size] byte-count pair, its insertions/deletions are 0, and hunks is empty.

The old_ref and new_ref fields indicate what was compared (e.g., "index", "working tree", "HEAD", or a commit reference).

Design Rationale

Positional revisions and --old / --new

Git-style positional revisions are supported: libra diff A (A vs working tree), libra diff A B (identical to A..B), libra diff A...B (merge-base(A,B) vs B), and libra diff --staged A (A vs index). Disambiguation matches Git: everything after -- is always a path; a pre--- token that is both a revision and an existing file is an error (ambiguous argument '<tok>': both a revision and a filename), and one that is neither errors with unknown revision or path not in the working tree (glob pathspecs like *.c are exempt). These errors exit 129 with LBR-CLI-002/LBR-CLI-003 (Libra's CLI-error convention; Git exits 128 here). More than two revisions is rejected — Git ≥2.38's combined-diff form for merges is a declined surface.

The Libra-only named flags (--old, --new) remain the ambiguity-free programmatic form — when either is given, every positional is a pathspec and no revision interpretation happens at all. This is valuable for AI agents constructing commands: there is exactly one way to express each intent, with no name-collision hazard.

Why histogram as the default algorithm?

Git defaults to the Myers algorithm for historical reasons. The histogram algorithm (introduced in Git 2.0 as an option) generally produces more readable diffs for source code because it is better at identifying moved blocks and avoids pathological cases with repeated lines. Libra defaults to histogram for better out-of-the-box quality. Myers and myersMinimal remain available for compatibility and edge cases.

The --cached alias

--cached is accepted as a Git-compatible visible alias for --staged (the canonical Libra spelling, matching libra status and libra restore --staged).

Why --new requires --old?

Allowing --new without --old would create an ambiguous comparison (new compared to what?). Requiring --old when --new is specified makes the comparison explicit and predictable. For the common case of comparing against HEAD, use --staged instead.

--word-diff and --color-words

--word-diff[=<mode>] is supported (see the option above): it re-renders the patch at word granularity in plain (default), color, porcelain, or none mode, with whitespace-delimited words. The shorthand --color-words and a custom --word-diff-regex are not yet implemented.

Parameter Comparison: Libra vs Git vs jj

Error Handling