[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands i
From: |
Programmingkid |
Subject: |
Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation |
Date: |
Thu, 16 Aug 2018 21:27:27 -0400 |
> On Aug 14, 2018, at 4:40 AM, Kevin Wolf <address@hidden> 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
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Max Reitz, 2018/08/13
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Eric Blake, 2018/08/13
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Kevin Wolf, 2018/08/14
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation,
Programmingkid <=
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Eric Blake, 2018/08/17
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Programmingkid, 2018/08/17
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Eric Blake, 2018/08/17
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Programmingkid, 2018/08/18