Overview

Btrfs is a great filesystem, but its userland tools are not very user-frienfly yet. As a long-time user, I've developed btrfs-list as a wrapper to make sense out of the btrfs sub list and btrfs qgroup show commands.

You need btrfs-list if either:

• You'd like to have a nice overview of your subvolumes/snapshots
• You've already used ZFS before and you're missing the zfs list command
• You're looking for exactly which snapshot to destroy to regain some space
• You're looking for a more accurate estimation of how much space is remaining on your FS

Basically it turns this: into this:

Prerequisites

• btrfs-progs v3.18 at least (Dec 2014)
• The quota feature enabled on your Btrfs filesystems (optional, to get space usage for subvolumes and snapshots)

Usage

Usage: btrfs-list [options] [mountpoint]

If no [mountpoint] is specified, display info for all btrfs filesystems.

  -h, --help                 display this message
  -d, --debug                enable debug output
      --color=WHEN           colorize the output; WHEN can be 'never', 'always',
                               or 'auto' (default, colorize if STDOUT is a term)
      --no-color             synonym of --color=never

  -s                         hide all snapshots
      --snap-min-used SIZE   hide snapshots taking less space than SIZE
      --snap-max-used SIZE   hide snapshots taking more space than SIZE

      --show-all             show all information for each item
      --show-gen             show generation of each item
      --show-cgen            show generation at creation of each item
      --show-id              show id of each item
      --show-uuid            show uuid of each item

SIZE can be a number (in bytes), or a number followed by k, M, G, T or P.

Examples

Display heavy snapshots

root@nas:~# btrfs-list --snap-min-used 4G --snap-only /tank
NAME                                                          TYPE     REFER      USED MOUNTPOINT
      backups/.snaps/skyline/20130213_231649_lastskyline    rosnap    22.52G    19.58G
      backups/.snaps/box/20171231_221207_monthly.12         rosnap    88.73G     4.96G
      backups/.snaps/box/20180130_221209_monthly.11         rosnap    91.25G     4.90G
      backups/.snaps/box/20180307_154215_monthly.10         rosnap    96.28G    10.72G
      backups/.snaps/box/20190120_193004_weekly.3           rosnap    56.45G     4.25G
      backups/.snaps/nasroot/20180122_091325_monthly.12     rosnap    34.65G    10.79G
      backups/.snaps/nasroot/20180221_092311_monthly.11     rosnap    31.96G     4.98G
      backups/.snaps/nasroot/20180323_092734_monthly.10     rosnap    33.69G     7.05G
      backups/.snaps/nasroot/20180820_205559_monthly.5      rosnap    31.74G     5.37G
      .syncthing-bkp                                        rosnap    40.48G     8.15G

Display verbose information

root@nas:~# btrfs-list --show-all /mnt/a
NAME                             ID     GEN    CGEN                                 UUID     TYPE     REFER      USED MOUNTPOINT
203be355                         -1       -       -                                    -       fs         -   134.09M (868.78M free)
   [main]                         5       -       -                                    -  mainvol    16.00k    16.00k
   sub1                         256      23       6 7e5e30e0-4e68-da46-aa38-381048b0a794   subvol    33.02M    16.00k /mnt/a/test
      sub1/.snap1               257       7       7 c8b1b7c9-26e0-b346-858f-a37d346ce8b6     snap    16.00k    16.00k
      sub1/.snap2               259       8       8 dbf3e766-0a47-d24b-914e-246cc24f6b6a     snap    10.02M    16.00k
      sub1/subsub1              260      29       9 f3dfc28f-84a4-6a43-8e2c-c5163d134e52     snap    16.02M    16.00k /mnt/a
         sub1/subsub1/.snapA1   263      12      12 728b929f-8c33-d541-806d-94871eaa75a6     snap    47.02M    31.02M
         sub1/subsub1/.snapA2   265      14      14 45281588-176e-7e4c-9d9b-79375cfcb6f3     snap    47.02M    16.00k
         subroot                266      15      15 66a0de92-f6c3-c441-8b18-1110b5b89a0e     snap    47.02M    16.00k
         sub1/subsub1/.snapA3   268      17      17 6e19b614-e6b6-a945-9ea6-1857329d8d06     snap    16.02M    16.00k
      sub1/.snap3               261      10      10 196f1987-161e-a644-b9f9-abcf406bdabd     snap    26.02M    16.00k
      sub1/.snap4               262      11      11 41c86ef5-09ec-2449-aa70-d963430c7b1b     snap    49.02M    23.02M
      sub1/.snap5               264      13      13 7c53673b-c078-834e-97f3-1e07a2a6cf77     snap    49.02M    16.00k
      sub1/.snap6               267      16      16 6bfd05d5-bc7e-5d40-aeda-81764c6c5b2b     snap    33.02M    16.00k
      snapq222                  269      22      21 12005af8-92b4-0646-a4fa-4ff1480797ee     snap    33.03M    32.00k
      snapmulti                 270      23      22 628a9b53-003c-fb40-be89-eee5bbbbeb42     snap    33.03M    32.00k