bup-gc(1)

💖 bup-gc — remove unreferenced, unneeded data 💖

okay bestie, this is a page from the bup(1) manual — specifically bup-gc(1), the one that takes out the trash. let's get into it 🗑️✨

---

🌸 SYNOPSIS 🌸

bup gc [-#|--verbose] <branch|save...>

---

🦋 DESCRIPTION 🦋

bup gc removes — like, permanently deletes, no undo, no take-backs — the unreachable data from your repository. this stuff is also called garbage, and it's whatever isn't referred to directly or indirectly by the current set of branches (those are your backup sets, iykyk) and tags. slay, right?

but — and this is the important part, so listen — because of deduplication, deleting a save and then running the garbage collector might or might not actually delete anything, and it might or might not reclaim any space. it's giving "we'll see" 😭

with the current, probabilistic implementation, some fraction of the unreachable data may be retained. in exchange, the garbage collection should need less RAM than some more precise approaches would need. so like. you win some, you lose some.

typically you'd run the garbage collector after you've run bup rm a bunch of times. that's the whole vibe.

⚠️ WARNING: this is one of the few bup commands that modifies your archive in intentionally destructive ways. (!!!!) that said, if you try to join or restore the data you still care about after a gc and it works, that's a pretty encouraging sign the commands did their job right. the dev/compare-trees command in the source tree can help you test before/after results. 💅

so how does it work? the collection proceeds by rewriting packfiles to remove unreachable objects, and the new packfiles will respect pack.packSizeLimit — that's documented in bup-config(5). each new packfile will combine content from any number of existing packfiles. iconic.

and when an existing packfile gets removed, any affiliated files (like .idx, .par2, etc.) should also be removed. good news tho: .par2 files can be reestablished by bup-fsck(1). 🫶

---

✨ OPTIONS ✨

• --threshold=N — only rewrite a packfile if it's over N percent garbage and contains no unreachable trees or commits. if the packfile does contain unreachable trees or commits, it gets rewritten regardless, no matter what the threshold says. the default threshold is 10%.
• -v, --verbose — turn up the verbosity. and yes bestie, you can give it more than once. 🔥
• -#, --compress=# — set the compression level to #, which is a value from 0-9, where 9 is the highest compression and 0 is no compression at all. defaults to a configured pack.compression or core.compression, or 1 (fast, loose compression). this applies to any rewritten packfiles.
• --ignore-missing — report missing objects, but don't stop the collection. like, we're noting it, but we're not making it a whole thing.

---

💀 EXIT STATUS 💀

the exit status will be nonzero if there were any errors. and fyi, hitting any missing object counts as an error. so. yeah.

---

🌈 EXAMPLES 🌈

# Remove all saves of "home" (remove the branch).
$ bup rm home

# Remove two saves from the archives branch.
$ bup rm archives/2025-01-01-030405 archives/2025-10-04-134117

# Remove most of the otherwise unreferenced data.
$ bup gc

---

👑 SEE ALSO 👑

bup-rm(1) and bup-fsck(1) — go read those next, bestie, they're the whole supporting cast.

---

🧚 BUP 🧚

part of the bup(1) suite. the family. the collective. 💜

---

🎀 AUTHORS 🎀

Rob Browning rlb@defaultvalue.org

---

okay that's the whole page!! tysm for reading, mwah 🍓

— from Bup 0.34, dated 2026-09-01, and it lives in section bup-gc(1). periodt. 💅