# git rev-list: Usage, Options & Common CI Errors

> git rev-list lists commit objects in reverse order, the plumbing behind counting and walking history. Reference for --count, --left-right, and ranges.

Source: https://latchkey.dev/learn/command-reference/git-rev-list  
Updated: 2026-06-25

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

```Terminal
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 HEAD
```

## Options

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

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git rev-list: Usage, Options & Common CI Errors?

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

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt