Skip to contentSkip to conversation

qemu-img: Unify [-b [-F]] documentation

PATCH Applied Hanna Reitz 3 participants 3 messages Jan 31, 2022 – Feb 1, 2022

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 qemu-img: Unify [-b [-F]] documentation

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).

---
 docs/tools/qemu-img.rst | 2 +-
 qemu-img-cmds.hx        | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)
docs/tools/qemu-img.rst +1 -1
index d663dd92bd..8885ea11cf 100644
@@ -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*
qemu-img-cmds.hx +2 -2
index 72bcdcfbfa..1b1dab5b17 100644
@@ -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,
Signature · 1 line
2.34.1
Applied
#1 lore raw

Am 31.01.2022 um 14:59 hat Hanna Reitz geschrieben:

Quoted 22 lines

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
Quoted 6 lines

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).

Thanks, applied to the block branch.

Kevin

Reviewed-by on v1 1/1
#2 lore raw
In reply to Hanna Reitz
Quoted 22 lines · Hanna Reitz

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
Quoted 6 lines

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).

Signature · 2 lines
Best regards,
Vladimir