Document that 'svn cleanup' removes pristines (was: [vincent-svn at vinc17.net: Re: size of .svn/pristine directory (svn 1.7.x)])

[Stefan Sperling]

Forwarding this to the right list.

I'm not sure if we commonly reference URLs in the book as Vincent
is porposing here. So I'd remove that part.

But otherwise it looks fine to me and I think it's a good idea
to mention this feature.

----- Forwarded message from Vincent Lefevre <vincent-svn at vinc17.net> -----

Date: Tue, 10 Dec 2013 01:28:52 +0100
From: Vincent Lefevre <vincent-svn at vinc17.net>
To: users at subversion.apache.org
Subject: Re: size of .svn/pristine directory (svn 1.7.x)
Message-ID: <20131210002852.GB9245 at xvii.vinc17.org>
Content-Type: multipart/mixed; boundary="2fHTh5uZTiUOsy+g"
User-Agent: Mutt/1.5.21-6305-vl-r59709 (2013-04-16)
X-Spam-Score: (-2.6) BAYES_00,SPF_PASS

On 2013-12-09 17:37:28 +0100, Stefan Sperling wrote:
> On Mon, Dec 09, 2013 at 05:30:21PM +0100, Vincent Lefevre wrote:
> > I noticed that the size of the .svn/pristine directory can get huge
> > over time (several times the expected size). A "svn cleanup" solves
> > the problem, but
> > 1. this isn't documented (I'm wondering how many users know that);
> > 2. this isn't automatic.
> > 
> > About (2), svn could warn the user when a cleanup could be needed.
> > I don't know what is the best solution.
> > 
> > I've reported a bug on the Debian BTS about that:
> > 
> >   http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=731769
> 
> Where is the point in filing bugs with Debian about that?
> Are they going to do anything else than tracking related
> bug entries upstream?

Yes, sometimes they do. For instance, the change (which is some kind
of regression) could be announced in NEWS.Debian to make the user
aware of it (for new features, pointing to the release notes should
be sufficient). An optional cron script to check the working copies
could be useful too.

> There already is http://subversion.tigris.org/issues/show_bug.cgi?id=4071
> 
> Would you like to submit a documentation patch, for example to
> the svnbook? See http://svnbook.red-bean.com/

First, "svn help cleanup" currently says:

cleanup: Recursively clean up the working copy, removing locks, resuming
unfinished operations, etc.

I suggest to change it to something like:

cleanup: Recursively clean up the working copy, removing locks, resuming
unfinished operations, removing unreferenced pristines, etc.
In 1.7, we recommend to run "svn cleanup" periodically to reduce the size
of the working copy.

I've attached a patch for the svnbook (not tested).

-- 
Vincent Lefèvre <vincent at vinc17.net> - Web: <http://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <http://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Index: ch02-basic-usage.xml
===================================================================
--- ch02-basic-usage.xml	(revision 4563)
+++ ch02-basic-usage.xml	(working copy)
@@ -2892,6 +2892,21 @@
 
     </sect2>
 
+    <!-- =============================================================== -->
+    <sect2 id="svn.tour.cleanup.size">
+      <title>Reducing the Size of a Working Copy</title>
+
+      <para>Subversion 1.7 does not automatically remove pristines
+        that are no longer referenced. As a consequence, a working
+        copy can grow up to several times the size that is really
+        needed. We recommend to run <command>svn cleanup</command>
+        periodically in order to claim back the disk space of
+        unreferenced pristines<footnote><para>See <ulink
+        url="http://subversion.tigris.org/issues/show_bug.cgi?id=4071"
+        /> for details.</para></footnote>.</para>
+
+    </sect2>
+
   </sect1>
 
   <!-- ================================================================= -->


----- End forwarded message -----