[svnbook] r4004 committed - For Issue 59 ("'svnsync init' supports a --allow-non-empty flag in...

[svnbook at googlecode.com]

Revision: 4004
Author:   cmpilato at gmail.com
Date:     Tue Aug 16 12:18:15 2011
Log:      For Issue 59 ("'svnsync init' supports a --allow-non-empty flag in
Subversion 1.7"):

* en/book/ch09-reference.xml
   Note the new 'svnsync initialize --allow-non-empty' option with a
   brief description of its utility.

http://code.google.com/p/svnbook/source/detail?r=4004

Modified:
  /trunk/en/book/ch09-reference.xml

=======================================
--- /trunk/en/book/ch09-reference.xml	Mon Aug 15 12:33:48 2011
+++ /trunk/en/book/ch09-reference.xml	Tue Aug 16 12:18:15 2011
@@ -7900,6 +7900,16 @@

        <variablelist>

+        <varlistentry>
+          <term><option>--allow-non-empty</option></term>
+          <listitem>
+            <para>Disables the verification (which <command>svnsync
+              initialize</command> performs by default) that the
+              repository being initialized is empty of history
+              version.</para>
+          </listitem>
+        </varlistentry>
+
          <varlistentry>
            <term><option>--config-dir</option>
              <replaceable>DIR</replaceable></term>
@@ -8196,10 +8206,8 @@
            <title>Description</title>

            <para><command>svnsync initialize</command> verifies that a
-            repository meets the requirements of a new mirror
-            repository—that it has no previous existing version
-            history and that it allows revision property
-            modifications—and records the initial administrative
+            repository meets the basic requirements of a new mirror
+            repository and records the initial administrative
              information that associates the mirror repository with the
              source repository (specified
              by <replaceable>SOURCE_URL</replaceable>).  This is the
@@ -8213,6 +8221,30 @@
              mirroring, though — simply specify the URL of the
              source repository subdirectory you wish to mirror
              as <replaceable>SOURCE_URL</replaceable>.</para>
+
+          <para>By default, the aforementioned basic requirements of a
+            mirror are that it allows revision property modifications
+            and that it contains no version history.  However, as of
+            Subversion 1.7, you may now optionally disable the
+            verification that the target repository is empty using
+            the <option>--allow-non-empty</option> option.  While the
+            use of this option should not become habitual (as it
+            bypasses a valuable safeguard mechanism), it does aid in
+            one very common use-case: initializing a copy of a
+            repository as a mirror of the original.  This is
+            especially useful when setting up new mirrors of
+            repositories which contain a large amount of version
+            history.  Rather than initialize a brand new repository as
+            a mirror and then syncronize all of the history into it,
+            administrators will find that it
+            <emphasis>significantly</emphasis> faster to first make a
+            copy of a mature repository (perhaps
+            using <command>svnadmin hotcopy</command>) and then
+            use <command>svnsync initialize
+            --allow-non-empty</command> to initialize that copy as a
+            mirror which is now already up-to-date with the
+            original.</para>
+
          </refsect1>

          <refsect1>