btrfs-progs: deprecate subcommand specific verbose/quiet options

Many subcommands have their own verbosity options that are being superseded by the global options. Update the help text to reflect that where applicable. Signed-off-by: David Sterba <dsterba@suse.com>
2024-12-22 06:10:06 +00:00 · 2020-06-26 22:20:56 +02:00 · 2020-06-26 22:20:56 +02:00 · 27a65e016e
commit 27a65e016e
parent 761add2622
18 changed files with 63 additions and 42 deletions
--- a/Documentation/btrfs-balance.asciidoc
+++ b/Documentation/btrfs-balance.asciidoc
@ -112,18 +112,21 @@ act on data block groups, see `FILTERS` section for details about 'filters'
 act on metadata chunks, see `FILTERS` section for details about 'filters'
 -s[<filters>]::::
 act on system chunks (requires '-f'), see `FILTERS` section for details about 'filters'.
-v::::
-be verbose and print balance filter arguments
 -f::::
 force a reduction of metadata integrity, eg. when going from 'raid1' to 'single'
 --background|--bg::::
 run the balance operation asynchronously in the background, uses `fork`(2) to
 start the process that calls the kernel ioctl
+-v::::
+(deprecated) alias for global '-v' option

 *status* [-v] <path>::
 Show status of running or paused balance.
 +
-If '-v' option is given, output will be verbose.
+`Options`
+
+-v::::
+(deprecated) alias for global '-v' option

 FILTERS
 -------
--- a/Documentation/btrfs-filesystem.asciidoc
+++ b/Documentation/btrfs-filesystem.asciidoc
@ -110,8 +110,6 @@ KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).
 +
 `Options`
 +
-v::::
-be verbose, print file names as they're submitted for defragmentation
 -c[<algo>]::::
 compress file contents while defragmenting. Optional argument selects the compression
 algorithm, 'zlib' (default), 'lzo' or 'zstd'. Currently it's not possible to select no
@ -137,6 +135,9 @@ target extent size, do not touch extents bigger than 'size', default: 32M
 The value is only advisory and the final size of the extents may differ,
 depending on the state of the free space and fragmentation or other internal
 logic. Reasonable values are from tens to hundreds of megabytes.
+
+-v::::
+(deprecated) alias for global '-v' option

 *du* [options] <path> [<path>..]::
 Calculate disk usage of the target files using FIEMAP. For individual
--- a/Documentation/btrfs-inspect-internal.asciidoc
+++ b/Documentation/btrfs-inspect-internal.asciidoc
@ -138,7 +138,7 @@ at 'path', ie. all hardlinks
 `Options`
 +
 -v::::
-verbose mode, print count of returned paths and ioctl() return value
+(deprecated) alias for global '-v' option

 *logical-resolve* [-Pvo] [-s <bufsize>] <logical> <path>::
 (needs root privileges)
@ -149,8 +149,6 @@ resolve paths to all files at given 'logical' address in the linear filesystem s
 +
 -P::::
 skip the path resolving and print the inodes instead
-v::::
-verbose mode, print count of returned paths and all ioctl() return values
 -o::::
 ignore offsets, find all references to an extent instead of a single block.
 Requires kernel support for the V2 ioctl (added in 4.15). The results might need
@ -160,6 +158,8 @@ to be obtained by other means.
 set internal buffer for storing the file names to 'bufsize', default is 64k,
 maximum 16m.  Buffer sizes over 64K require kernel support for the V2 ioctl
 (added in 4.15).
+-v::::
+(deprecated) alias for global '-v' option

 *min-dev-size* [options] <path>::
 (needs root privileges)
--- a/Documentation/btrfs-receive.asciidoc
+++ b/Documentation/btrfs-receive.asciidoc
@ -35,12 +35,6 @@ A subvolume is made read-only after the receiving process finishes successfully

 `Options`

-v::
-increase verbosity about performed actions, print details about each operation
-
-q|--quiet::
-suppress all messages except errors
-
 -f <FILE>::
 read the stream from <FILE> instead of stdin,

