| Message ID | 20220131135908.32393-1-hreitz@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | qemu-img: Unify [-b [-F]] documentation | expand |
Am 31.01.2022 um 14:59 hat Hanna Reitz geschrieben: > qemu-img convert documents the backing file and backing format options > as follows: > [-B backing_file [-F backing_fmt]] > whereas qemu-img create has this: > [-b backing_file] [-F backing_fmt] > > That is, for convert, we document that -F cannot be given without -B, > while for create, way say that they are independent. > > Indeed, it is technically possible to give -F without -b, because it is > left to the block driver to decide whether this is an error or not, so > sometimes it is: > > $ qemu-img create -f qed -F qed test.qed 64M > Formatting 'test.qed', fmt=qed size=67108864 backing_fmt=qed [...] > > And sometimes it is not: > > $ qemu-img create -f qcow2 -F qcow2 test.qcow2 64M > Formatting 'test.qcow2', fmt=qcow2 cluster_size=65536 [...] > qemu-img: test.qcow2: Backing format cannot be used without backing file > > Generally, it does not make much sense, though, and users should only > give -F with -b, so document it that way, as we have already done for > qemu-img convert (commit 1899bf47375ad40555dcdff12ba49b4b8b82df38). > > Reported-by: Tingting Mao <timao@redhat.com> > Signed-off-by: Hanna Reitz <hreitz@redhat.com> Thanks, applied to the block branch. Kevin
31.01.2022 16:59, Hanna Reitz wrote: > qemu-img convert documents the backing file and backing format options > as follows: > [-B backing_file [-F backing_fmt]] > whereas qemu-img create has this: > [-b backing_file] [-F backing_fmt] > > That is, for convert, we document that -F cannot be given without -B, > while for create, way say that they are independent. > > Indeed, it is technically possible to give -F without -b, because it is > left to the block driver to decide whether this is an error or not, so > sometimes it is: > > $ qemu-img create -f qed -F qed test.qed 64M > Formatting 'test.qed', fmt=qed size=67108864 backing_fmt=qed [...] > > And sometimes it is not: > > $ qemu-img create -f qcow2 -F qcow2 test.qcow2 64M > Formatting 'test.qcow2', fmt=qcow2 cluster_size=65536 [...] > qemu-img: test.qcow2: Backing format cannot be used without backing file > > Generally, it does not make much sense, though, and users should only > give -F with -b, so document it that way, as we have already done for > qemu-img convert (commit 1899bf47375ad40555dcdff12ba49b4b8b82df38). > > Reported-by: Tingting Mao<timao@redhat.com> > Signed-off-by: Hanna Reitz<hreitz@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst index d663dd92bd..8885ea11cf 100644 --- a/docs/tools/qemu-img.rst +++ b/docs/tools/qemu-img.rst @@ -463,7 +463,7 @@ Command description: ``--skip-broken-bitmaps`` is also specified to copy only the consistent bitmaps. -.. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE] [-F BACKING_FMT] [-u] [-o OPTIONS] FILENAME [SIZE] +.. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE [-F BACKING_FMT]] [-u] [-o OPTIONS] FILENAME [SIZE] Create the new disk image *FILENAME* of size *SIZE* and format *FMT*. Depending on the file format, you can add one or more *OPTIONS* diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx index 72bcdcfbfa..1b1dab5b17 100644 --- a/qemu-img-cmds.hx +++ b/qemu-img-cmds.hx @@ -52,9 +52,9 @@ SRST ERST DEF("create", img_create, - "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]") + "create [--object objectdef] [-q] [-f fmt] [-b backing_file [-F backing_fmt]] [-u] [-o options] filename [size]") SRST -.. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE] [-F BACKING_FMT] [-u] [-o OPTIONS] FILENAME [SIZE] +.. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE [-F BACKING_FMT]] [-u] [-o OPTIONS] FILENAME [SIZE] ERST DEF("dd", img_dd,
qemu-img convert documents the backing file and backing format options as follows: [-B backing_file [-F backing_fmt]] whereas qemu-img create has this: [-b backing_file] [-F backing_fmt] That is, for convert, we document that -F cannot be given without -B, while for create, way say that they are independent. Indeed, it is technically possible to give -F without -b, because it is left to the block driver to decide whether this is an error or not, so sometimes it is: $ qemu-img create -f qed -F qed test.qed 64M Formatting 'test.qed', fmt=qed size=67108864 backing_fmt=qed [...] And sometimes it is not: $ qemu-img create -f qcow2 -F qcow2 test.qcow2 64M Formatting 'test.qcow2', fmt=qcow2 cluster_size=65536 [...] qemu-img: test.qcow2: Backing format cannot be used without backing file Generally, it does not make much sense, though, and users should only give -F with -b, so document it that way, as we have already done for qemu-img convert (commit 1899bf47375ad40555dcdff12ba49b4b8b82df38). Reported-by: Tingting Mao <timao@redhat.com> Signed-off-by: Hanna Reitz <hreitz@redhat.com> --- docs/tools/qemu-img.rst | 2 +- qemu-img-cmds.hx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-)