gc Git Command Guide

The git gc command is used to run housekeeping tasks within the current repository, such as compressing file revisions, removing unreachable objects, packing refs, pruning reflog, and updating ancillary indexes like the commit-graph.

git gc Syntax:

git gc [--aggressive] [--auto] [--[no-]detach] [--quiet]
       [--prune=<date> | --no-prune] [--force] [--keep-largest-pack]

Options:

Option	Description
—aggressive	Aggressively optimize (much slower)
—auto	Check if housekeeping needed, exit if not
—detach	Run in background (default)
—no-detach	Run in foreground
—quiet	Suppress progress reports
—prune=	Prune loose objects older than date (default: 2 weeks)
—no-prune	Don’t prune loose objects
—force	Force run even if another gc is running
—keep-largest-pack	Consolidate all except largest pack

Parameters:

Parameter	Description
(none)	Operates on current repository

git gc Command Samples:

Basic repository maintenance

git gc

Run standard garbage collection and optimization.

Aggressive optimization

git gc --aggressive

Spend extra time for maximum optimization (not usually worth it).

Check if maintenance needed

git gc --auto

Only run if repository needs housekeeping.

Prune old objects immediately

git gc --prune=now

Prune loose objects regardless of age (risky if repo is active).

Force run even if another gc running

git gc --force

Run garbage collection despite concurrent gc processes.

Quiet operation

git gc --quiet

Run without progress output.

Custom prune expiration

git gc --prune=1.month.ago

Prune objects older than 1 month.

Keep largest pack file

git gc --keep-largest-pack

Preserve largest pack, consolidate others.

Run in foreground

git gc --no-detach

Run in foreground instead of background.

Full maintenance with commit graph

git gc && git maintenance start

Run traditional gc followed by modern maintenance.

How do I run basic repository maintenance?

To run basic repository maintenance, simply use:

git gc

This compresses objects, removes unreachable ones, and optimizes the repository.

How does —auto work?

To check if maintenance is needed without forcing it, use:

git gc --auto

This exits early if no housekeeping is required based on configuration thresholds.

When should I use —aggressive?

To use aggressive optimization when optimization is critical, run:

git gc --aggressive

This re-computes all deltas but takes significantly longer and may not be worth it.

How do I control pruning of loose objects?

To control when loose objects are pruned, use —prune:

git gc --prune=1.week.ago

This prunes objects older than the specified time.

How can I run gc in the background?

To run gc in the background (default), use:

git gc

Or explicitly:

git gc --detach

How do I run gc in foreground?

To run gc in the foreground, use:

git gc --no-detach

This is useful for scripts that need gc to complete before continuing.

When is —force useful?

To force gc even if another instance is running, use:

git gc --force

This bypasses safety checks and should be used carefully.

How do I maintain repositories automatically?

To enable automatic maintenance on regular operations, configure:

git config gc.auto 256
git config gc.autopacklimit 50

This triggers gc when object count exceeds configured thresholds.

What’s the difference between git gc and git maintenance?

git gc focuses on pack file optimization, while git maintenance handles broader cleanup. Use both:

git gc && git maintenance run --all

How do I disable automatic gc?

To disable automatic gc runs during porcelain commands, use:

git config gc.auto 0

Applications of the git gc command

Optimizing repository performance and reducing storage
Cleaning up after bulk imports or large object additions
Periodic repository maintenance for long-term projects
Troubleshooting strange repository behavior
Preparing repositories for archive or backup
Reducing repository size for distribution