> On Aug 17, 2018, at 9:44 AM, Eric Blake <ebl...@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.