Changeset
tools/virsh.pod | 238 +++++++++++++++++++++++++++++++++++++++-----------------
1 file changed, 168 insertions(+), 70 deletions(-)
Git apply log
Switched to a new branch '20180312211158.28343-1-jferlan@redhat.com'
Applying: virsh: Clean up formatting of the vol-create* commands
Applying: virsh: Fix man page argument ordering for vol-clone command
Applying: virsh: Fix man page argument ordering for vol-delete command
Applying: virsh: Fix man page argument ordering for vol-upload command
Applying: virsh: Fix man page argument ordering for vol-download command
Applying: virsh: Fix man page argument ordering for vol-wipe command
Applying: virsh: Fix man page argument ordering for vol-dumpxml command
Applying: virsh: Fix man page argument ordering for vol-info command
Applying: virsh: Clean up man page formatting for vol-list and vol-pool
Applying: virsh: Fix man page argument ordering for vol-{path|name|key} commands
Applying: tools: Clean up the vol-resize man page
To https://github.com/patchew-project/libvirt
 * [new tag]         patchew/20180312211158.28343-1-jferlan@redhat.com -> patchew/20180312211158.28343-1-jferlan@redhat.com
Test passed: syntax-check

loading

[libvirt] [PATCH 00/11] Make some virsh.pod adjustments for vol-* commands
Posted by John Ferlan, 14 weeks ago
Been reviewing documentation lately - ran into the virsh vol-* commands
and their "inconsistency" with the expected ordering of the command options.
Also the commands were largely a mash of sentences without regard for
any sort of readability.

John Ferlan (11):
  virsh: Clean up formatting of the vol-create* commands
  virsh: Fix man page argument ordering for vol-clone command
  virsh: Fix man page argument ordering for vol-delete command
  virsh: Fix man page argument ordering for vol-upload command
  virsh: Fix man page argument ordering for vol-download command
  virsh: Fix man page argument ordering for vol-wipe command
  virsh: Fix man page argument ordering for vol-dumpxml command
  virsh: Fix man page argument ordering for vol-info command
  virsh: Clean up man page formatting for vol-list and vol-pool
  virsh: Fix man page argument ordering for vol-{path|name|key} commands
  tools: Clean up the vol-resize man page

 tools/virsh.pod | 238 +++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 168 insertions(+), 70 deletions(-)

-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH 00/11] Make some virsh.pod adjustments for vol-* commands
Posted by Michal Privoznik, 14 weeks ago
On 03/12/2018 10:11 PM, John Ferlan wrote:
> Been reviewing documentation lately - ran into the virsh vol-* commands
> and their "inconsistency" with the expected ordering of the command options.
> Also the commands were largely a mash of sentences without regard for
> any sort of readability.
> 
> John Ferlan (11):
>   virsh: Clean up formatting of the vol-create* commands
>   virsh: Fix man page argument ordering for vol-clone command
>   virsh: Fix man page argument ordering for vol-delete command
>   virsh: Fix man page argument ordering for vol-upload command
>   virsh: Fix man page argument ordering for vol-download command
>   virsh: Fix man page argument ordering for vol-wipe command
>   virsh: Fix man page argument ordering for vol-dumpxml command
>   virsh: Fix man page argument ordering for vol-info command
>   virsh: Clean up man page formatting for vol-list and vol-pool
>   virsh: Fix man page argument ordering for vol-{path|name|key} commands
>   tools: Clean up the vol-resize man page
> 
>  tools/virsh.pod | 238 +++++++++++++++++++++++++++++++++++++++-----------------
>  1 file changed, 168 insertions(+), 70 deletions(-)
> 

ACK

Michal

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 01/11] virsh: Clean up formatting of the vol-create* commands
Posted by John Ferlan, 14 weeks ago
Clean up the formatting to make the output a bit more readable at
least with respect to not having one paragraph of output. Each
option will start on its own line.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 82de2cc45..52f45d721 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -3948,10 +3948,13 @@ before the event.
 =item B<vol-create> I<pool-or-uuid> I<FILE> [I<--prealloc-metadata>]
 
 Create a volume from an XML <file>.
+
 I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
