mirror of
https://github.com/speed47/btrfs-list
synced 2024-10-02 22:03:31 +00:00
update README
This commit is contained in:
parent
4f286276f9
commit
fcf4a98f85
147
README.md
147
README.md
|
@ -4,10 +4,11 @@ Btrfs is a great filesystem, but its userland tools are not very user-frienfly y
|
||||||
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.
|
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 need `btrfs-list` if either:
|
||||||
- You'd like to have a nice overview of your subvolumes/snapshots
|
- You'd like to have a nice tree-style overview of your subvolumes/snapshots
|
||||||
- You've already used ZFS before and you're missing the _zfs list_ command
|
- 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 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 for all btrfs supported data profiles, as corner cases of raid1/raid10 are not handled well by _btrfs-progs_, and raid5/raid6 are not implemented at all yet
|
- You're using `btrfs-progs` < v5.7 and you're looking for a more accurate estimation of how much space is remaining on your FS for all btrfs supported data profiles,
|
||||||
|
as corner cases of raid1/raid10 are not handled well by older versions of `btrfs-progs`, and raid5/raid6 were not implemented at all
|
||||||
|
|
||||||
Basically it turns this:
|
Basically it turns this:
|
||||||
![btrfs_sub_list](https://user-images.githubusercontent.com/218502/53362053-99564e00-3939-11e9-9072-1d9ef617971f.PNG)
|
![btrfs_sub_list](https://user-images.githubusercontent.com/218502/53362053-99564e00-3939-11e9-9072-1d9ef617971f.PNG)
|
||||||
|
@ -73,7 +74,94 @@ SIZE can be a number (in bytes), or a number followed by k, M, G, T or P.
|
||||||
|
|
||||||
# Examples
|
# Examples
|
||||||
|
|
||||||
## Display heavy snapshots
|
## Quick view
|
||||||
|
|
||||||
|
```
|
||||||
|
root@nas:~# btrfs-list /git
|
||||||
|
NAME TYPE REFER EXCL MOUNTPOINT
|
||||||
|
git fs - 58.96G (single, 17.27G free)
|
||||||
|
[main] mainvol 60.61G 292.00k /git
|
||||||
|
.beeshome subvol 56.64M 56.64M
|
||||||
|
.snaps/20220103_005415_daily.0 rosnap 60.54G 144.00k
|
||||||
|
.snaps/20220101_004815_daily.2 rosnap 60.42G 160.00k
|
||||||
|
.snaps/20211229_004815_daily.5 rosnap 60.42G 160.00k
|
||||||
|
.snaps/20220102_005203_daily.1 rosnap 60.42G 160.00k
|
||||||
|
.snaps/20220103_114214_hourly.6 rosnap 60.54G 144.00k
|
||||||
|
.snaps/20220103_154814_hourly.2 rosnap 60.61G 144.00k
|
||||||
|
.snaps/20220103_175114_hourly.0 rosnap 60.61G 144.00k
|
||||||
|
.snaps/20211230_004815_daily.4 rosnap 60.42G 160.00k
|
||||||
|
.snaps/20211231_004815_daily.3 rosnap 60.42G 160.00k
|
||||||
|
.snaps/20220103_144814_hourly.3 rosnap 60.61G 144.00k
|
||||||
|
.snaps/20220103_164815_hourly.1 rosnap 60.61G 144.00k
|
||||||
|
.snaps/20220103_124215_hourly.5 rosnap 60.54G 2.23M
|
||||||
|
.snaps/20220103_134556_hourly.4 rosnap 60.60G 480.00k
|
||||||
|
.snaps/20220103_104215_hourly.7 rosnap 60.54G 144.00k
|
||||||
|
```
|
||||||
|
|
||||||
|
## Detailed view
|
||||||
|
|
||||||
|
```
|
||||||
|
root@nas:/mnt/b# btrfs-list -qad .
|
||||||
|
NAME ID PARENT TOPLVL GEN CGEN UUID PARENTUUID RCVD_UUID OTIME TYPE EXCL MOUNTPOINT
|
||||||
|
7cb8325f - - - - - - - - - fs 157.00M (raid5, 3.59G free, 2.74G unallocatable)
|
||||||
|
[main] 5 - - - - - - - - mainvol - /mnt/b
|
||||||
|
sub1 258 5 5 21 8 ae9c..6cae - - - subvol -
|
||||||
|
sub1/.snap1 259 258 258 9 9 2d50..2094 ae9c..6cae - 2022-01-03 18:39:48 snap -
|
||||||
|
sub1/.snap2 260 258 258 10 10 a2e9..1431 ae9c..6cae - 2022-01-03 18:39:48 snap -
|
||||||
|
sub1/.snap3 270 258 258 20 20 b054..6ce2 ae9c..6cae - 2022-01-03 18:41:26 snap -
|
||||||
|
sub1/.snap4 271 258 258 21 21 ae07..cc69 ae9c..6cae - 2022-01-03 18:41:27 snap -
|
||||||
|
sub1/subsub1 261 258 258 14 11 bdf1..e7fe - - - subvol -
|
||||||
|
sub1/subsub1/.snapA1 262 261 261 12 12 ab9b..e6df bdf1..e7fe - 2022-01-03 18:40:09 snap -
|
||||||
|
sub1/subsub1/.snapA2 263 261 261 13 13 407c..1a14 bdf1..e7fe - 2022-01-03 18:40:09 snap -
|
||||||
|
sub2 265 5 5 19 15 bc35..8104 - - - subvol -
|
||||||
|
sub3 266 5 5 17 16 eb52..da06 - - - subvol -
|
||||||
|
sub3/subsub3 267 266 266 32 17 eb81..00af - - - subvol -
|
||||||
|
sub3-snaps/.snapK 280 279 279 30 30 41b9..442a eb81..00af - 2022-01-03 18:43:25 snap -
|
||||||
|
sub3-snaps/.snapL 281 279 279 31 31 3308..f953 eb81..00af - 2022-01-03 18:43:25 snap -
|
||||||
|
sub2/subsub2 268 265 265 28 18 2189..08b4 - - - subvol -
|
||||||
|
sub2/subsub2/.snapB 269 268 268 19 19 259d..0afd 2189..08b4 - 2022-01-03 18:41:15 snap -
|
||||||
|
sub2/subsub2/.snapC 272 268 268 24 22 8ae4..1313 2189..08b4 - 2022-01-03 18:41:49 snap -
|
||||||
|
sub2/subsub2/.snapB-backup 294 268 268 24 24 fe27..2169 259d..0afd - 2022-01-03 18:42:05 snap -
|
||||||
|
sub2/subsub2/.snapC-backup 274 268 268 24 24 da86..1964 8ae4..1313 - 2022-01-03 18:42:03 snap -
|
||||||
|
sub2/subsub2/.snapD 273 268 268 23 23 713f..6a28 2189..08b4 - 2022-01-03 18:41:50 snap -
|
||||||
|
sub2-snaps/.snapX 276 275 275 26 26 97ef..7187 2189..08b4 - 2022-01-03 18:43:04 snap -
|
||||||
|
sub2-snaps/.snapZ 278 275 275 28 28 4c08..f7fb 2189..08b4 - 2022-01-03 18:43:06 snap -
|
||||||
|
sub2-snaps 275 5 5 28 25 3ce4..2ae3 - - - subvol -
|
||||||
|
sub3-snaps 279 5 5 32 29 05c9..0620 - - - subvol -
|
||||||
|
sub4-snaps 284 5 5 37 34 2366..b451 - - - subvol -
|
||||||
|
(deleted) - - - - - 05eb..d578 - - - deleted -
|
||||||
|
sub4-snaps/sub4-bkp1 285 284 284 35 35 0134..77cb 05eb..d578 - 2022-01-03 18:45:11 snap -
|
||||||
|
sub4-snaps/sub4-bkp2 286 284 284 36 36 587b..e3e0 05eb..d578 - 2022-01-03 18:45:11 snap -
|
||||||
|
sub4-snaps/sub4-bkp3 287 284 284 37 37 55eb..e32e 05eb..d578 - 2022-01-03 18:45:12 snap -
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that the hierarchy here is the hierarchy between the subvolumes and snapshots, not the folder hierarchy.
|
||||||
|
This is why for example `sub3-snaps/.snapK` is under `sub3/subsub3`, because it is a snapshot of this subvolume,
|
||||||
|
even if in the folder hierarchy, it is under `sub3-snaps`.
|
||||||
|
|
||||||
|
Same goes for `.snapD` and `.snapX`, these are at a different spot in the folder hierarchy, but both are snapshots
|
||||||
|
of the `sub2/subsub2` subvolume, hence are placed under it.
|
||||||
|
|
||||||
|
We also have 3 snapshots of a `(deleted)` subvolume, these ghosts subvolumes are shown with the option `-d`.
|
||||||
|
|
||||||
|
## View free space of all btrfs filesystems at a glance
|
||||||
|
|
||||||
|
```
|
||||||
|
root@nas:/tmp/md5# btrfs-list -f
|
||||||
|
NAME TYPE EXCL MOUNTPOINT
|
||||||
|
var fs 18.09G (single, 5.62G free)
|
||||||
|
root fs 950.39M (single, 36.61M free)
|
||||||
|
newtank fs 15.61T (raid1, 764.30G free)
|
||||||
|
git fs 58.96G (single, 17.27G free)
|
||||||
|
opt fs 1.11G (single, 668.23M free)
|
||||||
|
incoming fs 26.18T (single, 1.07T free)
|
||||||
|
7cb8325f fs 157.00M (raid5, 3.59G free, 2.74G unallocatable)
|
||||||
|
home fs 13.64G (single, 5.99G free)
|
||||||
|
slash fs 19.80G (single, 11.70G free)
|
||||||
|
varlog fs 12.26G (single, 3.96G free)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Display heavy snapshots only
|
||||||
|
|
||||||
```
|
```
|
||||||
root@nas:~# btrfs-list --snap-min-excl 4G --snap-only /tank
|
root@nas:~# btrfs-list --snap-min-excl 4G --snap-only /tank
|
||||||
|
@ -90,54 +178,11 @@ NAME TYPE REFER
|
||||||
.syncthing-bkp rosnap 40.48G 8.15G
|
.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 EXCL 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
|
|
||||||
```
|
|
||||||
|
|
||||||
## Get accurate free space amount
|
## Get accurate free space amount
|
||||||
|
|
||||||
For some configurations, `btrfs filesystem usage` *Free (estimated)* section is misleading, for example in a 5-devices RAID1 setup with 4 devices of 133M and 1 device of 500M:
|
Note: this is fixed with recent versions of `btrfs-progs` (v5.7 onwards), but we'll keep this feature to continue
|
||||||
|
supporting older releases of `btrfs-progs` if for some reason you're stuck with older versions.
|
||||||
|
|
||||||
```
|
For RAID5/6 setups, old versions of `btrfs filesystem usage` always display 0 bytes in the *Free (estimated)* section,
|
||||||
root@nas:~# btrfs-list /mnt/a
|
and you have no way to know the free space of your filesystem. `btrfs-list` handles this transparently by doing
|
||||||
NAME TYPE REFER EXCL MOUNTPOINT
|
the calculations needed to report the proper amount of free space, even in RAID5/6 setups.
|
||||||
8c4ca5e5 fs - 0.00 (456.44M free) (418.00M realfree)
|
|
||||||
[main] mainvol 16.00k 16.00k /mnt/a
|
|
||||||
```
|
|
||||||
|
|
||||||
The *free* amount is reported by `btrfs filesystem usage`, the *realfree* is the adjusted amount by `btrfs-list`. Let's verify that we got it right:
|
|
||||||
|
|
||||||
```
|
|
||||||
root@nas:~# dd if=/dev/urandom of=/mnt/a/big
|
|
||||||
dd: writing to '/mnt/a/big': No space left on device
|
|
||||||
853114+0 records in
|
|
||||||
853113+0 records out
|
|
||||||
436793856 bytes (437 MB, 417 MiB) copied, 3.55206 s, 123 MB/s
|
|
||||||
|
|
||||||
root@nas:~# ls -lh /mnt/a/big
|
|
||||||
-rw-r--r-- 1 root root 417M Mar 2 19:31 /mnt/a/big
|
|
||||||
|
|
||||||
root@nas:~# btrfs-list /mnt/a
|
|
||||||
NAME TYPE REFER EXCL MOUNTPOINT
|
|
||||||
8c4ca5e5 fs - 416.56M (39.88M free) (320.00k realfree)
|
|
||||||
[main] mainvol 416.58M 416.58M /mnt/a
|
|
||||||
```
|
|
||||||
|
|
|
@ -3,7 +3,7 @@
|
||||||
#
|
#
|
||||||
# SPDX-License-Identifier: GPL-2.0-only
|
# SPDX-License-Identifier: GPL-2.0-only
|
||||||
#
|
#
|
||||||
# btrfs-list: a wrapper to btrfs-progs to show a nice overview of your btrfs subvolumes and snapshots, a la 'zfs list'
|
# btrfs-list: a wrapper to btrfs-progs to show a nice tree-style overview of your btrfs subvolumes and snapshots, a la 'zfs list'
|
||||||
#
|
#
|
||||||
# Check for the latest version at:
|
# Check for the latest version at:
|
||||||
# https://github.com/speed47/btrfs-list
|
# https://github.com/speed47/btrfs-list
|
||||||
|
|
Loading…
Reference in a new issue