From cd1627e8041ffa06764ef82b984f4291660edcc9 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Sat, 18 Aug 2012 22:27:17 +0100
Subject: FAQ: virt-sparsify and raw sparse output.

---
 examples/guestfs-faq.pod   | 19 +++++++++++++++++++
 sparsify/virt-sparsify.pod | 13 +++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/examples/guestfs-faq.pod b/examples/guestfs-faq.pod
index 7ca534ab..28257437 100644
--- a/examples/guestfs-faq.pod
+++ b/examples/guestfs-faq.pod
@@ -405,6 +405,25 @@ C<$TMPDIR/.guestfs-E<lt>UIDE<gt>> is used instead.
 
 It is safe to delete this directory when you are not using libguestfs.
 
+=head2 virt-sparsify seems to make the image grow to the
+full size of the virtual disk
+
+If the input to L<virt-sparsify(1)> is raw, then the output will be
+raw sparse.  Make sure you are measuring the output with a tool which
+understands sparseness such as C<du-sh>.  It can make a huge difference:
+
+ $ ls -lh test1.img
+ -rw-rw-r--. 1 rjones rjones 100M Aug  8 08:08 test1.img
+ $ du -sh test1.img
+ 3.6M	test1.img
+
+(Compare the apparent size B<100M> vs the actual size B<3.6M>)
+
+If all this confuses you, use a non-sparse output by specifying the
+I<--convert> option, eg:
+
+ virt-sparsify --convert qcow2 disk.raw disk.qcow2
+
 =head1 USING LIBGUESTFS IN YOUR OWN PROGRAMS
 
 =head2 The API has hundreds of methods, where do I start?
diff --git a/sparsify/virt-sparsify.pod b/sparsify/virt-sparsify.pod
index 14f7eecb..b716350b 100644
--- a/sparsify/virt-sparsify.pod
+++ b/sparsify/virt-sparsify.pod
@@ -25,6 +25,19 @@ Virt-sparsify can operate on any disk image, not just ones from
 virtual machines.  If a virtual machine has more than one attached
 disk, you must sparsify each one separately.
 
+=head2 IMPORTANT NOTE ABOUT SPARSE OUTPUT IMAGES
+
+If the input is raw, then the default output is raw sparse.  B<You
+must check the output size using a tool that understands sparseness>
+such as C<du -sh>.  It can make a huge difference:
+
+ $ ls -lh test1.img
+ -rw-rw-r--. 1 rjones rjones 100M Aug  8 08:08 test1.img
+ $ du -sh test1.img
+ 3.6M	test1.img
+
+(Compare the apparent size B<100M> vs the actual size B<3.6M>)
+
 =head2 IMPORTANT LIMITATIONS
 
 =over 4
-- 
cgit