+
 I<FILE> is the XML <file> with the volume definition. An easy way to create the
 XML <file> is to use the B<vol-dumpxml> command to obtain the definition of a
 pre-existing volume.
+
 [I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't
 support full allocation). This option creates a sparse image file with metadata,
 resulting in higher performance compared to images with no preallocation and
@@ -3963,53 +3966,66 @@ B<Example>
  vi newvolume.xml (or make changes with your other text editor)
  virsh vol-create differentstoragepool newvolume.xml
 
-=item B<vol-create-from> I<pool-or-uuid> I<FILE> [I<--inputpool>
-I<pool-or-uuid>] I<vol-name-or-key-or-path> [I<--prealloc-metadata>]
-[I<--reflink>]
+=item B<vol-create-from> I<pool-or-uuid> I<FILE> I<vol-name-or-key-or-path>
+[I<--inputpool> I<pool-or-uuid>]  [I<--prealloc-metadata>] [I<--reflink>]
 
 Create a volume, using another volume as input.
+
 I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
+
 I<FILE> is the XML <file> with the volume definition.
+
+I<vol-name-or-key-or-path> is the name or key or path of the source volume.
+
 I<--inputpool> I<pool-or-uuid> is the name or uuid of the storage pool the
 source volume is in.
-I<vol-name-or-key-or-path> is the name or key or path of the source volume.
+
 [I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't
 support full allocation). This option creates a sparse image file with metadata,
 resulting in higher performance compared to images with no preallocation and
 only slightly higher initial disk space usage.
+
 When I<--reflink> is specified, perform a COW lightweight copy,
 where the data blocks are copied only when modified.
 If this is not possible, the copy fails.
 
 =item B<vol-create-as> I<pool-or-uuid> I<name> I<capacity>
-[I<--allocation> I<size>] [I<--format> I<string>] [I<--backing-vol>
-I<vol-name-or-key-or-path>] [I<--backing-vol-format> I<string>]
-[I<--prealloc-metadata>] [I<--print-xml>]
+[I<--allocation> I<size>] [I<--format> I<string>]
+[I<--backing-vol> I<vol-name-or-key-or-path>]
+[I<--backing-vol-format> I<string>] [I<--prealloc-metadata>] [I<--print-xml>]
 
 Create a volume from a set of arguments unless I<--print-xml> is specified, in
 which case just the XML of the volume object is printed out without any actual
 object creation.
+
 I<pool-or-uuid> is the name or UUID of the storage pool to create the volume
 in.
+
 I<name> is the name of the new volume. For a disk pool, this must match the
 partition name as determined from the pool's source device path and the next
 available partition. For example, a source device path of /dev/sdb and there
 are no partitions on the disk, then the name must be sdb1 with the next
 name being sdb2 and so on.
+
 I<capacity> is the size of the volume to be created, as a scaled integer
 (see B<NOTES> above), defaulting to bytes if there is no suffix.
+
 I<--allocation> I<size> is the initial size to be allocated in the volume,
 also as a scaled integer defaulting to bytes.
+
 I<--format> I<string> is used in file based storage pools to specify the volume
 file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use extended for disk
 storage pools in order to create an extended partition (other values are
 validity checked but not preserved when libvirtd is restarted or the pool
 is refreshed).
+
 I<--backing-vol> I<vol-name-or-key-or-path> is the source backing
 volume to be used if taking a snapshot of an existing volume.
+
 I<--backing-vol-format> I<string> is the format of the snapshot backing volume;
 raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are, however, meant for
 file based storage pools.
+
 [I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't
 support full allocation). This option creates a sparse image file with metadata,
 resulting in higher performance compared to images with no preallocation and
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 02/11] virsh: Fix man page argument ordering for vol-clone command
Posted by John Ferlan, 14 weeks ago
The proper command order is 'virsh vol-clone source-vol target-vol pool'.
While making the modification clean up the description a bit too in
order to help clarify under what circumstances the source-vol could be
found if the pool name was not provided.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 52f45d721..ff3b0729e 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4031,19 +4031,27 @@ support full allocation). This option creates a sparse image file with metadata,
 resulting in higher performance compared to images with no preallocation and
 only slightly higher initial disk space usage.
 
