Re: [Qemu-devel] [Qemu-block] [PATCH v2] qemu-img: Clarify about relative backing file options

[Jeff Cody <jcody@redhat.com>]

On Fri, Aug 04, 2017 at 10:36:58PM +0800, Fam Zheng wrote:
> It's not too surprising when a user specifies the backing file relative
> to the current working directory instead of the top layer image. This
> causes error when they differ. Though the error message has enough
> information to infer the fact about the misunderstanding, it is better
> if we document this explicitly, so that users don't have to learn from
> mistakes.
> 
> Signed-off-by: Fam Zheng <famz@redhat.com>
> 
> ---
> v2: Improve wording. [Eric]
> ---
>  qemu-img.texi | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/qemu-img.texi b/qemu-img.texi
> index 72dabd6b3e..90c7eab4a8 100644
> --- a/qemu-img.texi
> +++ b/qemu-img.texi
> @@ -244,6 +244,9 @@ only the differences from @var{backing_file}. No size needs to be specified in
>  this case. @var{backing_file} will never be modified unless you use the
>  @code{commit} monitor command (or qemu-img commit).
>  
> +If a relative path name is given, the backing file is looked up relative to
> +the directory containing @var{filename}.
> +
>  Note that a given backing file will be opened to check that it is valid. Use
>  the @code{-u} option to enable unsafe backing file mode, which means that the
>  image will be created even if the associated backing file cannot be opened. A
> @@ -343,6 +346,9 @@ created as a copy on write image of the specified base image; the
>  @var{backing_file} should have the same content as the input's base image,
>  however the path, image format, etc may differ.
>  
> +If a relative path name is given, the backing file is looked up relative to
> +the directory containing @var{output_filename}.
> +
>  If the @code{-n} option is specified, the target volume creation will be
>  skipped. This is useful for formats such as @code{rbd} if the target
>  volume has already been created with site specific options that cannot
> @@ -490,6 +496,9 @@ The backing file is changed to @var{backing_file} and (if the image format of
>  string), then the image is rebased onto no backing file (i.e. it will exist
>  independently of any backing file).
>  
> +If a relative path name is given, the backing file is looked up relative to
> +the directory containing @var{filename}.
> +
>  @var{cache} specifies the cache mode to be used for @var{filename}, whereas
>  @var{src_cache} specifies the cache mode for reading backing files.
>  
> -- 
> 2.13.3
> 
> 

Reviewed-by: Jeff Cody <jcody@redhat.com>