btrfs-progs: docs: update btrfs-check

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

Documentation/btrfs-check.asciidoc

@@ -11,42 +11,87 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-*btrfs check* is used to check or repair an unmounted btrfs filesystem.
 
-NOTE: Since btrfs is under development, the *btrfs check* capabilities are
-continuously enhanced. It's highly recommended to read the following btrfs
-wiki before executing *btrfs check* with '--repair' option: +
-https://btrfs.wiki.kernel.org/index.php/Btrfsck
+The filesystem checker is used to verify structural integrity of a filesystem
+and attempt to repair it if requested. The filesystem must be unmounted.
+
+By default, *btrfs check* will not modify the device but you can reaffirm that
+by the option '--readonly'.
 
 *btrfsck* is an alias of *btrfs check* command and is now deprecated.
 
-OPTIONS
--------
--s|--super <superblock>::
-use <superblock>th superblock copy, valid values are 0 up to 2 if the
-respective superblock offset is within the filesystem
+WARNING: Do not use '--repair' unless you are adviced to by a developer, an
+experienced user or accept the fact that 'fsck' cannot possibly fix all sorts
+of damage that could happen to a filesystem because of software and hardware
+bugs.
+
+The structural integrity check verifies if internal filesystem objects or
+data structures satisfy the constraints, point to the right objects or are
+correctly connected together.
+
+There are several cross checks that can detect wrong reference counts of shared
+extents, backrefrences, missing extents of inodes, directory and inode
+connectivity etc.
+
+The amount of memory required can be high, depending on the size of the
+filesystem, smililarly the run time.
+
+SAFE OR ADVISORY OPTIONS
+------------------------
+
 -b|--backup::
-use the first backup roots stored in the superblock that is valid
---repair::
-try to repair the filesystem
---readonly::
-run in read-only mode (default)
---init-csum-tree::
-create a new CRC tree and recalculate all checksums
---init-extent-tree::
-create a new extent tree
+use the first valid set of backup roots stored in the superblock
++
+This can be combined with '--super' if some of the superblocks are damaged.
+
 --check-data-csum::
 verify checksums of data blocks
--p|--progress::
-indicate progress at various checking phases
---qgroup-report::
-verify qgroup accounting and compare against filesystem accounting
++
+This expects that the filesystem is otherwise
+OK, so this is basically and offline 'scrub' but does not repair data from
+spare coipes.
+
+--chunk-root <bytenr>::
+use the given offset 'bytenr' for the chunk tree root
+
 -E|--subvol-extents <subvolid>::
 show extent state for the given subvolume
+
+-p|--progress::
+indicate progress at various checking phases
+
+--qgroup-report::
+verify qgroup accounting and compare against filesystem accounting
+
 -r|--tree-root <bytenr>::
-use the given bytenr for the tree root
---chunk-root <bytenr>::
-use the given bytenr for the chunk tree root
+use the given offset 'bytenr' for the tree root
+
+--readonly::
+(default)
+run in read-only mode, this option exists to calm potential panic when users
+are going to run the checker
+
+-s|--super <superblock>::
+use 'superblock'th superblock copy, valid values are 0, 1 or 2 if the
+respective superblock offset is within the device size
++
+This can be used to use a different starting point if some of the primary
+superblock is damaged.
+
+DANGEROUS OPTIONS
+-----------------
+
+--repair::
+enable the repair mode and attempt to fix problems where possible
+--init-csum-tree::
+create a new checksum tree and recalculate checksums in all files
++
+NOTE: Do not blindly use this option to fix checksum mismatch problems.
+
+--init-extent-tree::
+build the extent tree from scratch
++
+NOTE: Do not use unless you know what you're doing.
 
 EXIT STATUS
 -----------