# git prune: Usage, Options & Common CI Errors

> git prune deletes unreachable objects from the object store. Reference for -n, --expire, and why gc is usually the safer wrapper to run in CI.

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

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

```Terminal
git prune -n                    # dry run: list what would go
git prune
git prune --expire=2.weeks.ago
git gc                          # the recommended safe wrapper
```

## Options

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

```.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 prune: Usage, Options & Common CI Errors?

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

---

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