-=item B<vol-clone> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
-I<name> [I<--prealloc-metadata>] [I<--reflink>]
+=item B<vol-clone> I<vol-name-or-key-or-path> I<name>
+[I<--pool> I<pool-or-uuid>] [I<--prealloc-metadata>] [I<--reflink>]
 
 Clone an existing volume within the parent pool.  Less powerful,
 but easier to type, version of B<vol-create-from>.
-I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool
-that contains the source volume, and will contain the new volume.
+
 I<vol-name-or-key-or-path> is the name or key or path of the source volume.
+
 I<name> is the name of the new volume.
+
+I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool
+that contains the source volume and will contain the new volume.
+If the source volume name is provided instead of the key or path, then
+providing the pool is necessary to find the volume to be cloned; otherwise,
+the first volume found by the key or path will be used.
+
 [I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't
 support full allocation). This option creates a sparse image file with metadata,
 resulting in higher performance compared to images with no preallocation and
 only slightly higher initial disk space usage.
+
 When I<--reflink> is specified, perform a COW lightweight copy,
 where the data blocks are copied only when modified.
 If this is not possible, the copy fails.
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 03/11] virsh: Fix man page argument ordering for vol-delete command
Posted by John Ferlan, 14 weeks ago
The proper command order is 'virsh vol-delete volume pool'. While
making the modification clean up the description a bit too in order
to help clarify under what circumstances the volume could be found
if the pool name was not provided.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index ff3b0729e..2d4416b44 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4056,13 +4056,18 @@ When I<--reflink> is specified, perform a COW lightweight copy,
 where the data blocks are copied only when modified.
 If this is not possible, the copy fails.
 
-=item B<vol-delete> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
+=item B<vol-delete> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>]
 [I<--delete-snapshots>]
 
 Delete a given volume.
-I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
-is in.
-I<vol-name-or-key-or-path> is the name or key or path of the volume to delete.
+
+I<vol-name-or-key-or-path> is the volume name or key or path of the volume
+to delete.
+
+[I<--pool> I<pool-or-uuid>] is the name or UUID of the storage pool the volume
+is in. If the volume name is provided instead of the key or path, then
+providing the pool is necessary to find the volume to be deleted; otherwise,
+the first volume found by the key or path will be used.
 
 The I<--delete-snapshots> flag specifies that any snapshots associated with
 the storage volume should be deleted as well. Not all storage drivers
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 04/11] virsh: Fix man page argument ordering for vol-upload command
Posted by John Ferlan, 14 weeks ago
The proper command order is 'virsh vol-upload volume file pool'. While
making the modification clean up the description a bit too in order
to help clarify under what circumstances the volume could be found
if the pool name was not provided.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 33 ++++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 11 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 2d4416b44..db871db9e 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4073,21 +4073,32 @@ The I<--delete-snapshots> flag specifies that any snapshots associated with
 the storage volume should be deleted as well. Not all storage drivers
 support this option, presently only rbd.
 
-=item B<vol-upload> [I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>]
-[I<--length> I<bytes>] [I<--sparse>] I<vol-name-or-key-or-path> I<local-file>
+=item B<vol-upload> I<vol-name-or-key-or-path> I<local-file>
+[I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>]
+[I<--length> I<bytes>] [I<--sparse>]
 
 Upload the contents of I<local-file> to a storage volume.
-I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
-is in.
+
 I<vol-name-or-key-or-path> is the name or key or path of the volume where the
-file will be uploaded.
-If I<--sparse> is specified, this command will preserve volume sparseness.
+I<local-file> will be uploaded.
+
+I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
+is in. If the volume name is provided instead of the key or path, then
+providing the pool is necessary to find the volume to be uploaded into;
+otherwise, the first volume found by the key or path will be used.
+
 I<--offset> is the position in the storage volume at which to start writing
