Appearance
git rev-list: The Plumbing Engine for CI/CD Automation
git rev-list is Git's low-level commit traversal engine. Every command that walks the commit graph — git log, git bisect, git merge-base, git shortlog, git cherry — runs rev-list under the hood. For a DevOps engineer writing CI automation, it is the single most versatile plumbing command you can learn.
git log is rev-list piped through diff-tree with pretty-printing. When you need counts, machine-readable output, or flags that git log doesn't expose, use rev-list directly.
Why a DevOps Engineer Needs This
- Count commits between deployments —
rev-list --countreturns a number, not a page of output. Wire it into a deploy gate: "if more than 50 commits since last tag, require a second approval." - Detect unpicked cherry-picks across branches —
rev-list --cherry --left-righttells you exactly which commits exist on one branch but not the other. Automate backport gap reports. - Find the bisect boundary —
rev-list --bisectis the algorithm that powersgit bisect. Use it to estimate how many CI runs a regression search will cost (and surface that cost in your PR dashboard). - Filter by parent count — find merge commits (
--min-parents=2), root commits (--max-parents=0), or single-parent commits. Audit your branching model automatically. - Walk the first-parent chain for deployment provenance —
rev-list --first-parent <tag>..HEADshows only the commits that landed directly on main, skipping feature-branch internals.
Table of Contents
- Basic Traversal and Counting
- Commit Selection and Filtering
- Symmetric Difference and Cherry Detection
- Parent and Topology Filters
- Ordering and Output Format
- Bisect Integration
- Stdin and Programmatic Use
- Deployment Gates and Release Automation
- Script: rev-list-manage.sh
1. Basic Traversal and Counting
rev-list accepts commit ranges (the same .. and ... syntax as git log):
bash
# List all commits reachable from HEAD but not from v1.0
git rev-list v1.0..HEAD
# Count them (returns an integer, exits 0)
git rev-list --count v1.0..HEAD
# All commits reachable from either tag, but not both (symmetric diff)
git rev-list --count v1.0...v2.0
# With excluded refs: commits reachable from main, excluding anything in release
git rev-list main ^release/2.x
# Shorthand: all branches except the current one
git rev-list --all --not HEADDevOps pattern — deploy gate:
bash
COMMIT_COUNT=$(git rev-list --count v1.0..HEAD)
if [ "$COMMIT_COUNT" -gt 50 ]; then
echo "::warning::Deploy gate: $COMMIT_COUNT commits since last tag. Requiring approval."
exit 1
fi2. Commit Selection and Filtering
These flags control which commits are emitted, independent of the reachability set.
By time
bash
# Commits in the last 7 days
git rev-list --since="7 days ago" HEAD
# Commits before a specific date
git rev-list --before="2026-09-01" main
# Range intersection
git rev-list --after="2026-08-01" --before="2026-09-01" mainBy author
bash
# Commits by a specific author
git rev-list --author="jane@example.com" HEAD
# Commits NOT by a specific committer
git rev-list --committer="bot@ci.example.com" --not HEAD --all
# Multiple authors (regex)
git rev-list --author="jane\|john" mainBy message pattern
bash
# Commits whose message matches a pattern (grep, not pickaxe)
git rev-list --grep="hotfix" v1.0..HEAD
# Or combine: commits tagged with a Jira ticket
git rev-list --grep="PROJ-[0-9]\+" --author="jane" --since="7 days ago" HEADBy file path
bash
# Commits that touched a specific path
git rev-list HEAD -- src/lib/parser.ts
# Exclude test files from the count
git rev-list --count HEAD -- :^src/__tests__
# Commits touching multiple directories
git rev-list HEAD -- src/api/ src/cli/DevOps pattern — changed-area commit count:
bash
# Count how many commits touched the payment module in this release
PAYMENT_COMMITS=$(git rev-list --count v1.0..HEAD -- payments/)
if [ "$PAYMENT_COMMITS" -gt 0 ]; then
echo "Payment module changed ($PAYMENT_COMMITS commits). Tagging for regression tests."
fiBy commit-ish list (max-count / skip)
bash
# First 5 commits on main
git rev-list --max-count=5 HEAD
# Skip the first 100 and show the next 10
git rev-list --skip=100 --max-count=10 HEAD
# The single most recent commit (like `git rev-parse HEAD`)
git rev-list --max-count=1 HEADThis is the pagination pattern — use --skip and --max-count for batch-processing large histories.
3. Symmetric Difference and Cherry Detection
The three-dot ... range shows commits reachable from either ref but not from both. Combined with --left-right and --cherry, this is the most powerful cross-branch analysis tool in Git.
Left-right markers
bash
# Compare main and release: mark commits unique to each side
git rev-list --left-right main...release/2.x
# Output:
# >commit_sha1 (on release/2.x, not on main)
# <commit_sha2 (on main, not on release/2.x)Cherry detection
--cherry-mark identifies commits whose patch content is identical (even if SHA or message differs):
bash
git rev-list --cherry-mark --left-right main...release/2.x
# Output:
# =commit_sha1 (patch-equivalent commit — exists on both)
# >commit_sha2 (on release/2.x, no equivalent on main)
# <commit_sha3 (on main, no equivalent on release/2.x)--cherry-pick is shorthand: drops the = commits and leaves only the > and < markers with +/-:
bash
git rev-list --cherry-pick --left-right main...release/2.xDevOps pattern — backport gap report:
bash
#!/bin/bash
# Detect hotfix commits in main that have no equivalent on release/2.x
UNPORTED=$(git rev-list --count --right-only --cherry-pick main...release/2.x)
echo "Backport gap: $UNPORTED hotfix commits on main not ported to release/2.x"4. Parent and Topology Filters
Most DevOps engineers never use these. They are invaluable for branching-model audits.
Min/max parents
bash
# Merge commits only (at least 2 parents)
git rev-list --min-parents=2 HEAD
# Regular commits only (exactly 1 parent)
git rev-list --min-parents=1 --max-parents=1 HEAD
# Root commits (0 parents — orphan branches, initial commits)
git rev-list --max-parents=0 --all
# Octopus merges (3+ parents)
git rev-list --min-parents=3 --allFirst-parent walk
bash
# Only the merge commits that landed on main
git rev-list --first-parent --min-parents=2 main
# Count of direct mainline commits since the tag
git rev-list --first-parent --count v1.0..mainNo-walk
Process each listed commit without walking its ancestors:
bash
# Get the commit dates for a list of SHAs
git rev-list --no-walk --format="%H %ai" sha1 sha2 sha3Ancestry-path
Show only commits that are ancestors of one ref AND descendants of another — useful for finding the "effective" range excluding branches that diverged:
bash
# Only commits on the direct path between v1.0 and main
git rev-list --ancestry-path v1.0..mainDevops pattern — merge audit:
bash
# Find all merge commits that brought more than N commits
git rev-list --min-parents=2 --format="%H %P" main | while read sha parents; do
count=$(git diff-tree --name-only "$sha" -- | wc -l)
if [ "$count" -gt 30 ]; then
echo "$sha merged $count files — consider feature flags instead"
fi
done5. Ordering and Output Format
Controlling output order matters when feeding rev-list into pipelines.
Ordering
bash
# By commit date (newest first) — default
git rev-list --date-order HEAD
# Topological order (parents before children, required for safe cherry-pick chains)
git rev-list --topo-order HEAD
# Topological order grouped by author timestamp
git rev-list --author-date-order HEAD
# Reversed (oldest first — good for linearizing a range to apply)
git rev-list --reverse v1.0..HEADFormat (machine-readable)
bash
# Just the SHAs (default) — pipeable
git rev-list v1.0..HEAD
# Raw timestamps for script consumption
git rev-list --format="%H %at %ct %an" v1.0..HEAD | grep -v "^commit "
# Null-separated (safe for tricky filenames)
git rev-list v1.0..HEA --null | xargs -0 -n1 echo
# Object name (abbreviated)
git rev-list --abbrev-commit --max-count=5 HEAD
# Missing check (partial clone / promisor)
git rev-list --missing=print --allDevOps pattern — zero-padded commit density report:
bash
# Commits per day for the last 14 days
for d in $(seq 0 13); do
day=$(date -d "-$d days" +%Y-%m-%d)
count=$(git rev-list --count --after="$day 00:00" --before="$day 23:59" HEAD)
echo "$day $count"
done6. Bisect Integration
git rev-list --bisect is the algorithm git bisect uses to find the optimal next commit to test. You can use it directly to evaluate bisect cost before starting one.
bash
# How many steps will a bisect take?
STEPS=$(git rev-list --bisect v1.0..HEAD | wc -l 2>/dev/null || echo 0)
echo "~$STEPS bisect steps for range v1.0..HEAD ($(git rev-list --count v1.0..HEAD) commits)"
# Approximate: log_2(N) ≈ number of tests needed
N=$(git rev-list --count v1.0..HEAD)
echo "Bisect range: $N commits ≈ $(python3 -c "import math; print(math.ceil(math.log2($N)))") runs"Mark history for bisect with --bisect flags
bash
# Find a bisect candidate (the commit that splits the remaining range in half)
git rev-list --bisect --all
# Not just HEAD — compute for any range
git rev-list --bisect v1.0..HEADThese are the same mechanics that bisect--helper uses internally. You would rarely call them directly, but understanding the cost helps you decide whether to bisect or git log --grep the range.
7. Stdin and Programmatic Use
rev-list accepts commit SHAs on stdin, making it the ideal hub for composable Git pipelines.
bash
# Read SHAs from a file, count them
git rev-list --stdin --count < /tmp/commits-to-check.txt
# Combine with other rev-list calls
git rev-list --all --not HEAD | git rev-list --stdin --count
# Intersect two lists
git rev-list --stdin < <(git rev-list main) | grep -Fxf <(git rev-list release)DevOps pattern — bulk cherry-pick check:
bash
# Given a list of SHAs from an external source (Jira, API), check if
# each one is already merged into main
cat /tmp/patches-to-verify.txt | git rev-list --stdin --not origin/main | wc -l
# Result: 0 means all are merged; >0 means some are missing from mainObject existence checks
bash
# Check if a commit object exists (exit code: 0 = yes, empty output = yes)
git rev-list --max-count=1 -q --verify abc123 2>/dev/null && echo "exists"
# Verify a range is valid
git rev-list --count v1.0..v1.1 >/dev/null 2>&1 || echo "Range invalid"8. Deployment Gates and Release Automation
Real-world CI patterns that combine multiple rev-list features.
Pattern: Deployment health gate
bash
#!/bin/bash
# gate.sh — exit 1 to block deployment
set -euo pipefail
TAG=v1.0
HEAD=HEAD
COUNT=$(git rev-list --count "$TAG..$HEAD")
echo "Commits since $TAG: $COUNT"
if [ "$COUNT" -gt 100 ]; then
echo "Blocking deploy: $COUNT commits is too large for a single deployment"
exit 1
fi
MERGE_COUNT=$(git rev-list --count --min-parents=2 "$TAG..$HEAD")
echo "Merged PRs: $MERGE_COUNT"
# Check if any commit messages contain "WIP" or "DO NOT MERGE"
BLOCKERS=$(git rev-list --grep="DO NOT MERGE\|WIP" "$TAG..$HEAD")
if [ -n "$BLOCKERS" ]; then
echo "Blocking deploy: found commits with blocked labels"
echo "$BLOCKERS"
exit 1
fi
echo "Gate passed."Pattern: Release notes outline by area
bash
#!/bin/bash
# release-areas.sh — show commit counts by directory
TAG=v1.0
for area in src/api src/cli payments/ docs/; do
count=$(git rev-list --count "$TAG..HEAD" -- "$area" 2>/dev/null || echo 0)
if [ "$count" -gt 0 ]; then
echo "$area: $count commits"
fi
donePattern: Hotfix backport verification
bash
#!/bin/bash
# backport-check.sh — verify a hotfix SHA landed on two branches
SHA=$1
for branch in main release/2.x release/2.1; do
if git rev-list --count "$branch" | grep -q "$SHA" 2>/dev/null; then
echo "$SHA present on $branch"
else
echo "WARNING: $SHA MISSING from $branch"
fi
donePattern: Stale branch detection
bash
#!/bin/bash
# stale-branches.sh — detect branches with no commits in 90 days
for branch in $(git for-each-ref --format='%(refname:short)' refs/heads/); do
count=$(git rev-list --count --since="90 days ago" "$branch" --not origin/main 2>/dev/null || echo 0)
if [ "$count" -eq 0 ]; then
echo "STALE: $branch (no new commits in 90 days)"
fi
donePattern: CI preflight — prevent force-push past shared commits
bash
# Query reflog: how many commits were on main before the latest push?
git rev-list --count --skip=1 --max-count=1 HEAD
# If this is >1 and the previous HEAD is not an ancestor, the push rewrote history.9. Full command reference
| Flag | Purpose | DevOps Use |
|---|---|---|
--count | Return integer count of commits | Deploy gates, release metrics |
--left-right | Mark < commits on right side, > on left | Cross-branch diff analysis |
--cherry-mark | Mark = for patch-equivalent commits | Backport gap detection |
--cherry-pick | Show only +/- marked commits | Cherry-pick automation |
--min-parents=N | Only commits with ≥ N parents | Merge audits |
--max-parents=N | Only commits with ≤ N parents | Find root/orphan commits |
--first-parent | Follow only the first parent chain | Clean mainline history |
--bisect | Find the midpoint commit (bisect algorithm) | Estimate bisect cost |
--since/--after | Filter by time (absolute or relative) | Changelog by sprint |
--before | Upper time bound | Windowed analysis |
--author/--committer | Filter by author pattern | Attribution reports |
--grep | Filter commit message pattern | Jira-tagged release notes |
--skip=N | Skip first N commits | Pagination, batch processing |
--max-count=N | Limit output to N commits | Single-commit extraction |
--reverse | Oldest-first order | Linearizing commit chains |
--topo-order | Parents before children | Safe cherry-pick ordering |
--date-order | By commit date | Chronological analysis |
--ancestry-path | Only commits on direct ancestry line | Clean range boundaries |
--stdin | Read SHAs from stdin | Composable Git pipelines |
--missing | List missing objects (promisor remotes) | Partial clone debugging |
--all | All refs (branches + tags) | Global repository queries |
--not | Exclude reachable commits | Negation in ref queries |
--no-walk | Don't walk ancestry | Individual SHA metadata |
10. Transition from git log to git rev-list
If you know git log, you already know rev-list. The flags are identical. The difference is the output:
You write this with git log | Use git rev-list when |
|---|---|
git log --oneline --count v1.0..HEAD | You want just the number, no formatting overhead |
git log --left-right --cherry-pick main...release | You want SHAs to feed into another pipe |
git log --skip=100 --max-count=10 HEAD | You're processing commits in a script |
git log --format="%H %an %ai" | You need raw data for a reporting dashboard |
git log adds diff-tree to show patches. rev-list gives you raw SHAs and metadata. If you don't need diffs, use rev-list.
See also
docs/devops-workflows/git-commit-forensics-querying.md—git logquerying and pickaxe search (the porcelain counterpart)docs/devops-workflows/git-bisect-ci-triage.md— automated regression triage using the bisectrev-listdrivesdocs/recipes/rev-list-quick.md— one-page cheat sheetscripts/rev-list-manage.sh— automation utility for common DevOps rev-list operations