@ -71,6 +65,20 @@ dump the stream metadata, one line per operation
 +
 Does not require the 'path' parameter. The filesystem remains unchanged.

+-q|--quiet::
+(deprecated) alias for global '-q' option
+
+-v::
+(deprecated) alias for global '-v' option
+
+`Global options`
+
+-v|--verbose::
+increase verbosity about performed actions, print details about each operation
+
+-q|--quiet::
+suppress all messages except errors
+
 BUGS
 ----
 *btrfs receive* sets the subvolume read-only after it completes
--- a/Documentation/btrfs-rescue.asciidoc
+++ b/Documentation/btrfs-rescue.asciidoc
@ -23,10 +23,10 @@ Recover the chunk tree by scanning the devices
 +
 -y::::
 assume an answer of 'yes' to all questions.
-v::::
-verbose mode.
 -h::::
 help.
+-v::::
+(deprecated) alias for global '-v' option

 NOTE: Since *chunk-recover* will scan the whole device, it will be *VERY* slow
 especially executed on a large device.
@ -58,7 +58,7 @@ Recover bad superblocks from good copies.
 -y::::
 assume an answer of 'yes' to all questions.
 -v::::
-verbose mode.
+(deprecated) alias for global '-v' option

 *zero-log* <device>::
 clear the filesystem log tree
--- a/Documentation/btrfs-restore.asciidoc
+++ b/Documentation/btrfs-restore.asciidoc
@ -47,9 +47,6 @@ restore owner, mode and times for files and directories
 -S|--symlinks::
 restore symbolic links as well as normal files

-v|--verbose::
-be verbose and print what is being restored
-
 -i|--ignore-errors::
 ignore errors during restoration and continue

@ -90,6 +87,14 @@ hierarchy.
 -c::
 ignore case (--path-regex only)

+-v|--verbose::
+(deprecated) alias for global '-v' option
+
+`Global options`
+
+-v|--verbose::
+be verbose and print what is being restored
+
 EXIT STATUS
 -----------
 *btrfs restore* returns a zero exit status if it succeeds. Non zero is
--- a/Documentation/btrfs-scrub.asciidoc
+++ b/Documentation/btrfs-scrub.asciidoc
@ -74,8 +74,6 @@ Note that not all IO schedulers honor the ionice settings.
 do not background and print scrub statistics when finished
 -d::::
 print separate statistics for each device of the filesystem ('-B' only) at the end
-q::::
-be quiet, omit error messages and statistics
 -r::::
 run in read-only mode, do not attempt to correct anything, can be run on a read-only
 filesystem
@ -89,6 +87,8 @@ set IO priority classdata (see `ionice`(1) manpage)
 force starting new scrub even if a scrub is already running,
 this can useful when scrub status file is damaged and reports a running
 scrub although it is not, but should not normally be necessary
+-q::::
+(deprecated) alias for global '-q' option

 *status* [-d] <path>|<device>::
 Show status of a running scrub for the filesystem identified by 'path' or
--- a/Documentation/btrfs-send.asciidoc
+++ b/Documentation/btrfs-send.asciidoc
@ -55,12 +55,17 @@ send in 'NO_FILE_DATA' mode
 The output stream does not contain any file
 data and thus cannot be used to transfer changes. This mode is faster and
 is useful to show the differences in metadata.
-
+-q|--quiet::::
+(deprecated) alias for global '-q' option
 -v|--verbose::
-enable verbose output, print generated commands in a readable form, (each
-occurrence of this option increases the verbosity level)
+(deprecated) alias for global '-v' option
+
+`Global options`
+
 -q|--quiet::
 suppress all messages except errors
+-v|--verbose::
+increase output verbosity, print generated commands in a readable form

 EXIT STATUS
 -----------
--- a/Documentation/btrfs-subvolume.asciidoc
+++ b/Documentation/btrfs-subvolume.asciidoc
@ -86,12 +86,11 @@ wait for transaction commit at the end of the operation.
 -C|--commit-each::::
 wait for transaction commit after deleting each subvolume.
 +