-the data. The value must be 0 or larger. I<--length> is an upper bound
-of the amount of data to be uploaded. A negative value is interpreted
-as an unsigned long long value to essentially include everything from
-the offset to the end of the volume.
-An error will occur if the I<local-file> is greater than the specified length.
+the data. The value must be 0 or larger.
+
+I<--length> is an upper bound of the amount of data to be uploaded.
+A negative value is interpreted as an unsigned long long value to
+essentially include everything from the offset to the end of the volume.
+
+If I<--sparse> is specified, this command will preserve volume sparseness.
+
+An error will occur if the I<local-file> is greater than the specified
+I<length>.
+
 See the description for the libvirt virStorageVolUpload API for details
 regarding possible target volume and pool changes as a result of the
 pool refresh when the upload is attempted.
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 05/11] virsh: Fix man page argument ordering for vol-download command
Posted by John Ferlan, 14 weeks ago
The proper command order is 'virsh vol-download volume file pool'. While
making the modification clean up the description a bit too in order
to help clarify under what circumstances the volume could be found
if the pool name was not provided.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index db871db9e..d8cc64f36 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4103,19 +4103,28 @@ See the description for the libvirt virStorageVolUpload API for details
 regarding possible target volume and pool changes as a result of the
 pool refresh when the upload is attempted.
 
-=item B<vol-download> [I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>]
-[I<--length> I<bytes>] [I<--sparse>] I<vol-name-or-key-or-path> I<local-file>
+=item B<vol-download> I<vol-name-or-key-or-path> I<local-file>
+[I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>] [I<--length> I<bytes>]
+[I<--sparse>]
 
 Download the contents of a storage volume to I<local-file>.
+
+I<vol-name-or-key-or-path> is the name or key or path of the volume to
+download into I<local-file>.
+
 I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
-is in.
-I<vol-name-or-key-or-path> is the name or key or path of the volume to download.
-If I<--sparse> is specified, this command will preserve volume sparseness.
+is in. If the volume name is provided instead of the key or path, then
+providing the pool is necessary to find the volume to be uploaded into;
+otherwise, the first volume found by the key or path will be used.
+
 I<--offset> is the position in the storage volume at which to start reading
-the data. The value must be 0 or larger. I<--length> is an upper bound of
-the amount of data to be downloaded. A negative value is interpreted as
-an unsigned long long value to essentially include everything from the
-offset to the end of the volume.
+the data. The value must be 0 or larger.
+
+I<--length> is an upper bound of the amount of data to be downloaded.
+A negative value is interpreted as an unsigned long long value to
+essentially include everything from the offset to the end of the volume.
+
+If I<--sparse> is specified, this command will preserve volume sparseness.
 
 =item B<vol-wipe> [I<--pool> I<pool-or-uuid>] [I<--algorithm> I<algorithm>]
 I<vol-name-or-key-or-path>
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 06/11] virsh: Fix man page argument ordering for vol-wipe command
Posted by John Ferlan, 14 weeks ago
The proper command order is 'virsh vol-wipe volume pool algorithm'. While
making the modification clean up the description a bit too in order
to help clarify under what circumstances the volume could be found
if the pool name was not provided.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index d8cc64f36..24177e407 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4126,15 +4126,23 @@ essentially include everything from the offset to the end of the volume.
 
 If I<--sparse> is specified, this command will preserve volume sparseness.
 
-=item B<vol-wipe> [I<--pool> I<pool-or-uuid>] [I<--algorithm> I<algorithm>]
-I<vol-name-or-key-or-path>
+=item B<vol-wipe> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>]
+[I<--algorithm> I<algorithm>]
 
 Wipe a volume, ensure data previously on the volume is not accessible to
-future reads. I<--pool> I<pool-or-uuid> is the name or UUID of the storage
-pool the volume is in.
+future reads.
+
 I<vol-name-or-key-or-path> is the name or key or path of the volume to wipe.
 It is possible to choose different wiping algorithms instead of re-writing
