gritHEAD → docs/reflog
Commands / HistoryMarkdown

grit reflog

Show, delete, or expire reflog entries.

grit reflog [REF] [-n N] [--since DATE] [--until DATE] [--grep PAT]
grit reflog list [-n N]
grit reflog delete <REF@{N}>...
grit reflog expire [--all] [--expire <DATE>] [--expire-unreachable <DATE>] [--dry-run]

Description

Inspect and maintain reference logs. With no subcommand, lists entries for REF (default HEAD) in newest-first order. Each line shows the selector (REF@{n}), the new_oid after the update, a relative date, and the log message.

Filters apply to the reflog entry identity timestamp (not the commit date). Scanning stops once -n matches are collected, so large logs are not fully materialized.

delete removes explicit entries without rewriting the branch tip. In ref@{n}, n is a nonnegative integer: 0 selects the newest entry, 1 the next older entry. Date selectors and bare indices are not accepted by delete. list prints every ref that currently has a reflog file (sorted), bounded by -n / --limit. expire applies Git-compatible gc.reflogExpire* rules (same layering as grit gc), using explicit --expire / --expire-unreachable values when given and merged config otherwise. An entry older than the unreachable cutoff is dropped when its old or new commit is not reachable from the ref's tip (from any ref for HEAD), with annotated tags peeled as current Git does; when the tip does not name a commit, every such entry is dropped. The check walks commits only: history down to the --expire cutoff first, and the rest once, only if an entry names an older commit. It never reads trees or fetches missing objects in a partial clone. Refs expired in one run share the commits already read, so expiring many branches with old entries costs little more than one. With --dry-run, expire reports per-ref prune counts without rewriting any log file.

A branch literally named list is ambiguous with the list subcommand; use the full ref (refs/heads/list) when showing that branch's entries.

Options

Option Description
REF Ref to list (default HEAD). Branch short names are accepted (main → refs/heads/main).
-n, --max-count Show at most N matching entries (newest first). Alias: --limit.
--since, --after Exclude entries older than this date (Git --since).
--until, --before Exclude entries newer than this date (Git --until).
--grep Keep entries whose message contains this substring (case-sensitive).
list List refs that have a reflog (-n / --limit bounds the list).
delete Remove one or more ref@{n} selectors.
expire Drop old reflog entries using gc expiry rules.
--all On expire, walk every ref under refs/, not only refs that already have log files.
--expire Reachable expiry time (now, never, 2.weeks.ago, Unix time, …).
--expire-unreachable Unreachable expiry time (same syntax as Git).
--dry-run On expire, preview pruning without writing reflog files.

JSON output

Schema: v1 (show entries), list v1, delete v1, expire v1

List (grit reflog [REF]):

Field Type Meaning
ref string Ref that was listed.
truncated boolean true when listing stopped before the oldest entry (typically because of -n).
entries array Newest-first entries.
entries[].index integer Newest-first index in the full reflog (0 is latest).
entries[].oid string Hex object id stored as new_oid for that entry (v1 alias of new_oid).
entries[].old_oid string Previous object id before the update.
entries[].new_oid string Object id after the update (same as oid).
entries[].date string Reflog committer time in RFC 3339 (original offset preserved).
entries[].relative_date string Human-relative time from the entry identity.
entries[].committer object name, email, and date (same shape as log / blame).
entries[].message string Reflog message (may be empty).
entries[].action string (optional) Best-effort prefix before the first ": " in the message.

Delete (grit reflog delete …):

Field Type Meaning
deleted array of strings Selectors that were removed.

List refs (grit reflog list):

Field Type Meaning
refs array Sorted ref names that have a log.
refs[].ref string Full ref name (for example refs/heads/main).

Expire (grit reflog expire):

Field Type Meaning
entries_pruned integer Reflog lines removed (or that would be removed with --dry-run).
dry_run boolean true when --dry-run was passed (default false).
refs array Per-ref prune counts.
refs[].ref string Ref that was processed.
refs[].pruned integer Entries pruned on that ref.

Markdown output

Pass --markdown for agent-friendly output.

Schema: v1 (show entries); subcommands use list v1, delete v1, and expire v1.

List mode emits a bullet per entry with REF@{n}, abbreviated oid, absolute date, and message (human mode keeps relative dates). Delete and expire print short confirmation lines.

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.