* [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
[not found] <20180730212249.16418-1-programmingkidx@gmail.com>
@ 2018-07-31 0:55 ` Programmingkid
2018-08-13 16:56 ` Max Reitz
1 sibling, 0 replies; 11+ messages in thread
From: Programmingkid @ 2018-07-31 0:55 UTC (permalink / raw)
To: QEMU Developers
When the user uses the --help option in qemu-img, the output for the commands is very hard to read due to being so close to each other. With this patch the help for the commands is double spaced making things easier to read.
Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
---
qemu-img.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/qemu-img.c b/qemu-img.c
index 9b7506b8ae..6a7e63435e 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -120,7 +120,7 @@ static void QEMU_NORETURN help(void)
"\n"
"Command syntax:\n"
#define DEF(option, callback, arg_string) \
- " " arg_string "\n"
+ " " arg_string "\n\n"
#include "qemu-img-cmds.h"
#undef DEF
"\n"
--
2.14.3 (Apple Git-98)
^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
[not found] <20180730212249.16418-1-programmingkidx@gmail.com>
2018-07-31 0:55 ` [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation Programmingkid
@ 2018-08-13 16:56 ` Max Reitz
2018-08-13 18:19 ` Eric Blake
1 sibling, 1 reply; 11+ messages in thread
From: Max Reitz @ 2018-08-13 16:56 UTC (permalink / raw)
To: John Arbuckle, eblake, kwolf, qemu-block, Qemu-devel
[-- Attachment #1: Type: text/plain, Size: 1282 bytes --]
On 2018-07-30 23:22, John Arbuckle wrote:
> When the user uses the --help option in qemu-img, the output for the commands is very hard to read due to being so close to each other. With this patch the help for the commands is double spaced making things easier to read.
>
> Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
> ---
> qemu-img.c | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/qemu-img.c b/qemu-img.c
> index 9b7506b8ae..6a7e63435e 100644
> --- a/qemu-img.c
> +++ b/qemu-img.c
> @@ -120,7 +120,7 @@ static void QEMU_NORETURN help(void)
> "\n"
> "Command syntax:\n"
> #define DEF(option, callback, arg_string) \
> - " " arg_string "\n"
> + " " arg_string "\n\n"
> #include "qemu-img-cmds.h"
> #undef DEF
> "\n"
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.)
Max
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
2018-08-13 16:56 ` Max Reitz
@ 2018-08-13 18:19 ` Eric Blake
2018-08-14 8:40 ` Kevin Wolf
0 siblings, 1 reply; 11+ messages in thread
From: Eric Blake @ 2018-08-13 18:19 UTC (permalink / raw)
To: Max Reitz, John Arbuckle, kwolf, qemu-block, Qemu-devel
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.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3266
Virtualization: qemu.org | libvirt.org
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
2018-08-13 18:19 ` Eric Blake
@ 2018-08-14 8:40 ` Kevin Wolf
2018-08-14 12:55 ` Eric Blake
2018-08-17 1:27 ` Programmingkid
0 siblings, 2 replies; 11+ messages in thread
From: Kevin Wolf @ 2018-08-14 8:40 UTC (permalink / raw)
To: Eric Blake; +Cc: Max Reitz, John Arbuckle, qemu-block, Qemu-devel
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
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
2018-08-14 8:40 ` Kevin Wolf
@ 2018-08-14 12:55 ` Eric Blake
2018-08-14 17:59 ` Programmingkid
2018-08-17 1:27 ` Programmingkid
1 sibling, 1 reply; 11+ messages in thread
From: Eric Blake @ 2018-08-14 12:55 UTC (permalink / raw)
To: Kevin Wolf; +Cc: Max Reitz, John Arbuckle, qemu-block, Qemu-devel
On 08/14/2018 03:40 AM, Kevin Wolf wrote:
>> 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>.
Indeed, that matches the approach that 'cvs --help' and 'git --help'
have taken. I could live with a split along those lines as being
something smarter. When you want to learn the options for 'create', you
may have to ask two different --help commands to learn everything you
need ['--help' didn't give me enough, but told me to use 'create
--help'], but at least you are not inundated with answers irrelevant to
the question you are asking, so you don't have to scroll through a wall
of text.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3266
Virtualization: qemu.org | libvirt.org
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
2018-08-14 12:55 ` Eric Blake
@ 2018-08-14 17:59 ` Programmingkid
0 siblings, 0 replies; 11+ messages in thread
From: Programmingkid @ 2018-08-14 17:59 UTC (permalink / raw)
To: Eric Blake; +Cc: Kevin Wolf, Max Reitz, qemu-block, Qemu-devel
> On Aug 14, 2018, at 8:55 AM, Eric Blake <eblake@redhat.com> wrote:
>
> On 08/14/2018 03:40 AM, Kevin Wolf wrote:
>>> 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>.
>
> Indeed, that matches the approach that 'cvs --help' and 'git --help' have taken. I could live with a split along those lines as being something smarter. When you want to learn the options for 'create', you may have to ask two different --help commands to learn everything you need ['--help' didn't give me enough, but told me to use 'create --help'], but at least you are not inundated with answers irrelevant to the question you are asking, so you don't have to scroll through a wall of text.
I also like the idea. It seems very organized and neat.
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
2018-08-14 8:40 ` Kevin Wolf
2018-08-14 12:55 ` Eric Blake
@ 2018-08-17 1:27 ` Programmingkid
2018-08-17 13:44 ` Eric Blake
1 sibling, 1 reply; 11+ messages in thread
From: Programmingkid @ 2018-08-17 1:27 UTC (permalink / raw)
To: Kevin Wolf, Max Reitz; +Cc: Eric Blake, Qemu-block, Qemu-devel
> On Aug 14, 2018, at 4:40 AM, Kevin Wolf <kwolf@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
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
2018-08-17 1:27 ` Programmingkid
@ 2018-08-17 13:44 ` Eric Blake
2018-08-17 19:28 ` Programmingkid
0 siblings, 1 reply; 11+ messages in thread
From: Eric Blake @ 2018-08-17 13:44 UTC (permalink / raw)
To: Programmingkid, Kevin Wolf, Max Reitz; +Cc: Qemu-block, Qemu-devel
On 08/16/2018 08:27 PM, Programmingkid wrote:
> 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>
>
Just reviewing the first for now, to give you a feel for what to consider.
> 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.
Bad advice. We WANT users to use -f (if you don't, and the automatic
guessing sees something that is not raw, but your image SHOULD have been
-f raw, then you have a security hole: the guest can write anything into
a raw image to make the host access files it shouldn't based on
interpreting the raw file as something else). I'd drop the last
sentence, and use just the first.
>
> --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
Please spell that "-o help", not "-o ?". Otherwise, the user has to
quote the ? to avoid it globbing into any single-byte file lying around
in the current directory.
> 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.
Not your fault, but I don't like it when interfaces take mutually
exclusive operations but the last one does not win. Either '-p -q'
should behave like '-q', and '-q -p' behave like '-p' (because we accept
the mutual exclusion but last one wins), or both forms should error
(because they are incompatible). But having both forms silently behave
like '-q' is evil. So, as long as you're willing to patch up
interfaces, that's a project to consider.
>
> -t Specifies the cache mode that should be used with the
> destination file.
And what are those modes? If you're going to be wordy, then give the
user enough information to be useful. Otherwise, being terse in --help
is fine (and let the man page be wordy instead).
>
> Example:
> qemu-img amend -o compat=0.10 -f qcow2 image.qcow2
Where's an example with --image-opts and --object secret?
We're trying to move away from compat=0.10 (also spelled compat=v2), and
instead start encouraging compat=v3.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3266
Virtualization: qemu.org | libvirt.org
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
2018-08-17 13:44 ` Eric Blake
@ 2018-08-17 19:28 ` Programmingkid
2018-08-17 20:59 ` Eric Blake
0 siblings, 1 reply; 11+ messages in thread
From: Programmingkid @ 2018-08-17 19:28 UTC (permalink / raw)
To: Eric Blake; +Cc: Kevin Wolf, Max Reitz, Qemu-block, Qemu-devel
> On Aug 17, 2018, at 9:44 AM, Eric Blake <eblake@redhat.com> wrote:
>
> On 08/16/2018 08:27 PM, Programmingkid wrote:
>
>> 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>
>
> Just reviewing the first for now, to give you a feel for what to consider.
>
>> 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.
>
> Bad advice. We WANT users to use -f (if you don't, and the automatic guessing sees something that is not raw, but your image SHOULD have been -f raw, then you have a security hole: the guest can write anything into a raw image to make the host access files it shouldn't based on interpreting the raw file as something else). I'd drop the last sentence, and use just the first.
Ok.
>
>> --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
>
> Please spell that "-o help", not "-o ?". Otherwise, the user has to quote the ? to avoid it globbing into any single-byte file lying around in the current directory.
"-o ?" and "-o help" does not appear to work for this command. Maybe it should be removed.
This is what I tried:
qemu-img amend -o help
qemu-img amend -o ?
This is what I see in both instances: qemu-img: Expecting one image file name
>
>> 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.
>
> Not your fault, but I don't like it when interfaces take mutually exclusive operations but the last one does not win. Either '-p -q' should behave like '-q', and '-q -p' behave like '-p' (because we accept the mutual exclusion but last one wins), or both forms should error (because they are incompatible). But having both forms silently behave like '-q' is evil. So, as long as you're willing to patch up interfaces, that's a project to consider.
>
>> -t Specifies the cache mode that should be used with the
>> destination file.
>
> And what are those modes? If you're going to be wordy, then give the user enough information to be useful. Otherwise, being terse in --help is fine (and let the man page be wordy instead).
I don't know what the modes are. Anyone care to fill us in?
>> Example:
>> qemu-img amend -o compat=0.10 -f qcow2 image.qcow2
>
> Where's an example with --image-opts and --object secret?
I prefer examples that I think a user would actually use. The --image-opts and -object options are not necessary to use this command.
> We're trying to move away from compat=0.10 (also spelled compat=v2), and instead start encouraging compat=v3.
So you want this: qemu-img amend -o compat=v3 -f qcow2 image.qcow2
Thank you for reviewing my documentation.
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
2018-08-17 19:28 ` Programmingkid
@ 2018-08-17 20:59 ` Eric Blake
2018-08-18 16:48 ` Programmingkid
0 siblings, 1 reply; 11+ messages in thread
From: Eric Blake @ 2018-08-17 20:59 UTC (permalink / raw)
To: Programmingkid; +Cc: Kevin Wolf, Max Reitz, Qemu-block, Qemu-devel
On 08/17/2018 02:28 PM, Programmingkid wrote:
>>> -o Used with a comma separated list of format specific options in a
>>> name=value format. Use "-o ?" for an overview of the options
>>
>> Please spell that "-o help", not "-o ?". Otherwise, the user has to quote the ? to avoid it globbing into any single-byte file lying around in the current directory.
>
> "-o ?" and "-o help" does not appear to work for this command. Maybe it should be removed.
> This is what I tried:
> qemu-img amend -o help
> qemu-img amend -o ?
The set of options depends on the file format being amended. So, you
have to try:
qemu-img amend -o help -f qcow2
or supply an image name, as in:
qemu-img amend -o help myimage.qcow2
(of course, the latter relies on image probing, which I just said is
potentially unsafe if you didn't use -f). But the point is the option
-o does work, just not in isolation.
>>> -t Specifies the cache mode that should be used with the
>>> destination file.
>>
>> And what are those modes? If you're going to be wordy, then give the user enough information to be useful. Otherwise, being terse in --help is fine (and let the man page be wordy instead).
>
> I don't know what the modes are. Anyone care to fill us in?
The source code is your friend. qemu-img.c has:
case 'T':
cache = optarg;
...
ret = bdrv_parse_cache_mode(cache, &flags, &writethrough);
then you search for bdrv_parse_cache_mode(), in block.c:
if (!strcmp(mode, "off") || !strcmp(mode, "none")) {
*writethrough = false;
*flags |= BDRV_O_NOCACHE;
} else if (!strcmp(mode, "directsync")) {
*writethrough = true;
*flags |= BDRV_O_NOCACHE;
} else if (!strcmp(mode, "writeback")) {
*writethrough = false;
} else if (!strcmp(mode, "unsafe")) {
*writethrough = false;
*flags |= BDRV_O_NO_FLUSH;
} else if (!strcmp(mode, "writethrough")) {
*writethrough = true;
So six different aliases, for five different modes. We can either
improve --help output to document these directly, or add a '-t help'
option (the way we have '-o help') to dynamically print the list.
>
>
>>> Example:
>>> qemu-img amend -o compat=0.10 -f qcow2 image.qcow2
>>
>> Where's an example with --image-opts and --object secret?
>
> I prefer examples that I think a user would actually use. The --image-opts and -object options are not necessary to use this command.
Umm, they ARE necessary if you want to amend a LUKS-encrypted image, and
that IS something I would actually use. What's more, it's the complex
examples (like a LUKS-encrypted image) where seeing something spelled
out will save a LOT of hair-pulling from someone reading the docs (but,
alongside it should ALSO be a short-and-simple example).
>
>> We're trying to move away from compat=0.10 (also spelled compat=v2), and instead start encouraging compat=v3.
>
> So you want this: qemu-img amend -o compat=v3 -f qcow2 image.qcow2
Yes, that's one reasonable example, but should not be the only example.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3266
Virtualization: qemu.org | libvirt.org
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation
2018-08-17 20:59 ` Eric Blake
@ 2018-08-18 16:48 ` Programmingkid
0 siblings, 0 replies; 11+ messages in thread
From: Programmingkid @ 2018-08-18 16:48 UTC (permalink / raw)
To: Eric Blake; +Cc: Kevin Wolf, Max Reitz, Qemu-block, Qemu-devel
> On Aug 17, 2018, at 4:59 PM, Eric Blake <eblake@redhat.com> wrote:
>
> On 08/17/2018 02:28 PM, Programmingkid wrote:
>
>>>> -o Used with a comma separated list of format specific options in a
>>>> name=value format. Use "-o ?" for an overview of the options
>>>
>>> Please spell that "-o help", not "-o ?". Otherwise, the user has to quote the ? to avoid it globbing into any single-byte file lying around in the current directory.
>> "-o ?" and "-o help" does not appear to work for this command. Maybe it should be removed.
>> This is what I tried:
>> qemu-img amend -o help
>> qemu-img amend -o ?
>
> The set of options depends on the file format being amended. So, you have to try:
>
> qemu-img amend -o help -f qcow2
>
> or supply an image name, as in:
>
> qemu-img amend -o help myimage.qcow2
>
> (of course, the latter relies on image probing, which I just said is potentially unsafe if you didn't use -f). But the point is the option -o does work, just not in isolation.
>
>
>>>> -t Specifies the cache mode that should be used with the
>>>> destination file.
>>>
>>> And what are those modes? If you're going to be wordy, then give the user enough information to be useful. Otherwise, being terse in --help is fine (and let the man page be wordy instead).
>> I don't know what the modes are. Anyone care to fill us in?
>
> The source code is your friend. qemu-img.c has:
>
> case 'T':
> cache = optarg;
> ...
> ret = bdrv_parse_cache_mode(cache, &flags, &writethrough);
>
> then you search for bdrv_parse_cache_mode(), in block.c:
>
> if (!strcmp(mode, "off") || !strcmp(mode, "none")) {
> *writethrough = false;
> *flags |= BDRV_O_NOCACHE;
> } else if (!strcmp(mode, "directsync")) {
> *writethrough = true;
> *flags |= BDRV_O_NOCACHE;
> } else if (!strcmp(mode, "writeback")) {
> *writethrough = false;
> } else if (!strcmp(mode, "unsafe")) {
> *writethrough = false;
> *flags |= BDRV_O_NO_FLUSH;
> } else if (!strcmp(mode, "writethrough")) {
> *writethrough = true;
>
> So six different aliases, for five different modes. We can either improve --help output to document these directly, or add a '-t help' option (the way we have '-o help') to dynamically print the list.
>
>>>> Example:
>>>> qemu-img amend -o compat=0.10 -f qcow2 image.qcow2
>>>
>>> Where's an example with --image-opts and --object secret?
>> I prefer examples that I think a user would actually use. The --image-opts and -object options are not necessary to use this command.
>
> Umm, they ARE necessary if you want to amend a LUKS-encrypted image, and that IS something I would actually use. What's more, it's the complex examples (like a LUKS-encrypted image) where seeing something spelled out will save a LOT of hair-pulling from someone reading the docs (but, alongside it should ALSO be a short-and-simple example).
>
>>> We're trying to move away from compat=0.10 (also spelled compat=v2), and instead start encouraging compat=v3.
>> So you want this: qemu-img amend -o compat=v3 -f qcow2 image.qcow2
>
> Yes, that's one reasonable example, but should not be the only example.
Here is an improved version of the amend documentation:
usage: qemu-img amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt]
[-t cache] -o options filename
Command parameters:
-f The format of the image file.
--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 help" 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. Avoid using with the -q option.
-q Quiet mode - do not print any output (except errors). Avoid
using with the -p option.
-t Specifies the cache mode that should be used with the
destination file. Options are: none, writeback, writethrough,
directsync, and unsafe.
Example:
qemu-img amend -o compat=v3 -f qcow2 image.qcow2
qemu-img amend --object secret,id=sec0,data=test --image-opts \
driver=luks,key-secret=sec0,file.filename=test.luks -o size=2G
^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2018-08-18 16:57 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <20180730212249.16418-1-programmingkidx@gmail.com>
2018-07-31 0:55 ` [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation Programmingkid
2018-08-13 16:56 ` Max Reitz
2018-08-13 18:19 ` Eric Blake
2018-08-14 8:40 ` Kevin Wolf
2018-08-14 12:55 ` Eric Blake
2018-08-14 17:59 ` Programmingkid
2018-08-17 1:27 ` Programmingkid
2018-08-17 13:44 ` Eric Blake
2018-08-17 19:28 ` Programmingkid
2018-08-17 20:59 ` Eric Blake
2018-08-18 16:48 ` Programmingkid
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.