Map command

Home / Commands / map

commitbrief map

Draw the commit graph — and, when a filter is active, show exactly which commits it selected. Deterministic: no provider call, no cache, no cost, and it always exits 0 on a successful render. A viewer, not a gate.

Why this exists

The commit filters can select a non-contiguous set of commits from anywhere in the history. That is what makes them powerful, and also what makes them invisible: the only feedback is a count.

$ commitbrief dry-run --author alice --start-date 2026-06-01
Commits (matched): 12

Which twelve? For a filter whose entire job is deciding what gets reviewed, "trust me, twelve" is weak feedback — and a wrong filter quietly reviews the wrong code.

$ commitbrief map --author alice --start-date 2026-06-01

shows them, in place, against the commits they were interleaved with.

Synopsis

commitbrief map [<git range>...]

commitbrief map                            # the DAG, newest first
commitbrief map --max-commits 50
commitbrief map main..develop              # bound to a range
commitbrief map --author alice             # matches highlighted, rest dimmed
commitbrief map --branches                 # branch topology instead
commitbrief map --all                      # every ref, not just HEAD's history

Commit graph (default)

One row per commit: lane gutter, short hash, ref labels, subject, author, relative age.

● a1b2c3d  (main) feat: add commit filters        alice  2h
│╲
│ ○ e4f5a6b  (payments/stripe) chore: bump sdk    bob    3d
│ ○ b7c8d9e  fix: rounding                        bob    3d
│╱
● f0a1b2c  docs: readme                           carol  1w

● matches the filter   ○ context

With no filter every commit is ● and no legend is printed. With one, matches are highlighted and the rest are drawn as dimmed context — deliberately kept in the graph, because a picture of only the matches would be a list, not a graph, and the lanes would be meaningless.

Merge commits are always drawn here, even though the filters exclude them by default elsewhere. In a graph a merge is structure: hiding it leaves lanes that fork and never rejoin.

Branch topology (--branches)

One row per branch — where it sits relative to the base and how far it has drifted:

main                      base       alice  2h
├─ payments/stripe        ▲3   ▼12   bob    3d
└─ feature/upgrade        ▲8   ▼0    alice  1h

▲ is ahead (commits this branch has that the base does not), ▼ is behind. The base is resolved from origin/HEAD, falling back to main/master/trunk, then the current HEAD — it never fails, because a topology view with an imperfect base beats an error. Capped at 200 refs.

Commit filters are rejected in this mode: a branch list has no commits to select, and rendering an unchanged view that silently ignored your flag would be worse than saying so.

Flags

Flag	Default	Description
--branches	off	Branch topology summary instead of the commit graph.
--all	off	Walk every ref rather than the given range / HEAD. Graph mode only.
--max-commits <N>	200	How many commits to draw. Truncation is reported on stderr.

All the commit filters apply in graph mode.

Rejected flags

map draws a graph, not findings, so flags that promise something else are refused rather than quietly ignored:

• --json / --markdown — a graph JSON (nodes, edges, lanes) would be a new versioned schema for output whose consumer is a person looking at a terminal. Deferred until someone asks with a real use case. Use --output <file> to capture the plain-text graph.
• --fail-on / --min-severity / --suggest-commit — there are no findings to act on.

Terminal behavior

• Rows clip to the terminal width rather than wrapping. A wrapped row would carry no lane gutter on its continuation line, visually detaching it from the graph. The gutter is drawn first, so the topology survives even when a subject is cut.
• Colour and box-drawing fall back together: a terminal that refused ANSI is also the one most likely to mangle │. A pipe, a file, or --color=never yields pure ASCII (*, o, |, \, /).
• Relative ages are coarse on purpose (3d, not 3 days 4 hours) to keep the column scannable.
• A truncated walk closes lanes at the boundary rather than inventing edges to commits it was never given, so the graph shows where it stops.

See also

• Filtering — the filters this visualises.
• Dry-run command — the counts map gives a shape to.
• Diff command — reviewing the range you just inspected.
• Global flags — the shared flag surface.