btrfs-progs: docs: enhance the manual page for convert

Signed-off-by: David Sterba <dsterba@suse.com>

1 files changed, 62 insertions, 23 deletions

diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc
index 09510fa6..ca3417f4 100644
--- a/Documentation/btrfs-convert.asciidoc
+++ b/Documentation/btrfs-convert.asciidoc
@@ -3,7 +3,7 @@ btrfs-convert(8)
 
 NAME
 ----
-btrfs-convert - convert from ext2/3/4 filesystem to btrfs or rollback
+btrfs-convert - convert from ext2/3/4 filesystem to btrfs
 
 SYNOPSIS
 --------
@@ -11,42 +11,82 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-*btrfs-convert* is used to convert existed ext2/3/4 to btrfs filesystem,
-and the original filesystem image is accessible as from separate subvolume
-named 'ext2_saved' as file image.
+*btrfs-convert* is used to convert existing ext2/3/4 filesystem image to a
+btrfs filesystem in-place.  The original filesystem image is accessible
+subvolume named 'ext2_saved' as file 'image'.
 
-WARNING: If one hopes to rollback to ext2/3/4, they should not execute
-*btrfs balance* command on converted btrfs, since it will change the extent
-layout and make *btrfs-convert* unable to rollback.
+WARNING: If you are going to perform rollback to ext2/3/4, you should not
+execute *btrfs balance* command on the converted filesystem. This will change
+the extent layout and make *btrfs-convert* unable to rollback.
 
-NOTE: If one is satisfied with converted btrfs, and not longer wants to
-rollback to ext2/3/4, it is highly recommended to remove 'ext2_saved' subvolume
-and execute *btrfs filesystem defragment* and *btrfs balance* command on the
-converted btrfs.
+The conversion utilizes free space of the original filesystem. The exact
+estimate of the required space cannot be foretold. The final btrfs metadata
+might occupy several gigabytes on a hundreds-gigabyte filesystem.
+
+If you decide not to rollback anymore, it is recommended to perform a few more
+steps to transform the btrfs filesystem to a more compact layout. The
+conversion inherits the original data block fragmentation and the metadata
+blocks are bound to the original free space layout.
+
+**REMOVE THE ORIGINAL FILESYSTEM METADATA**
+
+By removing the 'ext2_saved' subvolume, all metadata of the original filesystem
+will be removed:
+
+   # btrfs subvolume delete /mnt/ext2_saved
+
+At this point it's not possible to do rollback. The filesystem is usable but may
+be impacted by the fragmentation.
+
+**MAKE FILE DATA MORE CONTIGUOUS**
+
+An optional but recommended step is to run defragmentation on the entire
+filesystem. This will attempt to make file extents more contiguous.
+
+   # btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs
+
+Verbose recursive defragmentation ('-v', '-r'), flush data per-file ('-f') with target
+extent size 32M ('-t').
+
+**ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT**
+
+Optional but recommended step.
+
+The metadata block groups after conversion may be smaller than the default size
+(256MiB or 1GiB). Running a balance will attempt to merge the block groups.
+This depends on the free space layout (and fragmentation) and may fail. This is
+a soft error leaving the filesystem usable but the block group layout may
+remain unchanged.
+
+Note that balance operation takes a lot of time.
+
+   # btrfs balance start -m /mnt/btrfs
 
 OPTIONS
 -------
 -d|--no-datasum::
-Disable data checksum calculations and set NODATASUM file flag. This can speed
-up the conversion.
+disable data checksum calculations and set NODATASUM file flag, this can speed
+up the conversion
 -i|--no-xattr::
-Ignore xattrs and ACLs.
+ignore xattrs and ACLs of files
 -n|--no-inline::
-Disable inlining of small files to metadata blocks.
+disable inlining of small files to metadata blocks, this will decrease the metadata
+consumption and may help to convert a filesystem with low free space
 -N|--nodesize <SIZE>::
-Set filesystem nodesize, the tree block size in which btrfs stores data.
+set filesystem nodesize, the tree block size in which btrfs stores its metadata.
 The default value is 16KB (16384) or the page size, whichever is bigger.
-Must be a multiple of the sectorsize, but not larger than 65536.
+Must be a multiple of the sectorsize, but not larger than 65536. Se
+`mkfs.btrfs`(8) for more details.
 -r|--rollback::
-Roll back to ext2fs.
+rollback to the original ext2/3/4 filesystem if possible
 -l|--label <LABEL>::
-set filesystem label during conversion.
+set filesystem label during conversion
 -L|--copy-label::
-use label from the converted filesystem.
+use label from the converted filesystem
 -p|--progress::
-Show progress of conversion, on by default.
+show progress of conversion, on by default
 --no-progress::
-Disable detailed progress and show only the main phases of conversion.
+disable detailed progress and show only the main phases of conversion
 
 EXIT STATUS
 -----------
@@ -56,4 +96,3 @@ If any problems happened, 1 will be returned.
 SEE ALSO
 --------
 `mkfs.btrfs`(8)
-