# git gc Command: Repack Repos in CI

> git gc compresses and cleans up a repository. Reference for --prune, --aggressive, and --auto to keep cached or long-lived CI checkouts small and fast.

Source: https://latchkey.dev/learn/command-reference/git-gc-command-reference  
Updated: 2026-06-26

git gc packs loose objects and prunes unreachable ones to reduce repo size and speed up operations.

On runners that cache a clone across many builds, the .git directory accumulates loose objects. Running gc periodically keeps the cached repo lean and fast to fetch.

## Common flags

- `--auto` - run gc only if the repo has crossed internal thresholds (cheap to call)
- `--prune=<date>` - prune unreachable objects older than the given date (e.g. now)
- `--aggressive` - repack more thoroughly at higher CPU cost
- `--no-cruft` - write pruned objects loose instead of in a cruft pack
- `--quiet` / `-q` - suppress progress output

## Example

```shell
# Keep a cached CI checkout compact between builds
git gc --auto --prune=now
```

## In CI

Use git gc --auto in cache-restore steps: it is nearly free when nothing is needed and only repacks when the repo has grown. Avoid --aggressive in CI unless disk size is critical, since it is CPU-heavy. Ephemeral runners rarely need gc at all.

## 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 gc Command: Repack Repos in CI?

On runners that cache a clone across many builds, the .git directory accumulates loose objects. Running gc periodically keeps the cached repo lean and fast to fetch.

### In CI?

Use git gc --auto in cache-restore steps: it is nearly free when nothing is needed and only repacks when the repo has grown. Avoid --aggressive in CI unless disk size is critical, since it is CPU-heavy. Ephemeral runners rarely need gc at all.

---

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