disk-usage

name

disk-usage

description

Analyse disk fill on a Linux desktop and surface where the space actually went. BTRFS-aware — reports real free space (`btrfs filesystem usage`), unallocated vs allocated, snapshot weight (`btrfs subvolume list` + size estimates), and compression ratio (`compsize`). For ext4/xfs/zfs, falls back to `df -hT` + `du`-based hot-spot detection. Triggers on "where did my disk space go", "check disk usage", "btrfs free space", "df is lying".

Disk Usage

df lies on BTRFS — it shows allocated space, not free space. This skill gives the truthful picture per filesystem and points at the biggest space sinks.

Steps

1. Enumerate filesystems. findmnt -t btrfs,ext4,xfs,zfs,f2fs -no SOURCE,TARGET,FSTYPE,OPTIONS — one row per real FS. Skip pseudo-FS.
2. Per FS, report:
   • df -hT <mount> — the naive view (note this for BTRFS).
   • BTRFS:
     • sudo btrfs filesystem usage <mount> — the truthful view: Device size / allocated / unallocated, Data/Metadata/System breakdown.
     • sudo btrfs filesystem df <mount> — used vs free per profile.
     • sudo btrfs subvolume list -t <mount> — list subvolumes; flag snapshots (typically under @snapshots/, .snapshots/, or named *-snapshot-*).
     • If compsize is installed: sudo compsize <mount> for actual compression ratio. Otherwise suggest sudo apt install compsize.
     • If usage > 80% of allocated and unallocated is small, suggest sudo btrfs balance start -dusage=50 <mount> (with a warning that it's I/O heavy).
   • ZFS: zpool list, zfs list -o name,used,avail,refer,mountpoint, zfs list -t snapshot.
   • ext4 / xfs: df -hT is honest. Move on to hot-spot scan.
3. Hot-spot scan for the FS the user cares most about (default: the one with least free):
   • sudo du -h --max-depth=1 -x <mount> 2>/dev/null | sort -hr | head -20 for top-level offenders.
   • For each offender > a threshold (default 5 GiB), recurse one level: du -h --max-depth=1 -x <path> | sort -hr | head -10.
   • Identify common patterns: ~/.cache, ~/snap, ~/.local/share/Trash, /var/log, /var/cache/apt, /var/lib/docker, /var/lib/flatpak, ~/Downloads.
4. Snapshot weight estimate (BTRFS). Use sudo btrfs filesystem du -s <snapshot-path> per snapshot — note this gives shared/exclusive bytes; the exclusive column is what you'd reclaim by deleting that snapshot.

Output

A short report leading with the truthful free-space number, then a ranked list of "biggest things that aren't sacred":

Filesystem: /  (BTRFS)
  Device size: 460 GiB
  Real free:   38 GiB  (df claims 92 GiB — see note)
  Note: BTRFS allocated 422 GiB, of which 384 GiB is used. df shows unallocated as "free".
  Compression ratio: 1.42x (compsize)

Snapshots: 27 — top weights (exclusive bytes):
  /@snapshots/142   8.1 GiB
  /@snapshots/138   6.4 GiB
  ...

Hot-spots in $HOME:
  ~/.cache             14 GiB
  ~/.local/share/Trash  9 GiB
  ~/Downloads           7 GiB
  ~/.cache/yarn         3 GiB

Suggested next steps:
  - Prune old snapshots (snap-it or snapper) — recoverable: ~30 GiB
  - Clear ~/.local/share/Trash — recoverable: 9 GiB
  - find-duplicates on ~/Downloads
  - prune-dev-clutter for stale venvs / node_modules

Notes

• Don't run btrfs balance automatically. Suggest only.
• Don't delete snapshots — that's snap-it or snapper's job; this skill only measures.
• du on / will hit slow paths (FUSE mounts, network FS) — -x keeps it on one filesystem.