CommitLore query

context, limits, ruled-out, and warnings read the same underlying
record set for one or more paths; stale reads it repo-wide. All are
read-only — none of them touch git state.

Reading records for a path

commitlore context src/core/types.ts

context for src/core/types.ts as of 2026-07-26T07:28:42.051Z — 2 limits, 5 ruled-out, 3 warnings, 16 other in 2 records (index, 2 commit record(s) scanned)

limits
  r-c0f4e2  3d249cd3  npm gitlore is held by an active same-domain CLI, so the owner's first-choice name was not available
  r-b2e7f1  00d348d1  Parsing must delegate to git interpret-trailers -- reimplementing the block rules would drift from the rest of the git ecosystem

ruled-out
  r-c0f4e2  3d249cd3  GitLore published as git-lore | the binary and search results still collide with the existing gitlore tool
  r-b2e7f1  00d348d1  line-matching Key: prefixes | prose containing a colon line parses as a record and feeds agents false context (verified B3)
  ...

warnings
  r-c0f4e2  3d249cd3  [directive]  ADR-0008 and ADR-0009 keep the literal string Annals on purpose -- mechanical substitution there destroys the decision trail
  ...

other
  r-c0f4e2  3d249cd3  Blast: system
  ...

context is every active record touching the path, grouped by section, each
line prefixed with its Record-Id and short commit sha. limits,
ruled-out, and warnings return the same underlying records filtered to
one key each — reach for those when only one kind of information matters:

commitlore limits src/core/types.ts

2 limits for src/core/types.ts as of 2026-07-26T07:28:42.946Z (index, 2 commit record(s) scanned)

  r-c0f4e2  3d249cd3  npm gitlore is held by an active same-domain CLI, so the owner's first-choice name was not available
  r-b2e7f1  00d348d1  Parsing must delegate to git interpret-trailers -- reimplementing the block rules would drift from the rest of the git ecosystem

Those four take zero or more paths (commitlore context a.ts b.ts answers for
both). Several paths work, but Git follows renames only for a single path.
When several paths are supplied, the CLI answers each literal path and
prints a diagnostic that renames were not followed; query one path at a time
when historical names matter.
They share these flags:

• --json — the full structured answer instead of the printed summary: each
  record's recordId, sha, committedAt, lifecycle, trust grade
  (directive when the author is trusted and the record is authored, a
  claim otherwise — see SPEC §7), every path the commit touched, and its full
  trailers array.
• --all-history — include superseded and expired records too, each labelled
  as such. Without it, only records currently active are returned.
• --no-index — answer from git directly instead of the local
  .git/commitlore/index.db cache (see commitlore-setup). Slower, but
  correct even if the index is stale or missing.
• --at <ISO 8601 instant> — evaluate as of a past instant instead of now,
  for asking "what was known at commit X".
• --limit <n> — cap the number of records returned.

Records that have gone stale

commitlore stale

stale at 2026-07-26T07:28:43.176Z — 0 superseded, 0 expired, 0 for review, of 20 record(s) in 30 commit(s)

Repo-wide, no path argument: lists records that are superseded (by a later
Supersedes:), expired (past their Expires: date, or matching a
free-text Expires: condition flagged for review), or a Certainty: guess
record surfaced for re-examination. Scans the most recent 1000 commits by
default; --all-history scans everything. Takes --json and --at the same
as the commands above.

Why not git log --grep

git log --grep 'Warn:' looks tempting — it's already installed, no new tool
needed. It also produces false positives that CommitLore's real parser does
not, because git trailer parsing is not line-matching.

Per SPEC §2.1 (verified against git interpret-trailers --parse): a trailer
block only exists if it is the message's last paragraph, and every
line in that paragraph is a Key: value line or a continuation of one. A
paragraph that mixes a colon-shaped line with a line of ordinary prose is
prose from end to end — none of it is a trailer, including the line that
looks like one. grep cannot see that distinction; it matches the substring
wherever it sits.

Concretely, this message has a colon-prefixed line but is not a CommitLore
record — the paragraph's second line is plain prose, so the whole paragraph
fails the trailer-block test:

Simplify retry loop timing

Refactored the shared retry helper for clarity and consolidated the
backoff calculation into one place.

Note: this touches the shared client wrapper, so double check
downstream callers before merging the release.

git log --grep 'Note:' (or any grep for ^[A-Za-z-]*:) matches that
Note: line and would report this commit as carrying a record. Running the
actual message through commitlore parse returns zero trailers:

commitlore parse --message-file message.txt --json

{
  "trailers": []
}

context/limits/ruled-out/warnings/stale all read through the same
grammar parse and validate use — delegated to git interpret-trailers,
never a line-by-line grep — so they never surface a body sentence as if it
were a recorded constraint.