git rev-list: Usage, Options & Common CI Errors
git rev-list is the plumbing that enumerates commits - counting them, comparing branches, walking ranges.
rev-list powers ahead/behind counts and history walks in scripts. It is git log without the formatting.
What it does
git rev-list outputs commit SHAs reachable from given refs in reverse chronological order, with flags to count, limit, and compare ranges - the engine many porcelain commands sit on.
Common usage
git rev-list --count HEAD # total commit count
git rev-list --count main..feature # commits ahead
git rev-list --left-right --count main...feature # behind<TAB>ahead
git rev-list --max-count=10 HEADOptions
| Flag | What it does |
|---|---|
| --count | Print the number of commits, not SHAs |
| --left-right | Mark which side of a symmetric range |
| --max-count=<n> | Limit how many commits |
| --no-merges | Exclude merge commits |
| --all | Start from all refs |
Common errors in CI
Counts are wrong or capped on a shallow clone because history is truncated - deepen with git fetch --unshallow or fetch-depth: 0. A symmetric range (A...B) needs both refs present, so fetch the target branch first.
Using this in CI
CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.
- uses: actions/checkout@v4
with:
fetch-depth: 0 # history, tags, and git describe all need this
- run: |
git rev-parse --is-shallow-repository # expect false
git rev-parse --abbrev-ref HEAD # prints HEAD when detached