gritHEAD → docs/revs
Commands / HistoryMarkdown

grit revs

List or count commits matching revision ranges.

grit revs <RANGE>... [-n <N>] [--count] [--left-right] [--cherry-mark]
[--skip <N>] [--since|--after <date>] [--until|--before <date>]
[--first-parent] [--follow] [--merges | --no-merges] [--reverse]
[--author <pat>] [--committer <pat>] [--grep <pat>]
[-S <string>] [-G <pat>] [--pickaxe-regex]
[-i] [--all-match] [--invert-grep] [-F] [--no-mailmap]
[--all] [--branches[=<glob>]] [--tags[=<glob>]] [--remotes[=<glob>]]
[--pathspec-from-file <file|->] [--pathspec-file-nul]
[-- <PATH>...]

Description

Walks commits reachable from one or more revision ranges and prints each commit’s full object id and subject (first line of the message), one commit per line. Ranges use the same syntax as Git’s rev-list: plain tips, A..B, symmetric difference A...B, and ^tip exclusions.

With no revision arguments, --branches, --tags, and --remotes (and optional globs) select only those ref tips—they replace the implicit HEAD default, they do not union with it, and if nothing matches the count is 0 with exit 0 (like git rev-list).

Use --count to print only the number of reachable commits (no subject lines). With --left-right and exactly one A...B range, --count prints left and right counts (same as git rev-list --left-right --count). Without --count, --left-right lists the range with a < (left) or > (right) prefix on each commit.

Reviewing a rewritten branch

--cherry-mark compares the two sides of one A...B range by patch-ID, the way git rev-list --left-right --cherry-mark does. Run it on the version you reviewed and the version that was force-pushed (old...new) to see which commits are the same change and which are new:

  • = marks a commit whose patch-ID also appears on the other side. When exactly one commit on each side has that patch-ID, the line names its counterpart and says whether the commit message changed, so a reworded commit stands out from an untouched one.
  • < and > mark commits found only on the left or right side: dropped, added, or edited commits, and commits that came in with the new base.

When several commits on one side share a patch-ID, they are all marked equivalent without being paired. Matching uses the stable patch-ID (path-limited when paths follow --). Only the diff counts: a commit whose content changed is a new commit on its side, and no content interdiff is shown. --cherry-mark and --left-right need exactly one A...B range and exit 1 otherwise, even with -n 0; --cherry-mark cannot be combined with --count. When a commit-graph file is present, the walk takes parents and commit dates from it instead of reading commit objects. Unfiltered counts use that graph linkage, and listings read each listed commit once to render its row.

A..B and A...B counts walk the range once: the excluded side is marked down to where it meets the included side, and the walk stops there instead of building ancestor sets for the shared history. --since, --until, --merges, --no-merges and --first-parent only decide which of those commits are counted, so counting a range costs about the same as listing it. With a commit-graph, generation numbers let the walk stop as soon as the included side is resolved, so a small range stays bounded even in a repository with a deep history. As in Git, --first-parent follows first parents from the included tips only; everything an excluded tip reaches through any parent stays excluded.

Path arguments after -- limit history to commits that touched those paths. Operands use Git pathspec cwd rules (same as grit diff): from a subdirectory, . limits to that directory, and bare filenames are relative to the current directory, not the repository root. Attribute pathspecs such as :(attr:myattr) use the repository's current .gitattributes stack (work tree, index, info/attributes, and macros), the same way as grit diff; they do not read historical trees' attribute files.

Author, committer, message, and pickaxe filters use the same rules as grit log (-S, -G, --pickaxe-regex, and the same -i / -F / mailmap behavior). Invalid patterns exit 129 with kind: "invalid_pattern" in --json output.

Options

Option Description
<RANGE>… One or more revision ranges (required unless a ref-set flag such as --all is used).
-n, --limit <N> Stop after N commits (listing mode only). --max-count is Git’s well-known alias.
--count Print only the commit count (or left/right counts with --left-right).
--left-right With one A...B range, mark each listed commit as left (<) or right (>); with --count, print {left, right} instead of a single total.
--cherry-mark With one A...B range, pair the two sides by patch-ID: = marks equivalent commits, < / > the rest (implies --left-right; conflicts with --count).
--skip <N> Skip N commits after ordering.
--since, --after <date> Exclude commits older than this date (committer date).
--until, --before <date> Exclude commits newer than this date.
--first-parent Follow first parents only at merges.
--follow With exactly one literal file path after --, walk history across renames (Git log --follow). Still walks when the path no longer exists at the start commit.
--merges Only merge commits (conflicts with --no-merges).
--no-merges Exclude merge commits (conflicts with --merges).
--reverse Print the selected window oldest-first. -n and --skip choose the window (newest N commits after skip); --reverse only flips that window.
--all Include every ref tip.
--branches[=<glob>] Branch tips, optionally filtered by glob.
--tags[=<glob>] Tag tips, optionally filtered by glob.
--remotes[=<glob>] Remote-tracking tips, optionally filtered by glob.
--author <pat> Only commits whose author matches (repeatable; OR).
--committer <pat> Only commits whose committer matches (repeatable; OR).
--grep <pat> Only commits whose message matches (repeatable; OR unless --all-match).
-i, --regexp-ignore-case Case-insensitive patterns.
--all-match Every --grep pattern must match.
--invert-grep Exclude commits that match the grep group.
-F, --fixed-strings Literal string patterns.
--no-mailmap Do not apply .mailmap for author/committer matching.
--pathspec-from-file <file|-> Read pathspecs from a file (- for stdin), in addition to argv paths after --.
--pathspec-file-nul --pathspec-from-file entries are NUL-separated.
-- <PATH>… Limit to commits touching these paths (cwd-relative under the work tree, like grit diff).

JSON output

Schema: v1

Pass --json for stable, scripting-friendly output:

Field Type Meaning
commits array Commits in walk order. Each entry uses the shared CommitJson shape, plus the side fields below with --left-right or --cherry-mark. Empty when --count is set.
commits[].side string or omitted left or right: which side of the A...B range the commit is on. Only with --left-right or --cherry-mark.
commits[].equivalent boolean or omitted With --cherry-mark: true when a commit on the other side has the same patch-ID.
commits[].equivalent_to string or omitted With --cherry-mark, when exactly one commit on each side shares the patch-ID: the other side's commit.
commits[].message_changed boolean or omitted Present with equivalent_to: true when the two commit messages differ.
count number or null Total reachable commits when --count is set without --left-right; otherwise null.
left_right object or omitted When --count and --left-right are set: left and right commit counts for the symmetric range.
truncated boolean true when more commits matched than returned (-n).
next null Reserved for future paging; always null today.

Markdown output

Schema: v1

Pass --markdown for a heading and bullet list of oid/subject pairs, or a bold count when --count is used.

Exit status

Code Meaning
0 Success (success).
1 Command failed (failure).
2 Invalid flags or arguments (usage).

See Exit codes for shared rules and structured --json kind values.