git cherry: Usage, Options & Common CI Errors
git cherry tells you which of your commits are already upstream and which are not.
Before backporting or re-pushing, cherry distinguishes commits whose change is already present upstream (by patch id) from those still missing - handy for release and backport gates.
What it does
git cherry compares a branch against an upstream and marks each commit with - if an equivalent change already exists upstream (matched by patch id) or + if it does not.
Common usage
git cherry -v main feature
git cherry main # upstream=main, head=current
git cherry -v upstream/main HEAD
# count unmerged commits:
git cherry main feature | grep -c '^+'Options
| Flag | What it does |
|---|---|
| -v | Show commit subjects alongside markers |
| <upstream> | Branch to compare against |
| <head> | Branch to examine (default: HEAD) |
| <limit> | Restrict to commits after this point |
Common errors in CI
cherry matches by patch id, so a commit that was rebased or slightly modified still shows + even though it is logically present - do not treat + as "definitely missing". A shallow clone can also skew results because the upstream history needed for patch-id matching is incomplete.
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