git gc: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

git gc (garbage collect) packs loose objects and prunes unreachable ones to keep the repository tidy.

gc reclaims space and speeds up operations. Git runs it automatically, but you can invoke it directly.

What it does

git gc packs loose objects into packfiles, removes redundant objects, prunes unreachable objects past the grace period, and packs refs to optimize the repository.

Common usage

Terminal

git gc
git gc --aggressive            # slower, better compression
git gc --prune=now             # prune immediately
git gc --auto                  # only if thresholds are exceeded

Options

Flag	What it does
--aggressive	Recompute deltas for tighter packing
--prune=<date>	Prune unreachable objects older than date
--auto	Run only when needed (used internally)
--no-prune	Do not prune any objects

Common errors in CI

fatal: gc is already running on machine … / "Unable to create '.git/gc.pid.lock': File exists" - a stale lock from a killed process. Remove .git/gc.pid.lock if no gc is actually running. Aggressive gc is slow; avoid it in time-boxed CI steps.

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

Frequently asked questions

git gc: Usage, Options & Common CI Errors?