[Top][All Lists]

[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: Eric Blake
Subject: Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation
Date: Fri, 17 Aug 2018 08:44:56 -0500
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.9.1

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.


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

  -o             Used with a comma separated list of format specific options in 
                 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 
                 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 
                 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).

     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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]