Git gc and repack Strategies

What you will learn

• Understand the core purpose of Git gc and repack Strategies
• Master the basic usage and common options of Git gc and repack Strategies
• Master git gc, git repack, and git maintenance to keep your repository healthy and performant through proper object management.
• Understand key concepts: Overview
• Know when to use this feature and when to avoid it

Start with a problem

Your Git repository keeps growing, clones are getting slower, and everyday operations are starting to feel sluggish. You want to know what optimization techniques are available and which ones fit your project.

Overview

As commits accumulate, Git's object store becomes fragmented. git gc (Garbage Collection) and git repack are essential tools for reclaiming space and improving performance.

git gc

Basic Usage

# Run garbage collection
git gc

# More aggressive (thorough compression)
git gc --aggressive

# Lightweight cleanup only
git gc --auto

git gc performs these operations:

1. Compress loose objects into pack files
2. Remove unreachable objects
3. Update reference logs
4. Optimize repository storage

Auto-Trigger

# Git runs git gc --auto after certain operations:
# - git commit (when loose objects exceed threshold)
# - git fetch
# - git merge

# View gc config
git config --global --list | grep gc

# Common settings
git config --global gc.auto 6700           # Trigger threshold
git config --global gc.autoPackLimit 50    # Pack file limit
git config --global gc.bigPackThreshold 2G # Skip packs over 2G

git repack

git repack is the core operation behind git gc, managing pack files directly.

# Pack all loose objects
git repack -a -d

# Incremental repack (new objects only)
git repack

# With delta compression (recommended)
git repack -a -d --window=250 --depth=50

Key Options

Optimization Example

# Recommended periodic maintenance
git repack -a -d --window=250 --depth=50 --threads=4

# For large repos, use a larger window
git repack -a -d --window=500 --depth=100 --threads=0
# --threads=0 means use all CPU cores

git maintenance

Git 2.31+ introduced git maintenance for smarter automatic maintenance.

# Register current repo for auto-maintenance
git maintenance start

# Run maintenance immediately
git maintenance run

# Run specific tasks only
git maintenance run --task=gc
git maintenance run --task=loose-objects
git maintenance run --task=incremental-repack

Maintenance Tasks

Scheduled Maintenance

# Enable scheduled maintenance
git maintenance start  # Configures system scheduler

# On macOS/Linux, uses launchd/systemd
# Manual cron example (every Sunday 3 AM)
0 3 * * 0 cd /path/to/repo && git maintenance run

Strategy Recommendations

Personal Repos

# Default config is usually fine
git config --global gc.auto 6700

Large Repos

# More frequent, deeper maintenance
git config --global gc.auto 10000
git maintenance start

CI Environment

# Avoid gc/repack in CI
# Use shallow clone instead
git clone --depth 1 ...

Safety Notes

1. git gc won't delete reflog entries that haven't expired
2. git repack -a -d can be slow — don't run on shared repos in use
3. GC'd objects can still be recovered via reflog for a time
4. Avoid frequent --aggressive on bare repos

Try it yourself

1. Practice the gc-repack-strategies command in a test repository and observe state changes before and after
2. Experiment with different options and compare the output differences
3. Simulate a real scenario where you would need to use this, and walk through the full process

Continue Learning

1. performance/shallow-clone-deep — Deep dive into shallow clone
2. performance/partial-clone — Partial clone guide
3. internals/packfiles-and-storage — Pack file internals

Further reading

Keep going on the same topic:

• Commit Graph Deep Dive
• Git Maintenance Deep Dive
• Large Repository Performance Optimization