bup-fsck(1)

💖 bup-fsck — verify or repair a bup repository 💖

okay bestie, welcome to bup-fsck, aka the manual to bup fsck (same thing, one's the page one's the command, don't think about it too hard ✨). it lives in the bup suite and it's basically your repo's personal hype-checker — it looks at your data and goes "girl… is this ok?" so you don't find out the hard way. let's GO 🫶

---

✨ SYNOPSIS ✨

bup fsck [-r] [-g] [-v] [--quick] [-j jobs] [--par2-ok] [--disable-par2]
[packfile...]

---

🎀 DESCRIPTION 🎀

so when you hand it packfiles (and btw they must end in .pack, that's the rule 💅), the pack-related operations get limited to just those files. no packfiles given? then it considers every single packfile in the current repository, all of them, the whole squad.

rn, bup fsck checks the data in the repository for corruption. more specifically, it checks the integrity of the data packfiles and their corresponding indexes to make sure they haven't changed since they were written. what it does not do is check higher level concerns like connectivity (missing objects) — like, whether all the data referred to by a save actually exists in the repository. for some of those higher level checks, go look at bup-validate-object-links(1) and bup-validate-refs(1). the way i'd put it: bup fsck's whole thing is detecting and potentially repairing file corruption, while those higher level problems are more likely to be caused by bugs (hopefully rarer ones 🙏).

when it's checking packfiles and indexes, right now fsck will normally rely on git-verify-pack(1). but with --quick (more on that below), bup will just check the index and packfile checksums itself. lowkey efficient.

to allow repairs, fsck has to be asked via --generate to generate par2(1) "recovery blocks" (if you have it installed 👀). these blocks let you recover from damage affecting up to 5% of your .pack files. iconic tbh.

here's the tea on why this matters. in a normal backup system, damaged blocks are less important, because there tends to be enough data duplicated between backup sets that a single damaged backup set is non-critical. in a deduplicating backup system like bup, however, no block is ever stored more than once, even if it is used in every single backup. so if that block were to be unrecoverable, all your backup sets would be damaged at once 😭. thus, it's important to be able to verify the integrity of your backups and recover from disk errors if they occur. periodt.

when attempting to --repair, bup will exit with status 1 if and only if repairs were needed and were successful, and there were no other errors.

⚠️ WARNING: bup fsck obviously cannot recover from a complete disk failure. if your backups are important, you need to carefully consider redundancy (such as using RAID for multi-disk redundancy, or making off-site backups for site redundancy). no cap, think about this one.

when asked to examine all packfiles (i.e. when no packfiles are specified), fsck will report any files that appear to be related to a pack file that no longer exists 👻. previous versions of bup gc can cause this to happen because they did not remove all of the related files when removing a pack file.

---

🔥 OPTIONS 🔥

• -r, --repair — attempt to repair any damaged packs using existing recovery blocks. (requires par2(1).)
• -g, --generate — generate recovery blocks for any packs that don't already have them. (requires par2(1).)
• -v, --verbose — increase verbosity (can be used more than once, pile it on 💅).
• --quick — don't run a full git verify-pack on each pack file; instead just check the final checksum. this can cause a significant speedup with no obvious decrease in reliability ✨. however, you may want to avoid this option if you're paranoid. has no effect on packs that already have recovery information.
• -j, --jobs=numjobs — maximum number of pack verifications to run at a time. the optimal value for this option depends how fast your CPU can verify packs vs. your disk throughput. if you run too many jobs at once, your disk will get saturated by seeking back and forth between files and performance will actually decrease — even if numjobs is less than the number of CPU cores on your system 💀. you can experiment with this option to find the optimal value.
• --par2-ok — immediately return 0 if par2(1) is installed and working, or 1 otherwise. do not actually check anything. it's just a vibe check on par2 itself, that's all.
• --disable-par2 — pretend that par2(1) is not installed, and ignore all recovery blocks. gaslighting, but make it config.

---

🌈 EXAMPLES 🌈

# generate recovery blocks for all packs that don't
# have them
bup fsck -g

# generate recovery blocks for a particular pack
bup fsck -g ~/.bup/objects/pack/153a1420cb1c8*.pack

# check all packs for correctness (can be very slow!)
bup fsck

# check all packs for correctness and recover any
# damaged ones
bup fsck -r

# check a particular pack for correctness and recover
# it if damaged
bup fsck -r ~/.bup/objects/pack/153a1420cb1c8*.pack

# check if recovery blocks are available on this system
if bup fsck --par2-ok; then
    echo "par2 is ok"
fi

---

⭐ EXIT STATUS ⭐

exits with 1 if --repair was requested, needed, successful, and there were no other errors. otherwise exits with 0 if there were no errors, and a value other than zero or one for errors. yes you read that right, main character exit codes only 👑

---

👀 SEE ALSO 👀

bup-damage(1), fsck(1), git-fsck(1), bup-validate-object-links(1), and bup-validate-refs(1)

---

🧚 BUP 🧚

part of the bup(1) suite. the whole little family 🫶

---

💜 AUTHORS 💜

Avery Pennarun apenwarr@gmail.com

---

Bup 0.34 · 2026-09-01 — mwah, that's the version and the date, go forth and verify your packs bestie 💖✨🎀