libra blame

Trace each line of a file to the commit that last introduced it.

Synopsis

libra blame <file> [<commit>] [-L <range>]

Description

libra blame annotates each line of a file with the commit hash, author name, date, and line number of the commit that last modified that line. It walks the commit history from the specified revision (defaulting to HEAD) backward through parent commits, using diff operations to attribute lines to the earliest commit that introduced them.

The output format matches Git's blame format for familiarity: a short hash, author name (truncated to 15 characters), date, line number, and line content on each line.

For large files, the -L option restricts output to a specific line range, reducing both computation time and output volume.

Options

Line Range Formats (-L)

Each endpoint of -L may be a line number or a /regex/; a single endpoint spans to the end of the file (matching Git):

Line numbers are 1-based. Out-of-range values, and a /regex/ that matches no line, produce an error.

# Blame from line 42 to the end of the file
libra blame -L 42 src/main.rs

# Blame a range
libra blame -L 10,20 src/main.rs

# Blame from a regex match to a regex match
libra blame -L '/fn main/,/^}/' src/main.rs

# Blame 5 lines starting at line 100
libra blame -L 100,+5 src/main.rs

Common Commands

# Blame a file at HEAD
libra blame src/main.rs

# Blame at a specific commit
libra blame src/main.rs abc1234

# Blame lines 10-20
libra blame -L 10,20 src/main.rs

# Blame 5 lines from line 10
libra blame -L 10,+5 src/main.rs

# Ignore whitespace-only changes when attributing lines
libra blame -w src/main.rs

# JSON output for agents
libra --json blame src/main.rs

Human Output

abc12345 (Author Name     2026-03-30 10:00:00 +0800 1) line content
def67890 (Other Author    2026-03-28 14:30:00 +0800 2) another line
abc12345 (Author Name     2026-03-30 10:00:00 +0800 3) third line

Each line shows:

• Short hash (8 characters): the commit that last changed this line.
• Author name (padded to 15 characters, truncated with ... if longer).
• Date: formatted in the local timezone as YYYY-MM-DD HH:MM:SS +ZZZZ.
• Line number: 1-based line number in the file.
• Content: the actual line content.

--quiet validates the revision, file, and line range but suppresses all output. This is useful for scripted checks ("does this file exist at this revision?").

Output is automatically paged when connected to a terminal.

Structured Output (JSON)

{
  "ok": true,
  "command": "blame",
  "data": {
    "file": "tracked.txt",
    "revision": "abc123...",
    "lines": [
      {
        "line_number": 1,
        "short_hash": "abc12345",
        "hash": "abc123...",
        "author": "Test User",
        "date": "2026-03-30T10:00:00+00:00",
        "content": "tracked"
      }
    ]
  }
}

The revision field contains the full commit hash that was used as the blame starting point. Each line entry includes both the short_hash (8 characters) and full hash for programmatic use.

When the file is empty, the lines array is empty and human output shows "File is empty".

Design Rationale

Why no --reverse?

Git's blame --reverse shows the last revision in which a line existed, walking forward in history instead of backward. This is useful for finding when a line was removed, but it requires forward-history traversal which is computationally expensive and architecturally different from normal blame. Libra omits this to keep the blame implementation simple and fast. To find when a line was removed, use libra log -p -- <file> and search for the deletion.

Line range formats

Libra's -L supports numeric ranges (N, N,M, N,+C) and /regex/ endpoints (/regex/, /start/,/end/, and regex mixed with line numbers), matching Git; a single endpoint spans to the end of the file. Git's -L :<funcname> function-name selection is not yet supported, as it depends on language-specific configuration (the .gitattributes diff driver).

Why default to HEAD instead of working tree?

Git's blame defaults to HEAD and requires git blame --contents <file> to blame the working-tree version. Libra follows the same convention: blame always operates on committed content. This ensures reproducible results -- the same command with the same commit always produces the same output, regardless of working-tree state.

Why positional commit argument instead of a flag?

The commit argument is positional (second argument after the file path) rather than a flag like --commit or --rev. This matches Git's syntax for familiarity and keeps the common case (libra blame file.rs) concise. Since the file path is always the first positional argument, there is no ambiguity.

Parameter Comparison: Libra vs Git vs jj

Error Handling