path: root/Documentation
diff options
authorOmar Sandoval <>2016-11-14 10:43:23 -0800
committerDavid Sterba <>2016-11-23 11:07:05 +0100
commita064f24e2ebeeaeea23d8dafcea7c77dc3d3333d (patch)
tree74096c8094cd136d3bb21640f29c32a59639dc2a /Documentation
parent87895ef4da2819b0b3ffde6bcd45abf7b2533b7f (diff)
btrfs-progs: document space_cache=v2 more thoroughly
Signed-off-by: Omar Sandoval <> Signed-off-by: David Sterba <>
Diffstat (limited to 'Documentation')
1 files changed, 25 insertions, 18 deletions
diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
index d12b0591..3b003d3d 100644
--- a/Documentation/btrfs-man5.asciidoc
+++ b/Documentation/btrfs-man5.asciidoc
@@ -319,25 +319,32 @@ May be resumed with *btrfs balance resume* or the paused state can be removed
by *btrfs balance cancel*. The default behaviour is to start interrutpd balance.
-('nospace_cache' since: 3.2, 'space_cache=v2' since 4.5, default: on)
-Options to control the free space cache. This affects performance as searching
-for new free blocks could take longer if the space cache is not enabled. On the
-other hand, managing the space cache consumes some resources. It can be
-disabled without clearing at mount time.
-There are two implementations of how the space is tracked. The safe default is
-'v1'. On large filesystems (many-terabytes) and certain workloads the 'v1'
-performance may degrade. This problem is addressed by 'v2', that is based on
-b-trees, sometimes referred to as 'free-space-tree'.
-'Compatibility notes:'
-* the 'v2' has to be enabled manually at mount time, once
-* kernel without 'v2' support will be able to mount the filesystem in read-only mode
-* 'v2' can be removed by mounting with 'clear_cache'
+('nospace_cache' since: 3.2, 'space_cache=v1' and 'space_cache=v2' since 4.5, default: 'space_cache=v1')
+Options to control the free space cache. The free space cache greatly improves
+performance when reading block group free space into memory. However, managing
+the space cache consumes some resources, including a small amount of disk
+There are two implementations of the free space cache. The original
+implementation, 'v1', is the safe default. The 'v1' space cache can be disabled
+at mount time with 'nospace_cache' without clearing.
+On very large filesystems (many terabytes) and certain workloads, the
+performance of the 'v1' space cache may degrade drastically. The 'v2'
+implementation, which adds a new B-tree called the free space tree, addresses
+this issue. Once enabled, the 'v2' space cache will always be used and cannot
+be disabled unless it is cleared. Use 'clear_cache,space_cache=v1' or
+'clear_cache,nospace_cache' to do so. If 'v2' is enabled, kernels without 'v2'
+support will only be able to mount the filesystem in read-only mode. The
+`btrfs(8)` command currently only has read-only support for 'v2'. A read-write
+command may be run on a 'v2' filesystem by clearing the cache, running the
+command, and then remounting with 'space_cache=v2'.
+If a version is not explicitly specified, the default implementation will be
+chosen, which is 'v1' as of 4.9.