Skip to content

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 --count returns 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-right tells you exactly which commits exist on one branch but not the other. Automate backport gap reports.
  • Find the bisect boundary — rev-list --bisect is the algorithm that powers git 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>..HEAD shows only the commits that landed directly on main, skipping feature-branch internals.

Table of Contents ​

  1. Basic Traversal and Counting
  2. Commit Selection and Filtering
  3. Symmetric Difference and Cherry Detection
  4. Parent and Topology Filters
  5. Ordering and Output Format
  6. Bisect Integration
  7. Stdin and Programmatic Use
  8. Deployment Gates and Release Automation
  9. 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 HEAD

DevOps 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
fi

2. 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" main

By 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" main

By 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" HEAD

By 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."
fi

By 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 HEAD

This 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.x

DevOps 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 --all

First-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..main

No-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 sha3

Ancestry-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..main

Devops 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
done

5. 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..HEAD

Format (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 --all

DevOps 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"
done

6. 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..HEAD

These 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 main

Object 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
done

Pattern: 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
done

Pattern: 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
done

Pattern: 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 ​

FlagPurposeDevOps Use
--countReturn integer count of commitsDeploy gates, release metrics
--left-rightMark < commits on right side, > on leftCross-branch diff analysis
--cherry-markMark = for patch-equivalent commitsBackport gap detection
--cherry-pickShow only +/- marked commitsCherry-pick automation
--min-parents=NOnly commits with ≥ N parentsMerge audits
--max-parents=NOnly commits with ≤ N parentsFind root/orphan commits
--first-parentFollow only the first parent chainClean mainline history
--bisectFind the midpoint commit (bisect algorithm)Estimate bisect cost
--since/--afterFilter by time (absolute or relative)Changelog by sprint
--beforeUpper time boundWindowed analysis
--author/--committerFilter by author patternAttribution reports
--grepFilter commit message patternJira-tagged release notes
--skip=NSkip first N commitsPagination, batch processing
--max-count=NLimit output to N commitsSingle-commit extraction
--reverseOldest-first orderLinearizing commit chains
--topo-orderParents before childrenSafe cherry-pick ordering
--date-orderBy commit dateChronological analysis
--ancestry-pathOnly commits on direct ancestry lineClean range boundaries
--stdinRead SHAs from stdinComposable Git pipelines
--missingList missing objects (promisor remotes)Partial clone debugging
--allAll refs (branches + tags)Global repository queries
--notExclude reachable commitsNegation in ref queries
--no-walkDon't walk ancestryIndividual 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 logUse git rev-list when
git log --oneline --count v1.0..HEADYou want just the number, no formatting overhead
git log --left-right --cherry-pick main...releaseYou want SHAs to feed into another pipe
git log --skip=100 --max-count=10 HEADYou'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 log querying and pickaxe search (the porcelain counterpart)
  • docs/devops-workflows/git-bisect-ci-triage.md — automated regression triage using the bisect rev-list drives
  • docs/recipes/rev-list-quick.md — one-page cheat sheet
  • scripts/rev-list-manage.sh — automation utility for common DevOps rev-list operations

Git Master — Git Reference for Every Skill Level