-volume with zeroes. This can be done via I<--algorithm> switch.
+volume with zeroes.
+
+I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the
+volume is in. If the volume name is provided instead of the key or path,
+then providing the pool is necessary to find the volume to be wiped;
+otherwise, the first volume found by the key or path will be used.
+
+Use the I<--algorithm> switch choosing from the list of the following
+algorithms in order to define which algorithm to use for the wipe.
 
 B<Supported algorithms>
   zero       - 1-pass all zeroes
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 07/11] virsh: Fix man page argument ordering for vol-dumpxml command
Posted by John Ferlan, 14 weeks ago
The proper command order is 'virsh vol-dumpxml volume pool'. While
making the modification clean up the description a bit too in order
to help clarify under what circumstances the volume could be found
if the pool name was not provided.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 24177e407..135cce841 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4178,12 +4178,17 @@ it expects the storage driver to be able to discard all bytes in a
 volume. It is up to the storage driver to handle how the discarding
 occurs. Not all storage drivers or volume types can support 'trim'.
 
-=item B<vol-dumpxml> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
+=item B<vol-dumpxml> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>]
 
 Output the volume information as an XML dump to stdout.
+
+I<vol-name-or-key-or-path> is the name or key or path of the volume
+to output the XML.
+
 I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
-is in. I<vol-name-or-key-or-path> is the name or key or path of the volume
-to output the XML of.
+is in. If the volume name is provided instead of the key or path, then
+providing the pool is necessary to find the volume to be uploaded into;
+otherwise, the first volume found by the key or path will be used.
 
 =item B<vol-info> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
 [I<--bytes>] [I<--physical>]
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 08/11] virsh: Fix man page argument ordering for vol-info command
Posted by John Ferlan, 14 weeks ago
The proper command order is 'virsh vol-info volume pool'. While
making the modification clean up the description a bit too in order
to help clarify under what circumstances the volume could be found
if the pool name was not provided.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 135cce841..cd1ccc6fa 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4190,17 +4190,26 @@ is in. If the volume name is provided instead of the key or path, then
 providing the pool is necessary to find the volume to be uploaded into;
 otherwise, the first volume found by the key or path will be used.
 
-=item B<vol-info> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
+=item B<vol-info> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>]
 [I<--bytes>] [I<--physical>]
 
 Returns basic information about the given storage volume.
+
+I<vol-name-or-key-or-path> is the name or key or path of the volume
+to return information for.
+
 I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
-is in. I<vol-name-or-key-or-path> is the name or key or path of the volume
-to return information for. If I<--bytes> is specified the sizes are not
-converted to human friendly units. If I<--physical> is specified, then the host
-physical size is returned and displayed instead of the allocation value. The
-physical value for some file types, such as qcow2 may have a different (larger)
-physical value than is shown for allocation. Additionally sparse files will
+is in. If the volume name is provided instead of the key or path, then
+providing the pool is necessary to find the volume to be uploaded into;
+otherwise, the first volume found by the key or path will be used.
+
+If I<--bytes> is specified the sizes are not converted to human friendly
+units.
+
+If I<--physical> is specified, then the host physical size is returned
+and displayed instead of the allocation value. The physical value for
+some file types, such as qcow2 may have a different (larger) physical
+value than is shown for allocation. Additionally sparse files will
 have different physical and allocation values.
 
 =item B<vol-list> [I<--pool> I<pool-or-uuid>] [I<--details>]
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 09/11] virsh: Clean up man page formatting for vol-list and vol-pool
Posted by John Ferlan, 14 weeks ago
Make the output more readable.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index cd1ccc6fa..1b59251bf 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4215,16 +4215,21 @@ have different physical and allocation values.
 =item B<vol-list> [I<--pool> I<pool-or-uuid>] [I<--details>]
 
 Return the list of volumes in the given storage pool.
+
 I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool.
+
 The I<--details> option instructs virsh to additionally display volume
 type and capacity related information where available.
 
-=item B<vol-pool> [I<--uuid>] I<vol-key-or-path>
+=item B<vol-pool> I<vol-key-or-path> [I<--uuid>]
 
 Return the pool name or UUID for a given volume. By default, the pool name is
-returned. If the I<--uuid> option is given, the pool UUID is returned instead.
+returned.
+
 I<vol-key-or-path> is the key or path of the volume to return the pool
