git prune: Usage, Options & Common CI Errors
git prune removes objects that are no longer reachable from any ref.
Prune is the low-level cleanup that permanently drops dangling objects. It is destructive to recovery, so most pipelines should run git gc (which prunes safely) rather than prune directly.
What it does
git prune deletes loose objects that are unreachable from any ref and older than the expiry window, reclaiming space but also removing the only copies of orphaned commits.
Common usage
git prune -n # dry run: list what would go
git prune
git prune --expire=2.weeks.ago
git gc # the recommended safe wrapperOptions
| Flag | What it does |
|---|---|
| -n / --dry-run | Show what would be pruned |
| -v / --verbose | Report each pruned object |
| --expire <time> | Only prune objects older than this |
| -- | Treat following args as heads to protect |
Common errors in CI
prune makes reflog- and stash-based recovery impossible for the objects it removes, so never run it while a rebase/merge is mid-flight or right after a reset you might want to undo. Prefer git gc, which runs prune with safe defaults and respects the reflog expiry window.
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