X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=Documentation%2Fbtrfs.asciidoc;h=7316ac094413dfae40871e0e018b48febd0550ac;hb=f435ddedcff81b0f381828390747ce8e7ad6cbd9;hp=3740c8b31d6c94e5e9357a8ecd8d89379d9e7500;hpb=cc68c4f9afb4624e5ac4dc10e2631ab7dbe2f17a;p=platform%2Fupstream%2Fbtrfs-progs.git

diff --git a/Documentation/btrfs.asciidoc b/Documentation/btrfs.asciidoc
index 3740c8b..7316ac0 100644
--- a/Documentation/btrfs.asciidoc
+++ b/Documentation/btrfs.asciidoc
@@ -3,7 +3,7 @@ btrfs(8)
 
 NAME
 ----
-btrfs - control a btrfs filesystem
+btrfs - a toolbox to manage btrfs filesystems
 
 SYNOPSIS
 --------
@@ -11,21 +11,34 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-*btrfs* is used to control the filesystem and the files and directories stored.
-It is the tool to create or destroy a snapshot or a subvolume for the
-filesystem, to defrag a file or a directory, flush the data to the disk,
-to resize the filesystem, to scan the device.
+The *btrfs* utility is a toolbox for managing btrfs filesystems.  There are
+command groups to work with subvolumes, devices, for whole filesystem or other
+specific actions. See section *COMMANDS*.
+
+There are also standalone tools for some tasks like *btrfs-convert* or
+*btrfstune* that were separate historically and/or haven't been merged to the
+main utility. See section 'STANDALONE TOOLS' for more details.
+
+For other topics (mount options, etc) please refer to the separate manual
+page `btrfs`(5).
+
+COMMAND SYNTAX
+--------------
+
+Any command name can be shortened so long as the shortened form is unambiguous,
+however, it is recommended to use full command names in scripts.  All command
+groups have their manual page named *btrfs-<group>*.
 
-It is possible to abbreviate the commands unless the commands are ambiguous.
 For example: it is possible to run *btrfs sub snaps* instead of
 *btrfs subvolume snapshot*.
 But *btrfs file s* is not allowed, because *file s* may be interpreted
 both as *filesystem show* and as *filesystem sync*.
 
-If a command is terminated by '--help', the detailed help is showed.
-If the passed command matches more commands,
-detailed help of all the matched commands is showed. For example
-*btrfs dev --help* shows the help of all *device** commands.
+If the command name is ambiguous, the list of conflicting options is
+printed.
+
+For an overview of a given command use 'btrfs command --help'
+or 'btrfs [command...] --help --full' to print all available options.
 
 COMMANDS
 --------
@@ -90,6 +103,29 @@ COMMANDS
 	Create/delete/list/manage btrfs subvolume. +
 	See `btrfs-subvolume`(8) for details.
 
+STANDALONE TOOLS
+----------------
+
+New functionality could be provided using a standalone tool. If the functionality
+proves to be useful, then the standalone tool is declared obsolete and its
+functionality is copied to the main tool. Obsolete tools are removed after a
+long (years) depreciation period.
+
+Tools that are still in active use without an equivalent in *btrfs*:
+
+*btrfs-convert*:: in-place conversion from ext2/3/4 filesystems to btrfs
+*btrfstune*:: tweak some filesystem properties on a unmounted filesystem
+*btrfs-select-super*:: rescue tool to overwrite primary superblock from a spare copy
+*btrfs-find-root*:: rescue helper to find tree roots in a filesystem
+
+Deprecated and obsolete tools:
+
+*btrfs-debug-tree*:: moved to *btrfs inspect-internal dump-tree*. Removed from
+source distribution.
+*btrfs-show-super*:: moved to *btrfs inspect-internal dump-super*, standalone
+removed.
+*btrfs-zero-log*:: moved to *btrfs rescue zero-log*, standalone removed.
+
 EXIT STATUS
 -----------
 *btrfs* returns a zero exit status if it succeeds. Non zero is returned in
@@ -103,9 +139,9 @@ further details.
 
 SEE ALSO
 --------
-`mkfs.btrfs`(8), `ionice`(1),
 `btrfs-balance`(8),
 `btrfs-check`(8),
+`btrfs-convert`(8),
 `btrfs-device`(8),
 `btrfs-filesystem`(8),
 `btrfs-inspect-internal`(8),
@@ -119,3 +155,5 @@ SEE ALSO
 `btrfs-scrub`(8),
 `btrfs-send`(8),
 `btrfs-subvolume`(8),
+`btrfstune`(8),
+`mkfs.btrfs`(8)