> On Aug 17, 2018, at 4:59 PM, Eric Blake <ebl...@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