-information for.
+information.
+
+If the I<--uuid> option is given, the pool UUID is returned instead.
 
 =item B<vol-path> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key>
 
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 10/11] virsh: Fix man page argument ordering for vol-{path|name|key} commands
Posted by John Ferlan, 14 weeks ago
The proper command order is 'virsh vol-path volume pool', or
'virsh vol-name volume pool', or 'virsh vol-key volume'. While
making the modification clean up the description a bit too in order
to help clarify under what circumstances the volume could be found
if the pool name was not provided.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 1b59251bf..366a628f9 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4231,24 +4231,34 @@ information.
 
 If the I<--uuid> option is given, the pool UUID is returned instead.
 
-=item B<vol-path> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key>
+=item B<vol-path> I<vol-name-or-key> [I<--pool> I<pool-or-uuid>]
 
 Return the path for a given volume.
+
+I<vol-name-or-key> is the name or key of the volume to return the path.
+
 I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
-is in.
-I<vol-name-or-key> is the name or key of the volume to return the path for.
+is in. If the volume name is provided instead of the key, then providing
+the pool is necessary to find the volume to be uploaded into; otherwise,
+the first volume found by the key will be used.
 
 =item B<vol-name> I<vol-key-or-path>
 
 Return the name for a given volume.
-I<vol-key-or-path> is the key or path of the volume to return the name for.
 
-=item B<vol-key> [I<--pool> I<pool-or-uuid>] I<vol-name-or-path>
+I<vol-key-or-path> is the key or path of the volume to return the name.
+
+=item B<vol-key> I<vol-name-or-path> [I<--pool> I<pool-or-uuid>]
 
 Return the volume key for a given volume.
+
+I<vol-name-or-path> is the name or path of the volume to return the
+volume key.
+
 I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
-is in. I<vol-name-or-path> is the name or path of the volume to return the
-volume key for.
+is in. If the volume name is provided instead of the path, then providing
+the pool is necessary to find the volume to be uploaded into; otherwise,
+the first volume found by the path will be used.
 
 =item B<vol-resize> I<vol-name-or-path> I<capacity> [I<--pool> I<pool-or-uuid>]
 [I<--allocate>] [I<--delta>] [I<--shrink>]
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH 11/11] tools: Clean up the vol-resize man page
Posted by John Ferlan, 14 weeks ago
Instead of appearing as one long paragraph, split the output to list
each command option on its own line for better readability.

Signed-off-by: John Ferlan <jferlan@redhat.com>
---
 tools/virsh.pod | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 366a628f9..d3ae7bb5d 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4264,17 +4264,29 @@ the first volume found by the path will be used.
 [I<--allocate>] [I<--delta>] [I<--shrink>]
 
 Resize the capacity of the given volume, in bytes.
+
+I<vol-name-or-key-or-path> is the name or key or path of the volume
+to resize.
+
+I<capacity> is a scaled integer (see B<NOTES> above) for the volume,
+which defaults to bytes if there is no suffix.
+
 I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
-is in. I<vol-name-or-key-or-path> is the name or key or path of the volume
-to resize.  The new capacity might be sparse unless I<--allocate> is
-specified.  Normally, I<capacity> is the new size, but if I<--delta>
-is present, then it is added to the existing size.  Attempts to shrink
-the volume will fail unless I<--shrink> is present; I<capacity> cannot
-be negative unless I<--shrink> is provided, but a negative sign is not
-necessary. I<capacity> is a scaled integer (see B<NOTES> above), which
-defaults to bytes if there is no suffix.  This command is only safe
-for storage volumes not in use by an active guest; see also
-B<blockresize> for live resizing.
+is in. If the volume name is provided instead of the key or path, then
+providing the pool is necessary to find the volume to be uploaded into;
+otherwise, the first volume found by the key or path will be used.
+
+The new I<capacity> might be sparse unless I<--allocate> is specified.
+
+Normally, I<capacity> is the new size, but if I<--delta>
+is present, then it is added to the existing size.
+
+Attempts to shrink the volume will fail unless I<--shrink> is present.
+The I<capacity> cannot be negative unless I<--shrink> is provided, but
+a negative sign is not necessary.
+
+This command is only safe for storage volumes not in use by an active
+guest; see also B<blockresize> for live resizing.
 
 =back
 
-- 
2.13.6

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list