1compsize(8)                          btrfs                         compsize(8)
2
3
4

NAME

6       compsize - calculate compression ratio of a set of files on btrfs
7

SYNOPSIS

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

DESCRIPTION

12       compsize  takes a list of files on a btrfs filesystem (recursing direc‐
13       tories) and measures used compression types and the effective  compres‐
14       sion ratio.
15
16       As  talking  about compression ratio for a partial extent doesn't quite
17       make any sense, every used extent is considered in its entirety.  Every
18       extent  is  also  counted exactly once, even if it's reflinked multiple
19       times.
20
21       The program gives a report similar to:
22       Processed 90319 files.
23       Type       Perc     Disk Usage   Uncompressed Referenced
24       TOTAL       79%      1.4G         1.8G         1.9G
25       none       100%      1.0G         1.0G         1.0G
26       lzo         53%      446M         833M         843M
27
28       The fields above are:
29
30       Type   compression algorithm
31
32       Perc   disk usage/uncompressed (compression ratio)
33
34       Disk Usage
35              blocks on the disk; this is what storing  these  files  actually
36              costs you (save for RAID considerations)
37
38       Uncompressed
39              uncompressed  extents; what you would need without compression -
40              includes deduplication savings and pinned extent waste
41
42       Referenced
43              apparent file sizes (sans holes); this  is  what  a  traditional
44              filesystem  that  supports  holes and efficient tail packing, or
45              tar -S, would need to store these files
46
47       Let's see this on an example: a file 128K big is  stored  as  a  single
48       extent  A  which  compressed  to  a single 4K page.  It then receives a
49       write of 32K at offset 32K, which also compressed to a single 4K  page,
50       stored as extent B.
51
52       The file now appears as:
53                +-------+-------+---------------+
54       extent A | used  | waste | used          |
55                +-------+-------+---------------+
56       extent B         | used  |
57                        +-------+
58
59       The  "waste" inside extent A can't be gotten rid until the whole extent
60       is rewritten (for example by defrag).  If compressed, the whole  extent
61       needs  to  be read every time that part of the file is being read, thus
62       the "waste" is still required.
63
64       In this case, we have: Disk Usage: 8KB, Uncompressed: 160K, Referenced:
65       128K.
66

OPTIONS

68       -b/--bytes
69              Show raw byte counts rather than human-friendly sizes.
70
71       -x/--one-file-system
72              Skip files and directories on different file systems.
73

SIGNALS

75       USR1   Displays partial data for files processed so far.
76

CAVEATS

78       Recently  written  files may show as not taking any space until they're
79       actually allocated and compressed; this happens once they're synced  or
80       on natural writeout, typically on the order of 30 seconds.
81
82       The ioctls used by this program require root.
83
84       Inline  extents  are considered to be always unique, even if they share
85       the same bytes on the disk.
86
87       This program doesn't currently support filesystems above 8TB on  32-bit
88       machines  but neither do other btrfs tools.
89
90
91
92btrfs                             2017-09-04                       compsize(8)