compsize(8)

✨ compsize — the btrfs compression-ratio calculator, bestie edition ✨

okay so you know how btrfs does compression and you're like "am I actually saving space or am I just delulu?" — this is the tool that tells you. it's compsize from the btrfs fam, and it is literally the vibe check your filesystem needed. 💅

---

🌸 NAME 🌸

compsize — calculate compression ratio of a set of files on btrfs 🦋

---

✨ SYNOPSIS ✨

compsize file-or-dir [ file-or-dir ... ]

---

💖 DESCRIPTION 💖

so compsize takes a list of files on a btrfs filesystem (and yes, it recurses into directories, she's thorough like that 🧚) and measures which compression types are actually being used and what the effective compression ratio is. but wait, there's more — besides compression, compsize also shows you the effect of reflinks (cp --reflink, snapshots, deduplication) and certain types of btrfs waste. she's giving full picture energy. 👑

the program gives a report similar to:

Processed 90319 files.
Type       Perc     Disk Usage   Uncompressed Referenced
TOTAL       79%      1.4G         1.8G         1.9G
none       100%      1.0G         1.0G         1.0G
lzo         53%      446M         833M         843M

and the fields above are, bestie, let me break it down:

Type — compression algorithm 🌈

Perc — disk usage/uncompressed (aka the compression ratio)

Disk Usage — blocks on the disk; this is what storing these files actually costs you (save for RAID considerations) 💸

Uncompressed — uncompressed extents; what you would need without compression — and this includes deduplication savings and pinned extent waste

Referenced — apparent file sizes (sans holes); this is what a traditional filesystem that supports holes and efficient tail packing, or tar -S, would need to store these files

---

🎀 let's see this on an example 🎀

a file 128K big is stored as a single extent A which compressed to a single 4K page. it then receives a write of 32K at offset 32K, which also compressed to a single 4K page, stored as extent B.

the file now appears as:

                +-------+-------+---------------+
       extent A | used  | waste | used          |
                +-------+-------+---------------+
       extent B         | used  |
                        +-------+

the "waste" inside extent A can't be gotten rid until the whole extent is rewritten (for example by defrag). and if compressed, the whole extent needs to be read every time that part of the file is being read, thus the "waste" is still required. 😭 it's giving trapped.

in this case, we have: Disk Usage: 8KB, Uncompressed: 160K, Referenced: 128K. math ate. 💅

---

🌟 OPTIONS 🌟

• -b, --bytes — show raw byte counts rather than human-friendly sizes. no cozy 1.4G vibes, just the raw numbers, periodt. 🔢
• -x, --one-file-system — skip files and directories on different file systems. stay in your lane, literally. 🚧

---

🚨 SIGNALS 🚨

• USR1 — displays partial data for files processed so far. so if it's taking forever you can just poke it and get the tea early. 👀

---

💀 CAVEATS 💀

recently written files may show as not taking any space until they're actually allocated and compressed; this happens once they're synced or on natural writeout, typically on the order of 30 seconds. so like, give it a sec, she's buffering. 🫶

the ioctls used by this program require root. no root, no numbers. that's just the rules. 🔥

inline extents are considered to be always unique, even if they share the same bytes on the disk. yes even then. 🙈

this program doesn't currently support filesystems above 8TB on 32-bit machines — but neither do other btrfs tools, so you're in good company. 😌

---

and that's the whole page, bestie!! this gem lives in the btrfs corner of the manual world and it's dated 2017-09-04, still iconic, still serving. go compress something and check your ratio, ily 🎀💜🦋