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

> git rev-list --count returns the number of commits in a range. Reference for --left-right, ranges, and using ahead/behind counts to gate pipelines.

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

git rev-list --count prints how many commits a range contains.

Need to know how many commits a branch is ahead, or how many landed since a tag? rev-list --count gives a single number that is easy to compare in CI conditions.

## What it does

git rev-list --count walks the requested revision range and prints only the count of matching commits, instead of listing their SHAs.

## Common usage

```Terminal
git rev-list --count HEAD
git rev-list --count main..feature        # commits ahead of main
git rev-list --count --left-right main...feature
git rev-list --count v1.0.0..HEAD         # commits since a tag
```

## Options

| Flag | What it does |
| --- | --- |
| --count | Print the number, not the list |
| <a>..<b> | Commits in b not in a |
| <a>...<b> | Symmetric difference |
| --left-right | With ..., split counts per side |
| --no-merges | Exclude merge commits |

## Common errors in CI

A two-dot range (main..feature) needs both refs present; on a shallow clone the merge base may be missing and the count is wrong or errors. Use fetch-depth: 0. Note .. (asymmetric) and ... (symmetric) differ - mixing them up gives surprising ahead/behind numbers.

## 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 --count: Usage, Options & Common CI Errors?

Need to know how many commits a branch is ahead, or how many landed since a tag? rev-list --count gives a single number that is easy to compare in CI conditions.

### What it does?

git rev-list --count walks the requested revision range and prints only the count of matching commits, instead of listing their SHAs.

### Common errors in CI?

A two-dot range (main..feature) needs both refs present; on a shallow clone the merge base may be missing and the count is wrong or errors. Use fetch-depth: 0. Note .. (asymmetric) and ... (symmetric) differ - mixing them up gives surprising ahead/behind numbers.

---

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