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