[svnbook] r4034 committed - Indentation fixes only.
svnbook at googlecode.com
svnbook at googlecode.com
Thu Aug 25 08:50:04 CDT 2011
Revision: 4034
Author: cmpilato at gmail.com
Date: Thu Aug 25 06:48:50 2011
Log: Indentation fixes only.
http://code.google.com/p/svnbook/source/detail?r=4034
Modified:
/trunk/en/book/ch05-repository-admin.xml
=======================================
--- /trunk/en/book/ch05-repository-admin.xml Wed Aug 24 13:29:44 2011
+++ /trunk/en/book/ch05-repository-admin.xml Thu Aug 25 06:48:50 2011
@@ -2599,121 +2599,120 @@
<sect3 id="svn.reposadmin.maint.replication.svnsync">
<title>Replication with svnsync</title>
- <para>Assuming you already have a source repository that you'd
- like to mirror, the next thing you need is a target repository
- that will actually serve as that mirror. This target
- repository can use either of the available filesystem
- data-store backends (see
- <xref linkend="svn.reposadmin.basics.backends"
- />)—Subversion's abstraction layers ensure that such
- details don't matter. But by default, it must
- not yet have any version history in it. (We'll discuss an
- exception to this later in this section.)</para>
-
- <para>The protocol that <command>svnsync</command> uses to
- communicate revision information is highly sensitive to
- mismatches between the versioned histories contained in the
- source and target repositories. For this reason,
- while <command>svnsync</command>
- cannot <emphasis>demand</emphasis> that the target repository
- be read-only,<footnote><para>In fact, it can't truly be
- read-only, or <command>svnsync</command> itself would have a
- tough time copying revision history into it.</para></footnote>
- allowing the revision history in the target repository to
- change by any mechanism other than the mirroring process is a
- recipe for disaster.</para>
-
- <warning>
- <para>Do <emphasis>not</emphasis> modify a mirror repository
- in such a way as to cause its version history to deviate
- from that of the repository it mirrors. The only commits
- and revision property modifications that ever occur on that
- mirror repository should be those performed by the
- <command>svnsync</command> tool.</para>
- </warning>
-
- <para>Another requirement of the target repository is that the
- <command>svnsync</command> process be allowed to modify
- revision properties. Because <command>svnsync</command> works
- within the framework of that repository's hook system, the
- default state of the repository (which is to disallow revision
- property changes; see <xref
- linkend="svn.ref.reposhooks.pre-revprop-change" />) is
- insufficient. You'll need to explicitly implement the
- pre-revprop-change hook, and your script must allow
- <command>svnsync</command> to set and change revision
- properties. With those provisions in place, you are ready to
- start mirroring repository revisions.</para>
-
- <tip>
- <para>It's a good idea to implement authorization measures
- that allow your repository replication process to perform
- its tasks while preventing other users from modifying the
- contents of your mirror repository at all.</para>
- </tip>
-
- <para>Let's walk through the use of <command>svnsync</command>
- in a somewhat typical mirroring scenario. We'll pepper this
- discourse with practical recommendations, which you are free to
- disregard if they aren't required by or suitable for your
- environment.</para>
-
- <para>As a service to the fine developers of our favorite
- version control system, we will be mirroring the public
- Subversion source code repository and exposing that mirror
- publicly on the Internet, hosted on a different machine than
- the one on which the original Subversion source code
- repository lives. This remote host has a global configuration
- that permits anonymous users to read the contents of
- repositories on the host, but requires users to authenticate
- to modify those repositories. (Please forgive us for
- glossing over the details of Subversion server configuration
- for the moment—those are covered thoroughly in <xref
- linkend="svn.serverconfig" />.) And for no other reason than
- that it makes for a more interesting example, we'll be driving
- the replication process from a third machine—the one that
- we currently find ourselves using.</para>
-
- <para>First, we'll create the repository which will be our
- mirror. This and the next couple of steps do require shell
- access to the machine on which the mirror repository will
- live. Once the repository is all configured, though, we
- shouldn't need to touch it directly again.</para>
-
- <informalexample>
- <screen>
+ <para>Assuming you already have a source repository that you'd
+ like to mirror, the next thing you need is a target repository
+ that will actually serve as that mirror. This target
+ repository can use either of the available filesystem
+ data-store backends (see
+ <xref linkend="svn.reposadmin.basics.backends"
+ />)—Subversion's abstraction layers ensure that such
+ details don't matter. But by default, it must
+ not yet have any version history in it. (We'll discuss an
+ exception to this later in this section.)</para>
+
+ <para>The protocol that <command>svnsync</command> uses to
+ communicate revision information is highly sensitive to
+ mismatches between the versioned histories contained in the
+ source and target repositories. For this reason,
+ while <command>svnsync</command>
+ cannot <emphasis>demand</emphasis> that the target repository
+ be read-only,<footnote><para>In fact, it can't truly be
+ read-only, or <command>svnsync</command> itself would have a
+ tough time copying revision history into it.</para></footnote>
+ allowing the revision history in the target repository to
+ change by any mechanism other than the mirroring process is a
+ recipe for disaster.</para>
+
+ <warning>
+ <para>Do <emphasis>not</emphasis> modify a mirror repository
+ in such a way as to cause its version history to deviate
+ from that of the repository it mirrors. The only commits
+ and revision property modifications that ever occur on that
+ mirror repository should be those performed by the
+ <command>svnsync</command> tool.</para>
+ </warning>
+
+ <para>Another requirement of the target repository is that the
+ <command>svnsync</command> process be allowed to modify
+ revision properties. Because <command>svnsync</command> works
+ within the framework of that repository's hook system, the
+ default state of the repository (which is to disallow revision
+ property changes; see <xref
+ linkend="svn.ref.reposhooks.pre-revprop-change" />) is
+ insufficient. You'll need to explicitly implement the
+ pre-revprop-change hook, and your script must allow
+ <command>svnsync</command> to set and change revision
+ properties. With those provisions in place, you are ready to
+ start mirroring repository revisions.</para>
+
+ <tip>
+ <para>It's a good idea to implement authorization measures
+ that allow your repository replication process to perform
+ its tasks while preventing other users from modifying the
+ contents of your mirror repository at all.</para>
+ </tip>
+
+ <para>Let's walk through the use of <command>svnsync</command>
+ in a somewhat typical mirroring scenario. We'll pepper this
+ discourse with practical recommendations, which you are free to
+ disregard if they aren't required by or suitable for your
+ environment.</para>
+
+ <para>As a service to the fine developers of our favorite
+ version control system, we will be mirroring the public
+ Subversion source code repository and exposing that mirror
+ publicly on the Internet, hosted on a different machine than
+ the one on which the original Subversion source code
+ repository lives. This remote host has a global configuration
+ that permits anonymous users to read the contents of
+ repositories on the host, but requires users to authenticate
+ to modify those repositories. (Please forgive us for
+ glossing over the details of Subversion server configuration
+ for the moment—those are covered thoroughly in <xref
+ linkend="svn.serverconfig" />.) And for no other reason than
+ that it makes for a more interesting example, we'll be driving
+ the replication process from a third machine—the one that
+ we currently find ourselves using.</para>
+
+ <para>First, we'll create the repository which will be our
+ mirror. This and the next couple of steps do require shell
+ access to the machine on which the mirror repository will
+ live. Once the repository is all configured, though, we
+ shouldn't need to touch it directly again.</para>
+
+ <informalexample>
+ <screen>
$ ssh admin at svn.example.com "svnadmin create /var/svn/svn-mirror"
admin at svn.example.com's password: ********
$
</screen>
- </informalexample>
-
- <para>At this point, we have our repository, and due to our
- server's configuration, that repository is now
- <quote>live</quote> on the Internet. Now, because we don't
- want anything modifying the repository except our replication
- process, we need a way to distinguish that process from other
- would-be committers. To do so, we use a dedicated username
- for our process. Only commits and revision property
- modifications performed by the special username
- <literal>syncuser</literal> will be allowed.</para>
-
- <para>We'll use the repository's hook system both to allow the
- replication process to do what it needs to do and to enforce
- that only it is doing those things. We accomplish this by
- implementing two of the repository event
- hooks—pre-revprop-change and start-commit. Our
- <filename>pre-revprop-change</filename> hook script is found
- in <xref
- linkend="svn.reposadmin.maint.replication.pre-revprop-change"
- />, and basically verifies that the user attempting the
- property changes is our <literal>syncuser</literal> user. If
- so, the change is allowed; otherwise, it is denied.</para>
-
- <example id="svn.reposadmin.maint.replication.pre-revprop-change">
- <title>Mirror repository's pre-revprop-change hook script</title>
-
- <programlisting>
+ </informalexample>
+
+ <para>At this point, we have our repository, and due to our
+ server's configuration, that repository is now
+ <quote>live</quote> on the Internet. Now, because we don't
+ want anything modifying the repository except our replication
+ process, we need a way to distinguish that process from other
+ would-be committers. To do so, we use a dedicated username
+ for our process. Only commits and revision property
+ modifications performed by the special username
+ <literal>syncuser</literal> will be allowed.</para>
+
+ <para>We'll use the repository's hook system both to allow the
+ replication process to do what it needs to do and to enforce
+ that only it is doing those things. We accomplish this by
+ implementing two of the repository event
+ hooks—pre-revprop-change and start-commit. Our
+ <filename>pre-revprop-change</filename> hook script is found
+ in <xref
+ linkend="svn.reposadmin.maint.replication.pre-revprop-change"
+ />, and basically verifies that the user attempting the
+ property changes is our <literal>syncuser</literal> user. If
+ so, the change is allowed; otherwise, it is denied.</para>
+
+ <example id="svn.reposadmin.maint.replication.pre-revprop-change">
+ <title>Mirror repository's pre-revprop-change hook script</title>
+ <programlisting>
#!/bin/sh
USER="$3"
@@ -2723,20 +2722,20 @@
echo "Only the syncuser user may change revision properties" >&2
exit 1
</programlisting>
- </example>
-
- <para>That covers revision property changes. Now we need to
- ensure that only the <literal>syncuser</literal> user is
- permitted to commit new revisions to the repository. We do
- this using a <filename>start-commit</filename> hook script
- such as the one in <xref
- linkend="svn.reposadmin.maint.replication.start-commit"
- />.</para>
-
- <example id="svn.reposadmin.maint.replication.start-commit">
- <title>Mirror repository's start-commit hook script</title>
-
- <programlisting>
+ </example>
+
+ <para>That covers revision property changes. Now we need to
+ ensure that only the <literal>syncuser</literal> user is
+ permitted to commit new revisions to the repository. We do
+ this using a <filename>start-commit</filename> hook script
+ such as the one in <xref
+ linkend="svn.reposadmin.maint.replication.start-commit"
+ />.</para>
+
+ <example id="svn.reposadmin.maint.replication.start-commit">
+ <title>Mirror repository's start-commit hook script</title>
+
+ <programlisting>
#!/bin/sh
USER="$2"
@@ -2746,26 +2745,26 @@
echo "Only the syncuser user may commit new revisions" >&2
exit 1
</programlisting>
- </example>
-
- <para>After installing our hook scripts and ensuring that they
- are executable by the Subversion server, we're finished with
- the setup of the mirror repository. Now, we get to actually
- do the mirroring.</para>
-
- <para>The first thing we need to do with
- <command>svnsync</command> is to register in our target
- repository the fact that it will be a mirror of the source
- repository. We do this using the <command>svnsync
- initialize</command> subcommand. The URLs we provide point to
- the root directories of the target and source repositories,
- respectively. In Subversion 1.4, this is required—only
- full mirroring of repositories is permitted. In Subversion
- 1.5, though, you can use <command>svnsync</command> to mirror
- only some subtree of the repository, too.</para>
-
- <informalexample>
- <screen>
+ </example>
+
+ <para>After installing our hook scripts and ensuring that they
+ are executable by the Subversion server, we're finished with
+ the setup of the mirror repository. Now, we get to actually
+ do the mirroring.</para>
+
+ <para>The first thing we need to do with
+ <command>svnsync</command> is to register in our target
+ repository the fact that it will be a mirror of the source
+ repository. We do this using the <command>svnsync
+ initialize</command> subcommand. The URLs we provide point to
+ the root directories of the target and source repositories,
+ respectively. In Subversion 1.4, this is required—only
+ full mirroring of repositories is permitted. In Subversion
+ 1.5, though, you can use <command>svnsync</command> to mirror
+ only some subtree of the repository, too.</para>
+
+ <informalexample>
+ <screen>
$ svnsync help init
initialize (init): usage: svnsync initialize DEST_URL SOURCE_URL
@@ -2778,62 +2777,61 @@
Copied properties for revision 0.
$
</screen>
- </informalexample>
-
- <para>Our target repository will now remember that it is a
- mirror of the public Subversion source code repository.
- Notice that we provided a username and password as arguments
- to <command>svnsync</command>—that was required by the
- pre-revprop-change hook on our mirror repository.</para>
-
- <note>
- <para>In Subversion 1.4, the values given to
- <command>svnsync</command>'s <option>--username</option> and
- <option>--password</option> command-line options were used
- for authentication against both the source and destination
- repositories. This caused problems when a user's
- credentials weren't exactly the same for both repositories,
- especially when running in noninteractive mode (with the
- <option>--non-interactive</option> option).</para>
-
- <para>This has been fixed in Subversion 1.5 with the
- introduction of two new pairs of options. Use
- <option>--source-username</option> and
- <option>--source-password</option> to provide authentication
- credentials for the source repository; use
- <option>--sync-username</option> and
- <option>--sync-password</option> to provide credentials for
- the destination repository. (The old
- <option>--username</option> and <option>--password</option>
- options still exist for compatibility, but we advise against
- using them.)</para>
-
- </note>
-
- <para>And now comes the fun part. With a single subcommand, we
- can tell <command>svnsync</command> to copy all the
- as-yet-unmirrored revisions from the source repository to the
- target.<footnote><para>Be forewarned that while it will take
- only a few seconds for the average reader to parse this
- paragraph and the sample output that follows it, the actual
- time required to complete such a mirroring operation is, shall
- we say, quite a bit longer.</para></footnote> The
- <command>svnsync synchronize</command> subcommand will peek
- into the special revision properties previously stored on the
- target repository and determine how much of the source
- repository has been previously mirrored—in this case,
- the most recently mirrored revision is r0. Then it will query
- the source repository and determine what the latest revision
- in that repository is. Finally, it asks the source
- repository's server to start replaying all the revisions
- between 0 and that latest revision. As
- <command>svnsync</command> gets the resultant response from
- the source repository's server, it begins forwarding those
- revisions to the target repository's server as new
- commits.</para>
-
- <informalexample>
- <screen>
+ </informalexample>
+
+ <para>Our target repository will now remember that it is a
+ mirror of the public Subversion source code repository.
+ Notice that we provided a username and password as arguments
+ to <command>svnsync</command>—that was required by the
+ pre-revprop-change hook on our mirror repository.</para>
+
+ <note>
+ <para>In Subversion 1.4, the values given to
+ <command>svnsync</command>'s <option>--username</option> and
+ <option>--password</option> command-line options were used
+ for authentication against both the source and destination
+ repositories. This caused problems when a user's
+ credentials weren't exactly the same for both repositories,
+ especially when running in noninteractive mode (with the
+ <option>--non-interactive</option> option).</para>
+
+ <para>This has been fixed in Subversion 1.5 with the
+ introduction of two new pairs of options. Use
+ <option>--source-username</option> and
+ <option>--source-password</option> to provide authentication
+ credentials for the source repository; use
+ <option>--sync-username</option> and
+ <option>--sync-password</option> to provide credentials for
+ the destination repository. (The old
+ <option>--username</option> and <option>--password</option>
+ options still exist for compatibility, but we advise against
+ using them.)</para>
+ </note>
+
+ <para>And now comes the fun part. With a single subcommand, we
+ can tell <command>svnsync</command> to copy all the
+ as-yet-unmirrored revisions from the source repository to the
+ target.<footnote><para>Be forewarned that while it will take
+ only a few seconds for the average reader to parse this
+ paragraph and the sample output that follows it, the actual
+ time required to complete such a mirroring operation is, shall
+ we say, quite a bit longer.</para></footnote> The
+ <command>svnsync synchronize</command> subcommand will peek
+ into the special revision properties previously stored on the
+ target repository and determine how much of the source
+ repository has been previously mirrored—in this case,
+ the most recently mirrored revision is r0. Then it will query
+ the source repository and determine what the latest revision
+ in that repository is. Finally, it asks the source
+ repository's server to start replaying all the revisions
+ between 0 and that latest revision. As
+ <command>svnsync</command> gets the resultant response from
+ the source repository's server, it begins forwarding those
+ revisions to the target repository's server as new
+ commits.</para>
+
+ <informalexample>
+ <screen>
$ svnsync help synchronize
synchronize (sync): usage: svnsync synchronize DEST_URL [SOURCE_URL]
@@ -2863,149 +2861,149 @@
Copied properties for revision 23408.
$
</screen>
- </informalexample>
-
- <para>Of particular interest here is that for each mirrored
- revision, there is first a commit of that revision to the
- target repository, and then property changes follow. This is
- because the initial commit is performed by (and attributed to)
- the user <literal>syncuser</literal>, and it is datestamped
- with the time as of that revision's creation. Also,
- Subversion's underlying repository access interfaces don't
- provide a mechanism for setting arbitrary revision properties
- as part of a commit. So <command>svnsync</command> follows up
- with an immediate series of property modifications that copy
- into the target repository all the revision properties found
- for that revision in the source repository. This also has the
- effect of fixing the author and datestamp of the revision to
- match that of the source repository.</para>
-
- <para>Also noteworthy is that <command>svnsync</command>
- performs careful bookkeeping that allows it to be safely
- interrupted and restarted without ruining the integrity of the
- mirrored data. If a network glitch occurs while mirroring a
- repository, simply repeat the <command>svnsync
- synchronize</command> command, and it will happily pick up
- right where it left off. In fact, as new revisions appear in
- the source repository, this is exactly what you do
- to keep your mirror up to date.</para>
-
- <warning>
- <para>As part of its bookkeeping, <command>svnsync</command>
- records in the mirror repository the URL with which the
- mirror was initialized. Because of this, invocations of
- <command>svnsync</command> which follow the initialization
- step do not <emphasis>require</emphasis> that you provide
- the source URL on the command line again. However, for
- security purposes, we recommend that you continue to do so.
- Depending on how it is deployed, it may not be safe for
- <command>svnsync</command> to trust the source URL which it
- retrieves from the mirror repository, and from which it
- pulls versioned data.</para>
- </warning>
-
- <sidebar>
- <title>svnsync Bookkeeping</title>
-
- <para><command>svnsync</command> needs to be able to set and
- modify revision properties on the mirror repository because
- those properties are part of the data it is tasked with
- mirroring. As those properties change in the source
- repository, those changes need to be reflected in the mirror
- repository, too. But <command>svnsync</command> also uses a
- set of custom revision properties—stored in revision 0
- of the mirror repository—for its own internal
- bookkeeping. These properties contain information such as
- the URL and UUID of the source repository, plus some
- additional state-tracking information.</para>
-
- <para>One of those pieces of state-tracking information is a
- flag that essentially just means <quote>there's a
- synchronization in progress right now.</quote> This is used
- to prevent multiple <command>svnsync</command> processes
- from colliding with each other while trying to mirror data
- to the same destination repository. Now, generally you
- won't need to pay any attention whatsoever to
- <emphasis>any</emphasis> of these special properties (all of
- which begin with the prefix <literal>svn:sync-</literal>).
- Occasionally, though, if a synchronization fails
- unexpectedly, Subversion never has a chance to remove this
- particular state flag. This causes all future
- synchronization attempts to fail because it appears that a
- synchronization is still in progress when, in fact, none is.
- Fortunately, recovering from this situation is easy to do.
- In Subversion 1.7, you can use the newly introduced
- <option>--steal-lock</option> option with
- <command>svnsync</command>'s commands. In previous
- Subversion versions, you need only to remove the
- <literal>svn:sync-lock</literal> property which serves as
- this flag from revision 0 of the mirror repository:</para>
-
- <informalexample>
- <screen>
+ </informalexample>
+
+ <para>Of particular interest here is that for each mirrored
+ revision, there is first a commit of that revision to the
+ target repository, and then property changes follow. This is
+ because the initial commit is performed by (and attributed to)
+ the user <literal>syncuser</literal>, and it is datestamped
+ with the time as of that revision's creation. Also,
+ Subversion's underlying repository access interfaces don't
+ provide a mechanism for setting arbitrary revision properties
+ as part of a commit. So <command>svnsync</command> follows up
+ with an immediate series of property modifications that copy
+ into the target repository all the revision properties found
+ for that revision in the source repository. This also has the
+ effect of fixing the author and datestamp of the revision to
+ match that of the source repository.</para>
+
+ <para>Also noteworthy is that <command>svnsync</command>
+ performs careful bookkeeping that allows it to be safely
+ interrupted and restarted without ruining the integrity of the
+ mirrored data. If a network glitch occurs while mirroring a
+ repository, simply repeat the <command>svnsync
+ synchronize</command> command, and it will happily pick up
+ right where it left off. In fact, as new revisions appear in
+ the source repository, this is exactly what you do
+ to keep your mirror up to date.</para>
+
+ <warning>
+ <para>As part of its bookkeeping, <command>svnsync</command>
+ records in the mirror repository the URL with which the
+ mirror was initialized. Because of this, invocations of
+ <command>svnsync</command> which follow the initialization
+ step do not <emphasis>require</emphasis> that you provide
+ the source URL on the command line again. However, for
+ security purposes, we recommend that you continue to do so.
+ Depending on how it is deployed, it may not be safe for
+ <command>svnsync</command> to trust the source URL which it
+ retrieves from the mirror repository, and from which it
+ pulls versioned data.</para>
+ </warning>
+
+ <sidebar>
+ <title>svnsync Bookkeeping</title>
+
+ <para><command>svnsync</command> needs to be able to set and
+ modify revision properties on the mirror repository because
+ those properties are part of the data it is tasked with
+ mirroring. As those properties change in the source
+ repository, those changes need to be reflected in the mirror
+ repository, too. But <command>svnsync</command> also uses a
+ set of custom revision properties—stored in revision 0
+ of the mirror repository—for its own internal
+ bookkeeping. These properties contain information such as
+ the URL and UUID of the source repository, plus some
+ additional state-tracking information.</para>
+
+ <para>One of those pieces of state-tracking information is a
+ flag that essentially just means <quote>there's a
+ synchronization in progress right now.</quote> This is used
+ to prevent multiple <command>svnsync</command> processes
+ from colliding with each other while trying to mirror data
+ to the same destination repository. Now, generally you
+ won't need to pay any attention whatsoever to
+ <emphasis>any</emphasis> of these special properties (all of
+ which begin with the prefix <literal>svn:sync-</literal>).
+ Occasionally, though, if a synchronization fails
+ unexpectedly, Subversion never has a chance to remove this
+ particular state flag. This causes all future
+ synchronization attempts to fail because it appears that a
+ synchronization is still in progress when, in fact, none is.
+ Fortunately, recovering from this situation is easy to do.
+ In Subversion 1.7, you can use the newly introduced
+ <option>--steal-lock</option> option with
+ <command>svnsync</command>'s commands. In previous
+ Subversion versions, you need only to remove the
+ <literal>svn:sync-lock</literal> property which serves as
+ this flag from revision 0 of the mirror repository:</para>
+
+ <informalexample>
+ <screen>
$ svn propdel --revprop -r0 svn:sync-lock http://svn.example.com/svn-mirror
property 'svn:sync-lock' deleted from repository revision 0
$
</screen>
- </informalexample>
-
- <para>Also, <command>svnsync</command> stores the source
- repository URL provided at mirror initialization time in a
- bookkeeping property on the mirror repository. Future
- synchronization operations against that mirror which omit
- the source URL at the command line will consult the
- special <literal>svn:sync-from-url</literal> property stored
- on the mirror itself to know where to synchronize from.
- This value is used literally by the
- synchronization process, though. So while from within
- CollabNet's network you can perhaps access our example
- source URL as <literal>http://svn/repos/svn</literal>
- (because that first <literal>svn</literal> magically gets
- <literal>.collab.net</literal> appended to it by DNS
- voodoo), if you later need to update that mirror from
- another machine outside CollabNet's network, the
- synchronization might fail (because the hostname
- <literal>svn</literal> is ambiguous). To avoid this
- problem, it's best to use fully qualified source repository
- URLs when initializing a mirror repository rather than those
- that refer to only hostnames or IP addresses (which can
- change over time). But here again, if you need an existing
mirror
- to start referring to a different URL for the same source
- repository, you can change the bookkeeping property which
- houses that information:</para>
-
- <!-- ### TODO: I think 'svnsync init -/-allow-non-empty'
- ### can be used for this, too. -->
-
- <informalexample>
- <screen>
+ </informalexample>
+
+ <para>Also, <command>svnsync</command> stores the source
+ repository URL provided at mirror initialization time in a
+ bookkeeping property on the mirror repository. Future
+ synchronization operations against that mirror which omit
+ the source URL at the command line will consult the
+ special <literal>svn:sync-from-url</literal> property stored
+ on the mirror itself to know where to synchronize from.
+ This value is used literally by the
+ synchronization process, though. So while from within
+ CollabNet's network you can perhaps access our example
+ source URL as <literal>http://svn/repos/svn</literal>
+ (because that first <literal>svn</literal> magically gets
+ <literal>.collab.net</literal> appended to it by DNS
+ voodoo), if you later need to update that mirror from
+ another machine outside CollabNet's network, the
+ synchronization might fail (because the hostname
+ <literal>svn</literal> is ambiguous). To avoid this
+ problem, it's best to use fully qualified source repository
+ URLs when initializing a mirror repository rather than those
+ that refer to only hostnames or IP addresses (which can
+ change over time). But here again, if you need an existing
mirror
+ to start referring to a different URL for the same source
+ repository, you can change the bookkeeping property which
+ houses that information:</para>
+
+ <!-- ### TODO: I think 'svnsync init -/-allow-non-empty'
+ ### can be used for this, too. -->
+
+ <informalexample>
+ <screen>
$ svn propset --revprop -r0 svn:sync-from-url
<replaceable>NEW-SOURCE-URL</replaceable> \
http://svn.example.com/svn-mirror
property 'svn:sync-from-url' set on repository revision 0
$
</screen>
- </informalexample>
-
- <para>Another interesting thing about these special
- bookkeeping properties is that <command>svnsync</command>
- will not attempt to mirror any of those properties when they
- are found in the source repository. The reason is probably
- obvious, but basically boils down to
- <command>svnsync</command> not being able to distinguish the
- special properties it has merely copied from the source
- repository from those it needs to consult and maintain for
- its own bookkeeping needs. This situation could occur if,
- for example, you were maintaining a mirror of a mirror of a
- third repository. When <command>svnsync</command> sees its
- own special properties in revision 0 of the source
- repository, it simply ignores them.</para>
-
- <para>In Subversion 1.6, an <command>svnsync info</command>
- subcommand has been added to easily display the special
- bookkeeping properties in the destination repository.</para>
-
- <informalexample>
- <screen>
+ </informalexample>
+
+ <para>Another interesting thing about these special
+ bookkeeping properties is that <command>svnsync</command>
+ will not attempt to mirror any of those properties when they
+ are found in the source repository. The reason is probably
+ obvious, but basically boils down to
+ <command>svnsync</command> not being able to distinguish the
+ special properties it has merely copied from the source
+ repository from those it needs to consult and maintain for
+ its own bookkeeping needs. This situation could occur if,
+ for example, you were maintaining a mirror of a mirror of a
+ third repository. When <command>svnsync</command> sees its
+ own special properties in revision 0 of the source
+ repository, it simply ignores them.</para>
+
+ <para>In Subversion 1.6, an <command>svnsync info</command>
+ subcommand has been added to easily display the special
+ bookkeeping properties in the destination repository.</para>
+
+ <informalexample>
+ <screen>
$ svnsync help info
info: usage: svnsync info DEST_URL
@@ -3018,26 +3016,25 @@
Last Merged Revision: 23408
$
</screen>
- </informalexample>
-
- </sidebar>
-
- <para>There is, however, one bit of inelegance in the process.
- Because Subversion revision properties can be changed at any
- time throughout the lifetime of the repository, and because
- they don't leave an audit trail that indicates when they were
- changed, replication processes have to pay special attention
- to them. If you've already mirrored the first 15 revisions of
- a repository and someone then changes a revision property on
- revision 12, <command>svnsync</command> won't know to go back
- and patch up its copy of revision 12. You'll need to tell it
- to do so manually by using (or with some additional tooling
- around) the <command>svnsync copy-revprops</command>
- subcommand, which simply rereplicates all the revision
- properties for a particular revision or range thereof.</para>
-
- <informalexample>
- <screen>
+ </informalexample>
+ </sidebar>
+
+ <para>There is, however, one bit of inelegance in the process.
+ Because Subversion revision properties can be changed at any
+ time throughout the lifetime of the repository, and because
+ they don't leave an audit trail that indicates when they were
+ changed, replication processes have to pay special attention
+ to them. If you've already mirrored the first 15 revisions of
+ a repository and someone then changes a revision property on
+ revision 12, <command>svnsync</command> won't know to go back
+ and patch up its copy of revision 12. You'll need to tell it
+ to do so manually by using (or with some additional tooling
+ around) the <command>svnsync copy-revprops</command>
+ subcommand, which simply rereplicates all the revision
+ properties for a particular revision or range thereof.</para>
+
+ <informalexample>
+ <screen>
$ svnsync help copy-revprops
copy-revprops: usage: svnsync copy-revprops DEST_URL [REV[:REV2]]
@@ -3048,46 +3045,46 @@
Copied properties for revision 12.
$
</screen>
- </informalexample>
-
- <para>That's repository replication
- via <command>svnsync</command> in a nutshell. You'll likely
- want some automation around such a process. For example,
- while our example was a pull-and-push setup, you might wish to
- have your primary repository push changes to one or more
- blessed mirrors as part of its post-commit and
- post-revprop-change hook implementations. This would enable
- the mirror to be up to date in as near to real time as is
- likely possible.</para>
-
- <para>Also, while it isn't very commonplace to do so,
- <command>svnsync</command> does gracefully mirror repositories
- in which the user as whom it authenticates has only partial
- read access. It simply copies only the bits of the repository
- that it is permitted to see. Obviously, such a mirror is not
- useful as a backup solution.</para>
-
- <para>In Subversion 1.5, <command>svnsync</command> grew the
- ability to also mirror a subset of a repository rather than
- the whole thing. The process of setting up and maintaining
- such a mirror is exactly the same as when mirroring a whole
- repository, except that instead of specifying the source
- repository's root URL when running <command>svnsync
- init</command>, you specify the URL of some subdirectory
- within that repository. Synchronization to that mirror will
- now copy only the bits that changed under that source
- repository subdirectory. There are some limitations to this
- support, though. First, you can't mirror multiple disjoint
- subdirectories of the source repository into a single mirror
- repository—you'd need to instead mirror some parent
- directory that is common to both. Second, the filtering
- logic is entirely path-based, so if the subdirectory you are
- mirroring was renamed at some point in the past, your mirror
- would contain only the revisions since the directory appeared
- at the URL you specified. And likewise, if the source
- subdirectory is renamed in the future, your synchronization
- processes will stop mirroring data at the point that the
- source URL you specified is no longer valid.</para>
+ </informalexample>
+
+ <para>That's repository replication
+ via <command>svnsync</command> in a nutshell. You'll likely
+ want some automation around such a process. For example,
+ while our example was a pull-and-push setup, you might wish to
+ have your primary repository push changes to one or more
+ blessed mirrors as part of its post-commit and
+ post-revprop-change hook implementations. This would enable
+ the mirror to be up to date in as near to real time as is
+ likely possible.</para>
+
+ <para>Also, while it isn't very commonplace to do so,
+ <command>svnsync</command> does gracefully mirror repositories
+ in which the user as whom it authenticates has only partial
+ read access. It simply copies only the bits of the repository
+ that it is permitted to see. Obviously, such a mirror is not
+ useful as a backup solution.</para>
+
+ <para>In Subversion 1.5, <command>svnsync</command> grew the
+ ability to also mirror a subset of a repository rather than
+ the whole thing. The process of setting up and maintaining
+ such a mirror is exactly the same as when mirroring a whole
+ repository, except that instead of specifying the source
+ repository's root URL when running <command>svnsync
+ init</command>, you specify the URL of some subdirectory
+ within that repository. Synchronization to that mirror will
+ now copy only the bits that changed under that source
+ repository subdirectory. There are some limitations to this
+ support, though. First, you can't mirror multiple disjoint
+ subdirectories of the source repository into a single mirror
+ repository—you'd need to instead mirror some parent
+ directory that is common to both. Second, the filtering
+ logic is entirely path-based, so if the subdirectory you are
+ mirroring was renamed at some point in the past, your mirror
+ would contain only the revisions since the directory appeared
+ at the URL you specified. And likewise, if the source
+ subdirectory is renamed in the future, your synchronization
+ processes will stop mirroring data at the point that the
+ source URL you specified is no longer valid.</para>
<para>We mentioned previously the cost of setting up an
initial mirror of an existing repository. For many folks,
More information about the svnbook-dev
mailing list