btrfs-progs: docs: add note about mount option applicability

[platform/upstream/btrfs-progs.git] / Documentation / btrfs-convert.asciidoc

diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc
index ab3577d..07ff608 100644 (file)
--- 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
+btrfs-convert - convert from ext2/3/4 or reiserfs filesystem to btrfs in-place
 
 SYNOPSIS
 --------
@@ -11,13 +11,22 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-*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'.
+*btrfs-convert* is used to convert existing source filesystem image to a btrfs
+filesystem in-place.  The original filesystem image is accessible in subvolume
+named like 'ext2_saved' as file 'image'.
 
-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.
+Supported filesystems:
+
+* ext2, ext3, ext4 -- original feature, always built in
+
+* reiserfs -- since version 4.13, opptinally built, requires libreiserfscore 3.6.27
+
+The list of supported source filesystem by a given binary is listed at the end
+of help (option '--help').
+
+WARNING: If you are going to perform rollback to the original filesystem, you
+should not execute *btrfs balance* command on the converted filesystem. This
+will change the extent layout and make *btrfs-convert* unable to rollback.
 
 The conversion utilizes free space of the original filesystem. The exact
 estimate of the required space cannot be foretold. The final btrfs metadata
@@ -28,15 +37,23 @@ 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.
 
+Due to different constraints, it's possible to convert only filesystem that
+have supported data block size (ie. the same that would be valid for
+'mkfs.btrfs'). This is typically the system page size (4KiB on x86_64
+machines).
+
+NOTE: The source filesystem should be clean, you are encouraged to run the
+'fsck' tool if you're not sure.
+
 **REMOVE THE ORIGINAL FILESYSTEM METADATA**
 
-By removing the 'ext2_saved' subvolume, all metadata of the original filesystem
-will be removed:
+By removing the subvolume named like 'ext2_saved' or 'reiserfs_saved', 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.
+be impacted by the fragmentation inherited from the original filesystem.
 
 **MAKE FILE DATA MORE CONTIGUOUS**
 
@@ -45,8 +62,8 @@ 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').
+Verbose recursive defragmentation ('-v', '-r'), flush data per-file ('-f') with
+target extent size 32MiB ('-t').
 
 **ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT**
 
@@ -54,18 +71,19 @@ 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.
+This depends on the free space layout (and fragmentation) and may fail due to
+lack of enough work space. 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.
+Note that balance operation takes a lot of time, please see also
+`btrfs-balance`(8).
 
    # btrfs balance start -m /mnt/btrfs
 
 OPTIONS
 -------
 -d|--no-datasum::
-disable data checksum calculations and set NODATASUM file flag, this can speed
+disable data checksum calculations and set the NODATASUM file flag, this can speed
 up the conversion
 -i|--no-xattr::
 ignore xattrs and ACLs of files
@@ -84,17 +102,20 @@ set filesystem label during conversion
 -L|--copy-label::
 use label from the converted filesystem
 -O|--features <feature1>[,<feature2>...]::
-A list of filesystem features turned on at btrfs-convert time. Not all features
+A list of filesystem features turned on at conversion time. Not all features
 are supported by old kernels. To disable a feature, prefix it with '^'.
+Description of the features is in section 'FILESYSTEM FEATURES' of
+`mkfs.btrfs`(8).
 +
 To see all available features that btrfs-convert supports run:
 +
 +btrfs-convert -O list-all+
 +
 -p|--progress::
-show progress of conversion, on by default
+show progress of conversion (a heartbeat indicator and number of inodes
+processed), on by default
 --no-progress::
-disable detailed progress and show only the main phases of conversion
+disable progress and show only the main phases of conversion
 
 EXIT STATUS
 -----------