> On Aug 14, 2018, at 4:40 AM, Kevin Wolf <kw...@redhat.com> wrote: > > Am 13.08.2018 um 20:19 hat Eric Blake geschrieben: >> On 08/13/2018 11:56 AM, Max Reitz wrote: >>> >>> Ah, hm, so much for that. Hm... I don't quite know what to think of >>> this. It does indeed improve legibility. But the question is whether >>> --help should be as condensed as possible, and if the user finds it hard >>> to read, whether they should not just open the man page... >>> >>> Then again, our --help text already has 102 lines. >>> >>> Let me just think about it for a bit longer. :-) >>> (And see whether others have opinions.) >> >> And I've already expressed my opinion that it is already rather long, where >> making it longer is not necessarily making it smarter. > > I think if we want to improve the help text, we should split it up. > > $ qemu-img --help > qemu-img version 2.12.94 (v3.0.0-rc4-5-g4fe9c3e13d-dirty) > Copyright (c) 2003-2017 Fabrice Bellard and the QEMU Project developers > usage: qemu-img [standard options] command [command options] > QEMU disk image utility > > '-h', '--help' display this help and exit > '-V', '--version' output version information and exit > '-T', '--trace' [[enable=]<pattern>][,events=<file>][,file=<file>] > specify tracing options > > Commands: > > amend Change options of an existing disk image > bench Run benchmarks on a given disk image > check Check the disk image for consistency or repair it > commit Merge the disk image into its backing file > ... > > Run 'qemu-img <command> --help' for details. > > See <https://qemu.org/contribute/report-a-bug> for how to report bugs. > More information on the QEMU project at <https://qemu.org>. > > $ qemu-img check --help > usage: qemu-img check [--object objectdef] [--image-opts] [-q] [-f fmt] > [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename > > Command parameters: > -f 'fmt' is the disk image format. It is guessed automatically > in most cases. > > -q use Quiet mode - do not print any output (except errors). > > -r tries to repair any inconsistencies that are found during the > check. '-r leaks' repairs only cluster leaks, whereas '-r > all' fixes all kinds of errors, with a higher risk of > choosing the wrong fix or hiding corruption that has already > occurred. > > -T 'src_cache' is the cache mode used to read input disk images, > the valid options are the same as for the 'cache' option. > > --object 'objectdef' is a QEMU user creatable object definition. See > the qemu(1) manual page for a description of the object > properties. The most common object type is a 'secret', which > is used to supply passwords and/or encryption keys. > > --output 'ofmt' is 'human' for human-readable output (default) or > 'json' for JSON output. > > Examples: > > ... > > Kevin
I am by no means an expert at qemu-img. But I did try my best to create what I think should be the new output for qemu-img <command> --help. This is just the text I plan on using in a future patch. It is easier to read right now than it will be in patch form, so please let me know if there are any errors in this documentation. Thank you. <amend> usage: qemu-img amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt] [-t cache] -o options filename Command parameters: -f 'fmt' is the disk image format. It is guessed automatically in most cases. --image-opts Treat filename as a set of image options, instead of a plain filename. -o Used with a comma separated list of format specific options in a name=value format. Use "-o ?" for an overview of the options supported by the used format --object 'objectdef' is a QEMU user creatable object definition. See the qemu(1) manual page for a description of the object properties. The most common object type is a 'secret', which is used to supply passwords and/or encryption keys. -p Display progress bar. If the -p option is not used for a command that supports it, the progress is reported when the process receives a "SIGUSR1" signal. -q Quiet mode - do not print any output (except errors). There's no progress bar in case both -q and -p options are used. -t Specifies the cache mode that should be used with the destination file. Example: qemu-img amend -o compat=0.10 -f qcow2 image.qcow2 <bench> usage: qemu-img bench [-c count] [-d depth] [-f fmt] [--flush-interval=flush_interval] [-n] [--no-drain] [-o offset] [--pattern=pattern] [-q] [-s buffer_size] [-S step_size] [-t cache] [-w] [-U] filename Command parameters: -c Number of I/O requests to perform. -d Number of I/O requests done in parallel. -f fmt' is the disk image format. It is guessed automatically in most cases. --flush-interval How often a flush should take place. -n Use native AIO backend if possible. --no-drain Issue a flush without draining the request queue first. -o The starting position. --pattern The byte pattern used to in write tests. -q Quiet mode - do not print any output (except errors). There's no progress bar in case both -q and -p options are used. -s buffer_size in bytes. -S Increases current position by step_size. -t Specifies the cache mode that should be used with the destination file. -w Perform write test. -U Open the image in shared mode, allowing other QEMU processes to open it in write mode. This option is only allowed when opening images in read-only mode. Example: qemu-img bench -c 20000 -d 50000 -f qcow2 image.qcow2 <check> usage: qemu-img check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename Command parameters: -f 'fmt' is the disk image format. It is guessed automatically in most cases. -q Use Quiet mode - do not print any output (except errors). -r Tries to repair any inconsistencies that are found during the check. '-r leaks' repairs only cluster leaks, whereas '-r all' fixes all kinds of errors, with a higher risk of choosing the wrong fix or hiding corruption that has already occurred. -T 'src_cache' is the cache mode used to read input disk images, the valid options are the same as for the 'cache' option. --object 'objectdef' is a QEMU user creatable object definition. See the qemu(1) manual page for a description of the object properties. The most common object type is a 'secret', which is used to supply passwords and/or encryption keys. --output 'ofmt' is 'human' for human-readable output (default) or 'json' for JSON output. Example: qemu-img check image.qcow2 <commit> usage: qemu-img commit [--object objectdef] [--image-opts] [-q] [-f fmt] [-t cache] [-b base] [-d] [-p] filename Command parameters: -b The base image or backing file. -d Skip emptying filename. -f 'fmt' is the disk image format. It is guessed automatically in most cases. --image-opts Treat filename as a set of image options, instead of a plain filename. --object 'objectdef' is a QEMU user creatable object definition. See the qemu(1) manual page for a description of the object properties. The most common object type is a 'secret', which is used to supply passwords and/or encryption keys. -p Display progress bar. If the -p option is not used for a command that supports it, the progress is reported when the process receives a "SIGUSR1" signal. -q Quiet mode - do not print any output (except errors). There's no progress bar in case both -q and -p options are used. -t Specifies the cache mode that should be used with the destination file. Example: qemu-img commit image.qcow2 <compare> usage: qemu-img compare [--object objectdef] [--image-opts] [-f fmt] [-F fmt] [-T src_cache] [-p] [-q] [-s] [-U] filename1 filename2 Command parameters: -f First image format. -F Second image format. --image-opts Treat filename as a set of image options, instead of a plain filename. -T Specifies the cache mode that should be used with the source file. --object 'objectdef' is a QEMU user creatable object definition. See the qemu(1) manual page for a description of the object properties. The most common object type is a 'secret', which is used to supply passwords and/or encryption keys. -p Display progress bar. If the -p option is not used for a command that supports it, the progress is reported when the process receives a "SIGUSR1" signal. -q Quiet mode - do not print any output (except errors). There's no progress bar in case both -q and -p options are used. -s Enable strict mode. Comparisons differ when image sizes differ or if a sector is allocated in one image and not allocated in the other image. -U Open the image in shared mode, allowing other QEMU processes to open it in write mode. This option is only allowed when opening images in read-only mode. Example: qemu-img compare image1.qcow image2.qcow2 <convert> usage: qemu-img convert [--object objectdef] [--image-opts] [--target-image-opts] [-U] [-c] [-p] [-q] [-n] [-f fmt] [-t cache] [-T src_cache] [-O output_fmt] [-B backing_file] [-o options] [-s snapshot_id_or_name] [-l snapshot_param] [-S sparse_size] [-m num_coroutines] [-W] filename [filename2 [...]] output_filename Command parameters: -B Force the output image to be created as a copy on write image of the specified base image. -c Compress the output image file. -f 'fmt' is the disk image format. It is guessed automatically in most cases. --image-opts Indicates that the source filename parameter is to be interpreted as a full option string, not a plain filename. -l Specifies a snapshot parameter. -m Number of parallel coroutines for the convert process -n Skip the creation of the target volume. -O Format of the output file. -o Allows for specifying options like virtual disk size. --object 'objectdef' is a QEMU user creatable object definition. See the qemu(1) manual page for a description of the object properties. The most common object type is a 'secret', which is used to supply passwords and/or encryption keys. -p Display progress bar. If the -p option is not used for a command that supports it, the progress is reported when the process receives a "SIGUSR1" signal. -q Quiet mode - do not print any output (except errors). There's no progress bar in case both -q and -p options are used. -S The consecutive number of bytes (defaults to 4k) that must contain only zeros for qemu-img to create a sparse image during conversion. -s The name or ID of the snapshot to use. -T Specifies the cache mode that should be used with the source file. -t Specifies the cache mode that should be used with the destination file. --target-image-opts Indicates whether the source filename includes options. -U Open the image in shared mode, allowing other QEMU processes to open it in write mode. This option is only allowed when opening images in read-only mode. -W Allow out-of-order writes to the destination. This option improves performance, but is only recommended for preallocated devices like host devices or other raw block devices. Example: qemu-img convert -f raw -O qcow2 image.img image.qcow2 <create> usage: qemu-img create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size] Command parameters: -b The backing file used to base the output file on. -f The format of the output file. -F The format of the backing file. -u Create the image file even if the backing file cannot be opened. -o Allows for specifying options like virtual disk size. --object 'objectdef' is a QEMU user creatable object definition. See the qemu(1) manual page for a description of the object properties. The most common object type is a 'secret', which is used to supply passwords and/or encryption keys. Example: qemu-img create -f qcow2 image.qcow2 10G <dd> usage: qemu-img dd [-f fmt] [-O output_fmt] [bs=block_size] [count=blocks] [skip=blocks] if=input of=output Command parameters: bs Size of the blocks used in reading and writing (512 bytes is the default). count The limit to how many blocks to read. -f Format of the input file. if The input file. -O Format of the output file. of The output file. skip Number of blocks to skip. Example: qemu-img dd if=/dev/cdrom -O raw of=cd.iso <info> usage: qemu-img info [-f fmt] [--output=ofmt] [--backing-chain] filename Command parameters: --backing-chain Recursively enumerate thru each disk image in the chain for information. -f The format of image file specified by filename. --output The output format of this command. Can be "human" or "json". Example: qemu-img info image.qcow2 <map> usage: qemu-img map [-f fmt] [--output=ofmt] filename Command parameters: -f The format of the image file specified by filename. --output The output format of this command. Can be "human" or "json". Example: qemu-img map image.qcow2 <measure> usage: qemu-img measure [--output=ofmt] [-O output_fmt] [-o options] [--size N ] [--object objectdef] [--image-opts] [-f fmt] [-l snapshot_param] filename Command parameters: -f 'fmt' is the disk image format. It is guessed automatically in most cases. --image-opts Indicates that the source filename parameter is to be interpreted as a full option string, not a plain filename. -l Specifies a snapshot parameter. -O Format of the output file. -o Allows for specifying options. --object 'objectdef' is a QEMU user creatable object definition. See the qemu(1) manual page for a description of the object properties. The most common object type is a 'secret', which is used to supply passwords and/or encryption keys. --output 'ofmt' is 'human' for human-readable output (default) or 'json' for JSON output. --size If given act as if creating a new empty image file using qemu-img create. Example: qemu-img measure -O qcow2 --size 5G <Snapshot> usage: qemu-img snapshot [-l | -a snapshot | -c snapshot | -d snapshot ] filename Command parameters: -a Applies the snapshot. -c Create a snapshot. -d Deletes a snapshot. -l Lists all snapshots Example: qemu-img snapshot -l image.qcow2 <Rebase> usage: qemu-img rebase [-f fmt] [-t cache] [-T src_cache] [-p] [-u] -b backing_file [-F backing_fmt] filename Command parameters: -b The new backing file. -F The format for the new backing file. -f 'fmt' is the disk image format. It is guessed automatically in most cases. -T Specifies the cache mode that should be used with the source file. -t Specifies the cache mode that should be used with the destination file. -p Display progress bar. If the -p option is not used for a command that supports it, the progress is reported when the process receives a "SIGUSR1" signal. -u Operate in unsafe mode. Example: qemu-img rebase -b backing.img diff.qcow2 <Resize> usage: qemu-img resize [--shrink] [--preallocation=prealloc] filename [+ | -] size Command parameters: --preallocation When growing an image, specify how the additional image area should be allocated on the host. --shrink Informs qemu-img that the user acknowledges all loss of data beyond the truncated image's end. Example: qemu-img resize image.qcow2 20G