Skip to content
Snippets Groups Projects
  • Hanna Reitz's avatar
    111fbd74
    qemu-img: Unify [-b [-F]] documentation · 111fbd74
    Hanna Reitz authored
    
    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 1899bf47).
    
    Reported-by: default avatarTingting Mao <timao@redhat.com>
    Signed-off-by: default avatarHanna Reitz <hreitz@redhat.com>
    Message-Id: <20220131135908.32393-1-hreitz@redhat.com>
    Signed-off-by: default avatarKevin Wolf <kwolf@redhat.com>
    111fbd74
    History
    qemu-img: Unify [-b [-F]] documentation
    Hanna Reitz authored
    
    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 1899bf47).
    
    Reported-by: default avatarTingting Mao <timao@redhat.com>
    Signed-off-by: default avatarHanna Reitz <hreitz@redhat.com>
    Message-Id: <20220131135908.32393-1-hreitz@redhat.com>
    Signed-off-by: default avatarKevin Wolf <kwolf@redhat.com>