-v|--verbose::::
-verbose output of operations.
-+
 -i|--subvolid <subvolid>::::
 subvolume id to be removed instead of the <path> that should point to the
 filesystem with the subvolume
+-v|--verbose::::
+(deprecated) alias for global '-v' option

 *find-new* <subvolume> <last_gen>::
 List the recently modified files in a subvolume, after <last_gen> generation.
--- a/cmds/balance.c
+++ b/cmds/balance.c
@ -495,11 +495,11 @@ static const char * const cmd_balance_start_usage[] = {
 	"-d[filters]    act on data chunks",
 	"-m[filters]    act on metadata chunks",
 	"-s[filters]    act on system chunks (only under -f)",
-	"-v|--verbose   be verbose",
 	"-f             force a reduction of metadata integrity",
 	"--full-balance do not print warning and do not delay start",
 	"--background|--bg",
 	"               run the balance as a background process",
+	"-v|--verbose   deprecated, alias for global -v option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
 	HELPINFO_INSERT_QUIET,
@ -834,7 +834,7 @@ static const char * const cmd_balance_status_usage[] = {
 	"btrfs balance status [-v] <path>",
 	"Show status of running or paused balance",
 	"",
-	"-v|--verbose     be verbose",
+	"-v|--verbose     deprecated, alias for global -v option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
 	NULL
--- a/cmds/filesystem.c
+++ b/cmds/filesystem.c
@ -833,13 +833,13 @@ static const char * const cmd_filesystem_defrag_usage[] = {
 	"btrfs filesystem defragment [options] <file>|<dir> [<file>|<dir>...]",
 	"Defragment a file or a directory",
 	"",
-	"-v                  be verbose",
 	"-r                  defragment files recursively",
 	"-c[zlib,lzo,zstd]   compress the file while defragmenting",
 	"-f                  flush data to disk immediately after defragmenting",
 	"-s start            defragment only from byte onward",
 	"-l len              defragment only up to len bytes",
 	"-t size             target extent size hint (default: 32M)",
+	"-v                  deprecated, alias for global -v option",
 	"",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
--- a/cmds/inspect.c
+++ b/cmds/inspect.c
@ -82,7 +82,7 @@ static const char * const cmd_inspect_inode_resolve_usage[] = {
 	"btrfs inspect-internal inode-resolve [-v] <inode> <path>",
 	"Get file system paths for the given inode",
 	"",
-	"-v   verbose mode",
+	"-v   deprecated, alias for global -v option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
 	NULL
@ -129,13 +129,13 @@ static const char * const cmd_inspect_logical_resolve_usage[] = {
 	"Get file system paths for the given logical address",
 	"",
 	"-P          skip the path resolving and print the inodes instead",
-	"-v          verbose mode",
 	"-o          ignore offsets when matching references (requires v2 ioctl",
 	"            support in the kernel 4.15+)",
 	"-s bufsize  set inode container's size. This is used to increase inode",
 	"            container's size in case it is not enough to read all the ",
 	"            resolved results. The max value one can set is 64k with the",
 	"            v1 ioctl. Sizes over 64k will use the v2 ioctl (kernel 4.15+)",
+	"-v          deprecated, alias for global -v option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
 	NULL
--- a/cmds/receive.c
+++ b/cmds/receive.c
@ -1229,7 +1229,6 @@ static const char * const cmd_receive_usage[] = {
 	"After receiving a subvolume, it is immediately set to",
 	"read-only.",
 	"",
-	"-v               increase verbosity about performed actions",
 	"-q|--quiet       suppress all messages, except errors",
 	"-f FILE          read the stream from FILE instead of stdin",
 	"-e               terminate after receiving an <end cmd> marker in the stream.",
@ -1245,6 +1244,7 @@ static const char * const cmd_receive_usage[] = {
 	"                 this file system is mounted.",
 	"--dump           dump stream metadata, one line per operation,",
 	"                 does not require the MOUNT parameter",
+	"-v               deprecated, alias for global -v option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
 	HELPINFO_INSERT_QUIET,
--- a/cmds/rescue.c
+++ b/cmds/rescue.c
@ -38,8 +38,8 @@ static const char * const cmd_rescue_chunk_recover_usage[] = {
 	"Recover the chunk tree by scanning the devices one by one.",
 	"",
 	"-y	Assume an answer of `yes' to all questions",
-	"-v	Verbose mode",
 	"-h	Help",
+	"-v     deprecated, alias for global -v option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
 	NULL
@ -106,7 +106,7 @@ static const char * const cmd_rescue_super_recover_usage[] = {
 	"Recover bad superblocks from good copies",
 	"",
 	"-y	Assume an answer of `yes' to all questions",
-	"-v	Verbose mode",
+	"-v     deprecated, alias for global -v option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
 	NULL
--- a/cmds/restore.c
+++ b/cmds/restore.c
@ -1386,7 +1386,6 @@ static const char * const cmd_restore_usage[] = {
 	"-x|--xattr           restore extended attributes",
 	"-m|--metadata        restore owner, mode and times",
 	"-S|--symlink         restore symbolic links",
-	"-v|--verbose         verbose",
 	"-i|--ignore-errors   ignore errors",
 	"-o|--overwrite       overwrite",
 	"-t <bytenr>          tree location",
@ -1401,6 +1400,7 @@ static const char * const cmd_restore_usage[] = {
 	"                     you have to use following syntax (possibly quoted):",
 	"                     ^/(|home(|/username(|/Desktop(|/.*))))$",
 	"-c                   ignore case (--path-regex only)",
+	"-v|--verbose         deprecated, alias for global -v option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
 	NULL
--- a/cmds/scrub.c
+++ b/cmds/scrub.c
@ -1612,6 +1612,7 @@ static const char * const cmd_scrub_start_usage[] = {
 	"-n     set ioprio classdata (see ionice(1) manpage)",
 	"-f     force starting new scrub even if a scrub is already running",
 	"       this is useful when scrub stats record file is damaged",
+	"-q     deprecated, alias for global -q option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_QUIET,
 	NULL
@ -1678,11 +1679,11 @@ static const char * const cmd_scrub_resume_usage[] = {
 	"",
 	"-B     do not background",
 	"-d     stats per device (-B only)",
-	"-q     be quiet",
 	"-r     read only mode",
 	"-R     raw print mode, print full data instead of summary",
 	"-c     set ioprio class (see ionice(1) manpage)",
 	"-n     set ioprio classdata (see ionice(1) manpage)",
+	"-q     deprecated, alias for global -q option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_QUIET,
 	NULL
--- a/cmds/send.c
+++ b/cmds/send.c
@ -452,9 +452,8 @@ static const char * const cmd_send_usage[] = {
 	"                 does not contain any file data and thus cannot be used",
 	"                 to transfer changes. This mode is faster and useful to",
 	"                 show the differences in metadata.",
-	"-v|--verbose     enable verbose output to stderr, each occurrence of",
-	"                 this option increases verbosity",
-	"-q|--quiet       suppress all messages, except errors",
+	"-v|--verbose     deprecated, alias for global -v option",
+	"-q|--quiet       deprecated, alias for global -q option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
 	HELPINFO_INSERT_QUIET,
--- a/cmds/subvolume.c
+++ b/cmds/subvolume.c
@ -238,7 +238,7 @@ static const char * const cmd_subvol_delete_usage[] = {
 	"-c|--commit-after      wait for transaction commit at the end of the operation",
 	"-C|--commit-each       wait for transaction commit after deleting each subvolume",
 	"-i|--subvolid          subvolume id of the to be removed subvolume",
-	"-v|--verbose           verbose output of operations",
+	"-v|--verbose           deprecated, alias for global -v option",
 	HELPINFO_INSERT_GLOBALS,
 	HELPINFO_INSERT_VERBOSE,
 	HELPINFO_INSERT_QUIET,