git prune

Usually invoked indirectly by gc.

🎯 What & why

git prune deletes loose objects that no ref (or reflog) can reach. It's how dangling commits, blobs, and trees finally get garbage collected from .git/objects/.

🧠 Mental model

Reachability is the only thing keeping an object alive. Cut every ref and reflog entry pointing at a commit, wait past the prune horizon, and prune will reap it. Until then it's safe.

🛠️ Synopsis

git prune [-n|--dry-run] [-v|--verbose] [--progress]
          [--expire <time>] [--exclude-promisor-objects] [--] [<head>...]

🎚️ Switches & options

Flag	What it does
`-n, --dry-run`	Show what would be pruned. Run this first. Always.
`-v, --verbose`	Print each object as it's pruned.
`--expire <time>`	Only prune objects older than `<time>`. Default: 2 weeks (`gc.pruneExpire`).
`--exclude-promisor-objects`	Don't prune objects from a promisor remote (partial clone). You want this if you partial-cloned.
`--progress`	Show a progress meter for big repos.
`git prune --expire=now`	⚠️ Bypasses the safety horizon. If reflogs aren't expired, you can still lose recoverable work.

💡 Use cases

After a filter-repo or filter-branch rewrite, to actually shrink the repo.
After deleting branches with sensitive data and expiring their reflogs.
Recovering disk space on a server that doesn't run gc regularly.
Almost never directly — git gc calls it for you with sane defaults.

🧪 Examples

See what would die

git prune --dry-run --verbose

Standard cleanup via gc (preferred)

git gc

Aggressive: prune everything unreachable, now

git reflog expire --expire-unreachable=now --all
git gc --prune=now

Partial clone — keep promisor objects

git prune --exclude-promisor-objects

🎓 Recommendations

Prefer git gc over git prune. gc packs first, then prunes — pruning unpacked-from objects you didn't pack first is wasted work.
The 2-week horizon exists for a reason: reflogs default to 90 days, so unreachable-but-recoverable objects survive gc for at least 14 days. Respect it.
Before rewriting history aggressively, snapshot the repo. Once prune --expire=now runs, the reflog won't save you.

🪤 Common pitfalls

git prune does NOT touch packed objects. To shrink those, you need git repack -ad (which gc does).
Running prune --expire=now after reflog expire --expire-unreachable=now is irreversible. If you got here by accident, there's no Ctrl+Z.
On partial clones, forgetting --exclude-promisor-objects can prune objects the remote expects you to have. Refetch country.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.