From 2fd02b1f5f50d499b8f19d0cc5e9bc9ed7e686cd Mon Sep 17 00:00:00 2001
From: Dimitri John Ledkov <xnox@ubuntu.com>
Date: Sat, 26 Jan 2019 00:37:47 +0000
Subject: New upstream release

---
 Documentation/btrfstune.asciidoc | 81 ++++++++++++++++++++++++++--------------
 1 file changed, 52 insertions(+), 29 deletions(-)

(limited to 'Documentation/btrfstune.asciidoc')

diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc
index 27100964..1d6bc98d 100644
--- a/Documentation/btrfstune.asciidoc
+++ b/Documentation/btrfstune.asciidoc
@@ -25,26 +25,29 @@ means.  Please refer to the 'FILESYSTEM FEATURES' in `btrfs`(5).
 
 OPTIONS
 -------
--S <0|1>::
-Enable seeding on a given device. Value 1 will enable seeding, 0 will disable it. +
-A seeding filesystem is forced to be mounted read-only. A new device can be added
-to the filesystem and will capture all writes keeping the seeding device intact.
 
--r::
-(since kernel: 3.7)
+-f::
+Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure
+that you are aware of the dangers.
+
+-m::
+(since kernel: 5.0)
 +
-Enable extended inode refs (hardlink limit per file in a directory is 65536),
-enabled by mkfs feature 'extref'.
+change fsid stored as 'metadata_uuid' to a randomly generated UUID,
+see also '-U'
 
--x::
-(since kernel: 3.10)
+-M <UUID>::
+(since kernel: 5.0)
 +
-Enable skinny metadata extent refs (more efficient representation of extents),
-enabled by mkfs feature 'skinny-metadata'.
+change fsid stored as 'metadata_uuid' to a given UUID, see also '-U'
 +
-All newly created extents will use the new representation. To completely switch
-the entire filesystem, run a full balance of the metadata. Please refer to
-`btrfs-balance`(8).
+The metadata_uuid is stored only in the superblock and is a backward
+incompatible change. The fsid in metadata blocks remains unchanged and
+is not overwritten, thus the whole operation is significantly faster than
+'-U'.
++
+The new metadata_uuid can be used for mount by UUID and is also used to
+identify devices of a multi-device filesystem.
 
 -n::
 (since kernel: 3.14)
@@ -52,33 +55,53 @@ the entire filesystem, run a full balance of the metadata. Please refer to
 Enable no-holes feature (more efficient representation of file holes), enabled
 by mkfs feature 'no-holes'.
 
--f::
-Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure
-that you are aware of the dangers.
+-r::
+(since kernel: 3.7)
++
+Enable extended inode refs (hardlink limit per file in a directory is 65536),
+enabled by mkfs feature 'extref'.
+
+-S <0|1>::
+Enable seeding on a given device. Value 1 will enable seeding, 0 will disable it. +
+A seeding filesystem is forced to be mounted read-only. A new device can be added
+to the filesystem and will capture all writes keeping the seeding device intact.
++
+WARNING: Clearing the seeding flag on a device may be dangerous.
+If a previously-seeding device is changed, all filesystems that used that
+device will become unmountable. Setting the seeding flag back will not fix
+that. +
+A valid usecase is 'seeding device as a base image'. Clear the seeding
+flag, update the filesystem and make it seeding again, provided that it's OK
+to throw away all filesystems built on top of the previous base.
 
 -u::
 Change fsid to a randomly generated UUID or continue previous fsid change
 operation in case it was interrupted.
 
 -U <UUID>::
-Change fsid to 'UUID'.
+Change fsid to 'UUID' in all metadata blocks.
 +
 The 'UUID' should be a 36 bytes string in `printf`(3) format
 '"%08x-%04x-%04x-%04x-%012x"'.
 If there is a previous unfinished fsid change, it will continue only if the
 'UUID' matches the unfinished one or if you use the option '-u'.
-
++
+All metadata blocks are rewritten, this may take some time, but the final
+filesystem compatibility is unaffected, unlike '-M'.
++
 WARNING: Cancelling or interrupting a UUID change operation will make the
-filesystem temporarily unmountable.  To fix it, rerun 'btrfstune -u' to restore
-the UUID and let it complete.
+filesystem temporarily unmountable.  To fix it, rerun 'btrfstune -u' and let
+it complete.
 
-WARNING: Clearing the seeding flag on a device may be dangerous.
-If a previously-seeding device is changed, all filesystems that used that
-device will become unmountable. Setting the seeding flag back will not fix
-that. +
-A valid usecase is 'seeding device as a base image'. Clear the seeding
-flag, update the filesystem and make it seeding again, provided that it's OK
-to throw away all filesystems built on top of the previous base.
+-x::
+(since kernel: 3.10)
++
+Enable skinny metadata extent refs (more efficient representation of extents),
+enabled by mkfs feature 'skinny-metadata'.
++
+All newly created extents will use the new representation. To completely switch
+the entire filesystem, run a full balance of the metadata. Please refer to
+`btrfs-balance`(8).
 
 EXIT STATUS
 -----------
-- 
cgit v1.2.3

