git rev-list

Engine behind git log, cherry, bisect — the DAG walker.

🎯 What & why

git rev-list is the DAG walker that powers log, cherry, bisect, and most history-aware plumbing. If you script anything about commits, you reach for it.

🧠 Mental model

Give it a set of tips and exclusions; it emits commit SHAs in topo order. log is rev-list with formatting bolted on - rev-list is the engine, not the UI.

🛠️ Synopsis

git rev-list [<options>] <commit>... [-- <path>...]

  A..B          # commits reachable from B but not A
  A...B         # symmetric difference
  ^A B          # B minus A (same as A..B for two refs)
  --count       # just print the number
  --objects     # also list trees and blobs reachable

🎚️ Switches & options

Flag	What it does
`<commit>...`	Tip commits to walk from
`^<commit>`	Exclude this commit and its ancestors from the walk
`--max-count=<n>`	Stop after n commits
`--reverse`	Output oldest-first instead of newest-first
`--first-parent`	Follow only the first parent of merges (linearize)
`--no-merges`	Skip merge commits
`--ancestry-path`	Only commits on a path between two endpoints
`--bisect`	Pick the midpoint commit (used by git bisect)
`--count`	Print the count instead of the SHAs
`--objects`	Also emit referenced tree and blob SHAs
`--pretty[=<fmt>]`	Format each commit (turns rev-list into log)

💡 Use cases

Count commits ahead/behind a remote: git rev-list --count main..@{u}.
Find every object reachable from a ref for size analysis or transfer.
Walk only the mainline by ignoring merged-in branches with --first-parent.
Drive custom bisect-like binary searches with --bisect.

🧪 Examples

Ahead/behind count

git rev-list --left-right --count main...origin/main

Linear mainline only

git rev-list --first-parent --no-merges main

All reachable objects

git rev-list --objects --all | head

Oldest-first replay list

git rev-list --reverse main..feature

🎓 Recommendations

Reach for rev-list (not log) whenever you need machine-readable commit lists - it has no formatting surprises.
Use --count instead of wc -l piping; it is faster and semantically clearer.
Combine --objects with git cat-file --batch-check for pack/object size auditing.

🪤 Common pitfalls

Forgetting ^ or .. syntax: git rev-list main feature walks BOTH tips, not the diff.
--first-parent changes ancestry semantics - do not mix it into commands that need true reachability.
--ancestry-path requires both endpoints; a single tip silently does nothing useful.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.