bup-margin(1)

💖 bup-margin(1) 💖

okay bestie, welcome to bup-margin — the little tool that goes "hey, how much room do we actually have before this whole dedup thing starts colliding?" 🦋

---

✨ NAME ✨

bup-margin — figure out your deduplication safety margin 💅

---

🌸 SYNOPSIS 🌸

bup margin [options...]

---

🎀 DESCRIPTION 🎀

so here's the vibe: bup margin goes through every single object in your bup repository and figures out the largest number of prefix bits shared between any two entries. that number is called n, and it's literally the longest subset of SHA-1 you could get away with using and still run into a collision between your object ids. 😭

for example, one system that got tested had a collection of 11 million objects (that's 70 GB, no cap), and bup margin returned 45. which means a 46-bit hash would be enough to dodge all collisions among that set of objects — each object in that repository could be uniquely identified by its first 46 bits. iconic. ✨

the number of bits needed seems to go up by about 1 or 2 for every doubling of the number of objects. and since SHA-1 hashes have 160 bits, that leaves a whole 115 bits of margin. 🫶 of course, because SHA-1 hashes are essentially random, it's theoretically possible to use many more bits with far fewer objects. so like, don't stress too hard.

if you're paranoid about the possibility of SHA-1 collisions (valid tbh), you can monitor your repository by running bup margin occasionally to see if you're getting dangerously close to 160 bits. 👑

---

💅 OPTIONS 💅

• --predict — guesses the offset into each index file where a particular object will appear, and reports the maximum deviation of the correct answer from the guess. potentially useful for tuning an interpolation search algorithm. tuning era fr fr 🔥
• --ignore-midx — don't use .midx files, use only .idx files. this is only really useful when used with --predict.

---

🌈 EXAMPLES 🌈

$ bup margin
Reading indexes: 100.00% (1612581/1612581), done.
40
40 matching prefix bits
1.94 bits per doubling
120 bits (61.86 doublings) remaining
4.19338e+18 times larger is possible

Everyone on earth could have 625878182 data sets
like yours, all in one repository, and we would
expect 1 object collision.

$ bup margin --predict
PackIdxList: using 1 index.
Reading indexes: 100.00% (1612581/1612581), done.
915 of 1612581 (0.057%)

---

🦋 SEE ALSO 🦋

• bup-midx(1)
• bup-save(1)

---

💜 BUP 💜

part of the bup(1) suite. family reunion energy 🫶

---

🌟 AUTHORS 🌟

Avery Pennarun <apenwarr@gmail.com>

---

and that's the whole page, bestie! 💖

okay so the lore: this is from Bup 0.34, dated 2026-09-01, and it's the bup-margin(1) manual page — a real one, from the General Commands Manual, no cap. go forth and check your margin, main character. 🎀✨