BTRFS-USAGE-REPORT(1)

💖 BTRFS-USAGE-REPORT 💖

okay bestie, so this is the manual page for btrfs-usage-report, which lives in section 1 of the Btrfs Usage Report manual. yes it's a real thing, yes it's iconic, let's get into it ✨

🌸 NAME 🌸

btrfs-usage-report — bestie, it shows you a detailed usage report about your btrfs filesystem. that's the whole job. no cap. 💅

🦋 SYNOPSIS 🦋

btrfs-usage-report [args] mountpoint

✨ DESCRIPTION ✨

so the btrfs-usage-report program shows a detailed report about how a btrfs filesystem is using the disk space it has. that's it. that's the vibe. 💖

okay but here's the thing, the filesystem you want info about needs to be online and mounted. and because the info it needs is pulled straight out of the btrfs kernel API, you have to run it as root. no way around it, sorry babe, it's giving sudo energy. 👑

now let's talk about why this tool even exists, because btrfs is a whole situation. in a btrfs filesystem, raw storage is shared between data of different types (System, MetaData and Data) and different profiles (like single, DUP, RAID1, etc). and also, one filesystem can have multiple block devices of different sizes attached. all of that together? absolutely confuses regular tools like df, which will already fail to show you how much free space you still have to add more data to the filesystem. df is not the moment. 😭

so here's what the report will show you:

• Physical disk space usage. at this level we can see how much disk space is allocated for specific combinations of type and profile. e.g. 1GiB of Data with profile RAID1 will show that two devices both store 1GiB of raw data, because it's duplicated. the way that math works is so real. 💅
• Virtual disk space usage. the btrfs virtual address space shows the amount of data we store, disregarding the storage profile. so if we store 1GiB of data using a RAID1 profile, then the virtual address space shows we have 1GiB of data, while the physical space usage will show up as 2GiB in total. iconic behaviour honestly. and heads up bestie — note that when using compression, the virtual address space counts compressed data instead of uncompressed data. 🫶
• Estimated free virtual space left for use. by extrapolating the current usage patterns, a prediction can be made that shows how much extra data can be added to the filesystem. these are the values you actually wish df would show you. these are the main character numbers. ⭐
• Unallocatable disk space, which is raw physical disk space that cannot be used, either because allocations in the filesystem are unbalanced, or because you've got different sizes of devices attached. additionally, it will show us if disk space can be reclaimed for use by using btrfs balance. and when you're converting between profiles, these values can quickly show you if the conversion to another profile can actually be completed or not. super useful, no notes. 🌈

🎀 OPTIONS 🎀

• -h, --help — shows the built-in help message and exits. that's it, she's simple, she's helpful, she ate. 💖

👑 SEE ALSO 👑

btrfs-space-calculator is a program that can calculate the amount of allocatable (and unallocatable) disk space based on a list of (maybe differently sized) block devices and target profiles to use. sister program, equally slay. 🦋

this program is an example of what can be done using the python-btrfs library. and bestie, listen — do not parse the output of this program, because it just displays data that is readily available when using functionality from this library. like, just use the library, i'm begging. 🙈

source and documentation on github: https://github.com/knorrie/python-btrfs ✨

🫶 okay that's the whole page! this was Btrfs Usage Report manual, dated 2018, and honestly? she's still serving. go check your filesystem, bestie, and remember: run it as root, don't parse the output, and stay hydrated. 💜🌸✨