[svnbook commit] r2681 - trunk/src/en/book
cmpilato
noreply at red-bean.com
Mon Feb 12 00:19:28 CST 2007
Author: cmpilato
Date: Mon Feb 12 00:19:28 2007
New Revision: 2681
Added:
trunk/src/en/book/ORPHANED-TOPICS
Modified:
trunk/src/en/book/ch-repository-admin.xml
Log:
* src/en/book/ch-repository-admin.xml
More hammerin' and sawin' on yet another massive chapter.
* src/en/book/ORPHANED-TOPICS
Created as a temporary holding area for a topic that I dunno where to
put (though /dev/null is looking right nice).
Modified: trunk/src/en/book/ch-repository-admin.xml
==============================================================================
--- trunk/src/en/book/ch-repository-admin.xml (original)
+++ trunk/src/en/book/ch-repository-admin.xml Mon Feb 12 00:19:28 2007
@@ -136,8 +136,8 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
- <sect1 id="svn.reposadmin.create">
- <title>Repository Creation and Configuration</title>
+ <sect1 id="svn.reposadmin.planning">
+ <title>Strategies for Repository Deployment</title>
<para>Due largely to the simplicity of the overall design of the
Subversion repository and the technologies on which it relies,
@@ -161,17 +161,228 @@
accessed?</para>
</listitem>
<listitem>
- <para>Which of the available types of data store do you want
- to use?</para>
- </listitem>
- <listitem>
<para>What types of access control and repository event
reporting do you need?</para>
</listitem>
+ <listitem>
+ <para>Which of the available types of data store do you want
+ to use?</para>
+ </listitem>
</itemizedlist>
- <para>We'll try to help you answer those questions, and then guide
- you through the setup steps.</para>
+ <para>In this section, we'll try to help you answer those
+ questions.</para>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.projects.chooselayout">
+ <title>Planning Your Repository Organization</title>
+
+ <para>While Subversion allows you to move around versioned files
+ and directories without any loss of information, and even
+ provides ways of moving whole sets of versioned history from
+ one repository to another, doing so can greatly disrupt the
+ workflow of those who access the repository often and come to
+ expect things to be at certain locations. So before creating
+ a new repository, try to peer into the future a bit; plan
+ ahead before placing your data under version control. By
+ conscientiously <quote>laying out</quote> your repository or
+ repositories and their versioned contents ahead of time, you
+ can prevent many future headaches.</para>
+
+ <para>Let's assume that as repository administrator, you will be
+ responsible for supporting the version control system for
+ several projects. Your first decision is whether to use a
+ single repository for multiple projects, or to give each
+ project its own repository, or some compromise of these
+ two.</para>
+
+ <para>There are benefits to using a single repository for
+ multiple projects, most obviously the lack of duplicated
+ maintenance. A single repository means that there is one set
+ of hook programs, one thing to routinely backup, one thing to
+ dump and load if Subversion releases an incompatible new
+ version, and so on. Also, you can move data between projects
+ easily, and without losing any historical versioning
+ information.</para>
+
+ <para>The downside of using a single repository is that
+ different projects may have different commit mailing lists or
+ different authentication and authorization requirements.
+ These aren't insurmountable problems, of course—it just
+ means that all of your hook scripts have to be sensitive to
+ the layout of your repository rather than assuming that the
+ whole repository is associated with a single group of people.
+ Also, remember that Subversion uses repository-global revision
+ numbers. Some folks don't like the fact that even though no
+ changes have been made to their project lately, the youngest
+ revision number for the repository keeps climbing because
+ other projects are actively adding new revisions.</para>
+
+ <para>A middle-ground approach can be taken, too. For example,
+ projects can be grouped by how well they relate to each other.
+ You might have a few repositories with a handful of projects
+ in each repository. That way, projects that are likely to
+ want to share data can do so easily, and as new revisions are
+ added to the repository, at least the developers know that
+ those new revisions are at least remotely related to everyone
+ who uses that repository.</para>
+
+ <para>After deciding how to organize your projects with respect
+ to repositories, you'll probably want to think about directory
+ hierarchies within the repositories themselves. Because
+ Subversion uses regular directory copies for branching and
+ tagging (see <xref linkend="svn.branchmerge"/>), the Subversion
+ community recommends that you choose a repository location for
+ each <firstterm>project root</firstterm>—the
+ <quote>top-most</quote> directory which contains data related
+ to that project—and then create three subdirectories
+ beneath that root: <filename>trunk</filename>, meaning the
+ directory under which the main project development occurs;
+ <filename>branches</filename>, which is a directory in which
+ to create various named branches of the main development line;
+ <filename>tags</filename>, which is a directory of branches
+ that are created, and perhaps destroyed, but never
+ changed.
+ <footnote>
+ <para>The <filename>trunk</filename>, <filename>tags</filename>,
+ and <filename>branches</filename> trio are sometimes referred
+ to as <quote>the TTB directories</quote>.</para>
+ </footnote>
+ </para>
+
+ <para>For example, your repository might look like:</para>
+
+ <screen>
+/
+ calc/
+ trunk/
+ tags/
+ branches/
+ calendar/
+ trunk/
+ tags/
+ branches/
+ spreadsheet/
+ trunk/
+ tags/
+ branches/
+ …
+</screen>
+
+ <para>Note that it doesn't matter where in your repository each
+ project root is. If you have only one project per repository,
+ the logical place to put each project root is at the root of
+ that project's respective repository. If you have multiple
+ projects, you might want to arrange them in groups inside the
+ repository, perhaps putting projects with similar goals or
+ shared code in the same subdirectory, or maybe just grouping
+ them alphabetically. Such an arrangement might look
+ like:</para>
+
+ <screen>
+/
+ utils/
+ calc/
+ trunk/
+ tags/
+ branches/
+ calendar/
+ trunk/
+ tags/
+ branches/
+ …
+ office/
+ spreadsheet/
+ trunk/
+ tags/
+ branches/
+ …
+</screen>
+
+ <para>Lay out your repository in whatever way you see fit.
+ Subversion does not expect or enforce a layout schema—in
+ its eyes, a directory is a directory is a directory.
+ Ultimately, you should choose the repository arrangement that
+ meets the needs of the people who work on the projects that
+ live there.</para>
+
+ <para>In the name of full disclosure, though, we'll mention
+ another very common layout. In this layout, the
+ <filename>trunk</filename>, <filename>tags</filename>, and
+ <filename>branches</filename> directories live in the root
+ directory of your repository, and your projects are in
+ subdirectories beneath those, like:</para>
+
+ <screen>
+/
+ trunk/
+ calc/
+ calendar/
+ spreadsheet/
+ …
+ tags/
+ calc/
+ calendar/
+ spreadsheet/
+ …
+ branches/
+ calc/
+ calendar/
+ spreadsheet/
+ …
+</screen>
+
+ <para>There's nothing particularly incorrect about such a
+ layout, but it may or may not seem as intuitive for your
+ users. Especially in large, multi-project situations with
+ many users, those users may tend to be familiar with only one
+ or two of the projects in the repository. But the
+ projects-as-branch-siblings tends to de-emphasize project
+ individuality and focus on the entire set of projects as a
+ single entity. That's a social issue though. We like our
+ originally suggested arrangement for purely practical
+ reasons—it's easier to ask about (or modify, or migrate
+ elsewhere) the entire history of a single project when there's
+ a single repository path that holds the entire
+ history—past, present, tagged, and branched—for
+ that project and that project alone.</para>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.basics.hosting">
+ <title>Deciding Where and How to Host Your Repository</title>
+
+ <para>Before creating your Subversion repository, an obvious
+ question you'll need to answer is where the thing is going to
+ live. This is strongly connected to a myriad of other
+ questions involving how the repository will be accessed (via a
+ Subversion server or directly), by whom (users behind your
+ corporate firewall or the whole world out on the open
+ Internet), what other services you'll be providing around
+ Subversion (repository browsing UIs, e-mail based commit
+ notification, etc.), your data backup strategy, and so
+ on.</para>
+
+ <para>We cover server choice and configuration in <xref
+ linkend="svn.serverconfig" />, but the point we'd like to
+ briefly make here is simply that the answers to some of these
+ other questions might have implications that force your hand
+ when deciding where your repository will live. For example,
+ certain deployment scenarios might require accessing the
+ repository via a remote filesystem from multiple computers, in
+ which case (as you'll read in the next section) your choice of
+ a repository back-end data store turns out not to be a choice
+ at all because only one of the available back-ends will work
+ in this scenario.</para>
+
+ <para>To try to address each and every possible way to deploy
+ Subversion is both not possible and outside the scope of this
+ book. We simply encourage you to evaluate your options, using
+ these pages and other sources as your reference material, and
+ plan ahead.</para>
+
+ </sect2>
<!-- =============================================================== -->
<sect2 id="svn.reposadmin.basics.backends">
@@ -458,30 +669,53 @@
checking out the latest tree is a bit slower than fetching
the fulltexts stored in a Berkeley DB HEAD revision. FSFS
also has a longer delay when finalizing a commit, which
- could in extreme cases cause clients to time out when
+ could in extreme cases cause clients to time out while
waiting for a response.</para>
<para>The most important distinction, however, is FSFS's
inability to be <quote>wedged</quote> when something goes
wrong. If a process using a Berkeley DB database runs into
- a permissions problem or suddenly crashes, the database is
- left unusable until an administrator recovers it. If the
- same scenarios happen to a process using an FSFS repository,
- the repository isn't affected at all. At worst, some
- transaction data is left behind.</para>
+ a permissions problem or suddenly crashes, the database can
+ be left in an unusable state until an administrator recovers
+ it. If the same scenarios happen to a process using an FSFS
+ repository, the repository isn't affected at all. At worst,
+ some transaction data is left behind.</para>
<para>The only real argument against FSFS is its relative
- immaturity compared to Berkeley DB. It hasn't been used or
- stress-tested nearly as much, and so a lot of these
- assertions about speed and scalability are just that:
- assertions, based on good guesses. In theory, it promises a
- lower barrier to entry for new administrators and is less
- susceptible to problems. In practice, only time will
- tell.</para>
+ immaturity compared to Berkeley DB. Unlike Berkeley DB,
+ which has years of history, its own dedicated development
+ team and, now, Oracle's mighty name attached to it,
+ <footnote>
+ <para>Oracle bought Sleepycat and its flagship software,
+ Berkeley DB, on Valentine's Day in 2006.</para>
+ </footnote>
+ FSFS is a much newer bit of engineering. It hasn't been
+ used or stress-tested nearly as much, so many of these
+ assertions about speed and scalability are based on
+ speculations founded in the theoretical principles of the
+ design. That said, FSFS has quickly become the back-end of
+ choice for some of the largest public and private Subversion
+ repositories, and promises a lower barrier to entry for
+ Subversion across the board.</para>
</sect3>
</sect2>
+ </sect1>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.reposadmin.create">
+ <title>Creating and Configuring Your Repository</title>
+
+ <para>In <xref linkend="svn.reposadmin.planning" />, we looked at
+ some of the important decisions that should be made before
+ creating and configuring your Subversion repository. Now, we
+ finally get to get our hands dirty!</para>
+
+ <para>In this section, we'll do ### BLAH BLAH BLAH BLAH</para>
+
<!-- =============================================================== -->
<sect2 id="svn.reposadmin.basics.creating">
<title>Creating the Repository</title>
@@ -535,10 +769,10 @@
<para>Present in the <filename>db/</filename> subdirectory of
your repository is the implementation of the versioned
- filesystem. Your new repository's versioned filesystem begins life at
- revision 0, which is defined to consist of nothing but the
- top-level root (<filename>/</filename>) directory. Initially,
- revision 0 also has a single revision property,
+ filesystem. Your new repository's versioned filesystem begins
+ life at revision 0, which is defined to consist of nothing but
+ the top-level root (<filename>/</filename>) directory.
+ Initially, revision 0 also has a single revision property,
<literal>svn:date</literal>, set to the time at which the
repository was created.</para>
@@ -549,12 +783,12 @@
<para>While some parts of a Subversion repository—such
as the configuration files and hook scripts—are meant
to be examined and modified manually, you shouldn't (and
- shouldn't need to) tamper with the repository <quote>by
- hand</quote>. The <command>svnadmin</command> tool should
- be sufficient for any changes necessary to your repository,
- or you can look to third-party tools (such as Berkeley DB's
- tool suite) for tweaking relevant subsections of the
- repository.</para>
+ shouldn't need to) tamper with the other parts of the
+ repository <quote>by hand</quote>. The
+ <command>svnadmin</command> tool should be sufficient for
+ any changes necessary to your repository, or you can look to
+ third-party tools (such as Berkeley DB's tool suite) for
+ tweaking relevant subsections of the repository.</para>
</warning>
</sect2>
@@ -702,31 +936,33 @@
configuration option values.</para>
<para>The producers of Berkeley DB understand that different
- databases have different requirements, and so they have
- provided a mechanism for overriding at runtime many of the
- configuration values for the Berkeley DB environment.
- Berkeley checks for the presence of a file named
- <filename>DB_CONFIG</filename> in each environment directory,
- and parses the options found in that file for use with that
- particular Berkeley environment.</para>
-
- <para>The Berkeley configuration file for your repository is
- located in the <filename>db</filename> environment directory,
- at <filename>repos/db/DB_CONFIG</filename>. Subversion itself
- creates this file when it creates the rest of the repository.
- The file initially contains some default options, as well as
+ applications and database environments have different
+ requirements, and so they have provided a mechanism for
+ overriding at runtime many of the configuration values for the
+ Berkeley DB environment. Berkeley checks for the presence of
+ a file named <filename>DB_CONFIG</filename> in the environment
+ directory, and parses the options found in that file for use
+ with that particular Berkeley DB environment.</para>
+
+ <para>The Berkeley DB configuration file for a BDB-backed
+ repository is located in the repository's
+ <filename>db</filename> subdirectory, at
+ <filename>db/DB_CONFIG</filename>. Subversion itself creates
+ this file when it creates the rest of the repository. The
+ file initially contains some default options, as well as
pointers to the Berkeley DB online documentation so you can
read about what those options do. Of course, you are free to
add any of the supported Berkeley DB options to your
<filename>DB_CONFIG</filename> file. Just be aware that while
Subversion never attempts to read or interpret the contents of
- the file, and makes no use of the option settings in it,
- you'll want to avoid any configuration changes that may cause
- Berkeley DB to behave in a fashion that is unexpected by the
- rest of the Subversion code. Also, changes made to
+ the file, and makes no direct use of the option settings in
+ it, you'll want to avoid any configuration changes that may
+ cause Berkeley DB to behave in a fashion that is unexpected by
+ the rest of the Subversion code. Also, changes made to
<filename>DB_CONFIG</filename> won't take effect until you
recover the database environment (using <command>svnadmin
- recover</command>).</para>
+ recover</command>).</para>
+
</sect2>
</sect1>
@@ -743,7 +979,7 @@
tools—what they are, when to use them, and how to use
them. This section will introduce you to the repository
administration tools provided by Subversion, and how to wield
- them to accomplish tasks such as repository migrations,
+ them to accomplish tasks such as repository data migration,
upgrades, backups and cleanups.</para>
<!-- =============================================================== -->
@@ -783,7 +1019,8 @@
Note: any subcommand which takes the '--revision' and '--transaction'
options will, if invoked without one of those options, act on
the repository's youngest revision.
-Type "svnlook help <subcommand>" for help on a specific subcommand.
+Type 'svnlook help <subcommand$gt;' for help on a specific subcommand.
+Type 'svnlook --version' to see the program version and FS modules.
…
</screen>
@@ -818,8 +1055,8 @@
<para>The only exception to these rules about subcommands is
the <command>svnlook youngest</command> subcommand, which
- takes no options, and simply prints out the
- <literal>HEAD</literal> revision number.</para>
+ takes no options, and simply prints out the repository's
+ youngest revision number.</para>
<screen>
$ svnlook youngest /path/to/repos
@@ -917,128 +1154,8 @@
we've mentioned previously, reporting which paths were
modified in a given revision or transaction, showing textual
and property differences made to files and directories, and
- so on. The following is a brief description of the current
- list of subcommands accepted by <command>svnlook</command>,
- and the output of those subcommands:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>author</literal></term>
- <listitem>
- <para>Print the tree's author.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>cat</literal></term>
- <listitem>
- <para>Print the contents of a file in the tree.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>changed</literal></term>
- <listitem>
- <para>List all files and directories that changed in the
- tree.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>date</literal></term>
- <listitem>
- <para>Print the tree's datestamp.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>diff</literal></term>
- <listitem>
- <para>Print unified diffs of changed files.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>dirs-changed</literal></term>
- <listitem>
- <para>List the directories in the tree that were
- themselves changed, or whose file children were
- changed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>history</literal></term>
- <listitem>
- <para>Display interesting points in the history of a
- versioned path (places where modifications or copies
- occurred).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>info</literal></term>
- <listitem>
- <para>Print the tree's author, datestamp, log message
- character count, and log message.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>lock</literal></term>
- <listitem>
- <para>If a path is locked, describe the lock attributes.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>log</literal></term>
- <listitem>
- <para>Print the tree's log message.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>propget</literal></term>
- <listitem>
- <para>Print the value of a property on a path in the
- tree.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>proplist</literal></term>
- <listitem>
- <para>Print the names and values of properties set on paths
- in the tree.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>tree</literal></term>
- <listitem>
- <para>Print the tree listing, optionally revealing the
- filesystem node revision IDs associated with each
- path.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>uuid</literal></term>
- <listitem>
- <para>Print the repository's UUID—
- <emphasis>U</emphasis>niversal <emphasis>U</emphasis>nique
- <emphasis>ID</emphasis>entifier.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>youngest</literal></term>
- <listitem>
- <para>Print the youngest revision number.</para>
- </listitem>
- </varlistentry>
- </variablelist>
+ so on. See <xref linkend="svn.ref.svnlook" /> for a full
+ reference of <command>svnlook</command>'s features.</para>
</sect3>
@@ -1054,158 +1171,26 @@
<command>svnadmin</command> is similar to that of
<command>svnlook</command>:</para>
- <screen>
-$ svnadmin help
-general usage: svnadmin SUBCOMMAND REPOS_PATH [ARGS & OPTIONS ...]
-Type "svnadmin help <subcommand>" for help on a specific subcommand.
-
-Available subcommands:
- create
- deltify
- dump
- help (?, h)
-…
-</screen>
-
- <para>We've already mentioned <command>svnadmin</command>'s
- <literal>create</literal> subcommand (see <xref
- linkend="svn.reposadmin.create"/>). Most of the others we will
- cover in more detail later in this chapter. For now, let's
- just take a quick glance at what each of the available
- subcommands offers.</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>create</literal></term>
- <listitem>
- <para>Create a new Subversion repository.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>deltify</literal></term>
- <listitem>
- <para>Run over a specified revision range, performing
- predecessor deltification on the paths changed in
- those revisions. If no revisions are specified, this
- command will simply deltify the
- <literal>HEAD</literal> revision.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>dump</literal></term>
- <listitem>
- <para>Dump the contents of the repository, bounded by a
- given set of revisions, using a portable dump format.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>hotcopy</literal></term>
- <listitem>
- <para>Make a hot copy of a repository. You can run
- this command at any time and make a safe copy of the
- repository, regardless if other processes are using
- the repository.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>list-dblogs</literal></term>
- <listitem>
- <para>(Berkeley DB repositories only.) List the paths
- of Berkeley DB log files associated with the
- repository. This list includes all log
- files—those still in use by Subversion, as well
- as those no longer in use.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>list-unused-dblogs</literal></term>
- <listitem>
- <para>(Berkeley DB repositories only.) List the paths
- of Berkeley DB log files associated with, but no
- longer used by, the repository. You may safely remove
- these log files from the repository layout, possibly
- archiving them for use in the event that you ever need
- to perform a catastrophic recovery of the
- repository.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>load</literal></term>
- <listitem>
- <para>Load a set of revisions into a repository from a
- stream of data that uses the same portable dump format
- generated by the <literal>dump</literal> subcommand.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>lslocks</literal></term>
- <listitem>
- <para>List and describe any locks that exist in the
- repository.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>lstxns</literal></term>
- <listitem>
- <para>List the names of uncommitted Subversion
- transactions that currently exist in the repository.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>recover</literal></term>
- <listitem>
- <para>Perform recovery steps on a repository that is in
- need of such, generally after a fatal error has
- occurred that prevented a process from cleanly
- shutting down its communication with the repository.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>rmlocks</literal></term>
- <listitem>
- <para>Unconditionally remove locks from listed
- paths.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>rmtxns</literal></term>
- <listitem>
- <para>Cleanly remove Subversion transactions from the
- repository (conveniently fed by output from the
- <literal>lstxns</literal> subcommand).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>setlog</literal></term>
- <listitem>
- <para>Replace the current value of the
- <literal>svn:log</literal> (commit log message)
- property on a given revision in the repository with a
- new value.</para>
- </listitem>
- </varlistentry>
+ <screen>
+$ svnadmin help
+general usage: svnadmin SUBCOMMAND REPOS_PATH [ARGS & OPTIONS ...]
+Type 'svnadmin help <subcommand>' for help on a specific subcommand.
+Type 'svnadmin --version' to see the program version and FS modules.
- <varlistentry>
- <term><literal>verify</literal></term>
- <listitem>
- <para>Verify the contents of the repository. This includes,
- among other things, checksum comparisons of the
- versioned data stored in the repository.</para>
- </listitem>
- </varlistentry>
- </variablelist>
+Available subcommands:
+ crashtest
+ create
+ deltify
+…
+</screen>
+
+ <para>We've already mentioned <command>svnadmin</command>'s
+ <literal>create</literal> subcommand (see <xref
+ linkend="svn.reposadmin.basics.creating"/>). Most of the
+ others we will cover as they become topically relevant later
+ in this chapter. And you can consult <xref
+ linkend="svn.ref.svnadmin" /> for a full rundown of
+ subcommands and what each of them offers.</para>
</sect3>
@@ -1213,11 +1198,13 @@
<sect3 id="svn.reposadmin.maint.tk.svndumpfilter">
<title>svndumpfilter</title>
- <para>Since Subversion stores everything in an opaque database
- system, attempting manual tweaks is unwise, if not quite
+ <para>Since Subversion stores your versioned history using, at
+ the very least, binary differencing algorithms and data
+ compression (and optionally in a completely opaque database
+ system), attempting manual tweaks is unwise, if not quite
difficult. And once data has been stored in your
- repository, Subversion generally doesn't provide an
- easy way to remove that data.
+ repository, Subversion generally doesn't provide an easy way
+ to remove that data.
<footnote>
<para>That, by the way, is a <emphasis>feature</emphasis>,
not a bug.</para>
@@ -1242,7 +1229,7 @@
linkend="svn.reposadmin.maint.migrate"/>). The great thing about the
human-readability aspect of the dump format is that, if you
aren't careless about it, you can manually inspect and
- modify it. Of course, the downside is that if you have two
+ modify it. Of course, the downside is that if you have three
years' worth of repository activity encapsulated in what is
likely to be a very large dump file, it could take you a
long, long time to manually inspect and modify it.</para>
@@ -1265,6 +1252,7 @@
$ svndumpfilter help
general usage: svndumpfilter SUBCOMMAND [ARGS & OPTIONS ...]
Type "svndumpfilter help <subcommand>" for help on a specific subcommand.
+Type 'svndumpfilter --version' to see the program version.
Available subcommands:
exclude
@@ -1296,9 +1284,9 @@
<para>Let's look a realistic example of how you might use this
program. We discuss elsewhere (see <xref
- linkend="svn.reposadmin.projects.chooselayout"/>) the process of deciding how to
- choose a layout for the data in your
- repositories—using one repository per project or
+ linkend="svn.reposadmin.projects.chooselayout"/>) the
+ process of deciding how to choose a layout for the data in
+ your repositories—using one repository per project or
combining them, arranging stuff within your repository, and
so on. But sometimes after new revisions start flying in,
you rethink your layout and would like to make some changes.
@@ -1507,7 +1495,7 @@
<para>If you're using a Berkeley DB repository, then all of
your versioned filesystem's structure and data live in a set
- of database tables within the <filename>db</filename>
+ of database tables within the <filename>db/</filename>
subdirectory of your repository. This subdirectory is a
regular Berkeley DB environment directory, and can therefore
be used in conjunction with any of the Berkeley database
@@ -1624,28 +1612,84 @@
it.</para>
</warning>
- <para>Another common use of <command>svnadmin</command> is to
- query the repository for outstanding—possibly
- dead—Subversion transactions. In the event that a
- commit should fail, the transaction is usually cleaned up.
- That is, the transaction itself is removed from the
- repository, and any data associated with (and only with) that
- transaction is removed as well. Occasionally, though, a
- failure occurs in such a way that the cleanup of the
- transaction never happens. This could happen for several
- reasons: perhaps the client operation was inelegantly
- terminated by the user, or a network failure might have
- occurred in the middle of an operation, etc. Regardless of
- the reason, dead transactions can happen. They don't do any
- real harm, other than consuming a small bit of disk space. A
- fastidious administrator may nonetheless want to remove
- them.</para>
-
- <para>You can use <command>svnadmin</command>'s
- <literal>lstxns</literal> command to list the names of the
- currently outstanding transactions.</para>
- <screen>
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.maint.diskspace">
+ <title>Managing Disk Space</title>
+
+ <para>While the cost of storage has dropped incredibly in the
+ past few years, disk usage is still a valid concern for
+ administrators seeking to version large amounts of data.
+ Every additional byte consumed by the live repository is a
+ byte that needs to be backed up offsite, perhaps multiple
+ times as part of rotating backup schedules. It is useful to
+ know what pieces of Subversion's repository data need to
+ remain on the live site, which need to be backed up, and which
+ can be safely removed.</para>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <sect3 id="svn.reposadmin.maint.diskspace.deltas">
+ <title>How Subversion saves disk space</title>
+
+ <para>To keep the size of the repository as small as possible,
+ Subversion uses <firstterm>deltification</firstterm> (or,
+ <quote>deltified storage</quote>) within the repository
+ itself. Deltification involves encoding the representation
+ of a chunk of data as a collection of differences against
+ some other chunk of data. If the two pieces of data are
+ very similar, this deltification results in storage savings
+ for the deltified chunk—rather than taking up space
+ equal to the size of the original data, it only takes up
+ enough space to say, <quote>I look just like this other
+ piece of data over here, except for the following couple of
+ changes</quote>. The result is that most of the repository
+ data that tends to be sizable—namely, the contents of
+ versioned files—is stored at a much smaller size than
+ the original <quote>fulltext</quote> representation of that
+ data. And for repositories created with Subversion 1.4 or
+ later, the space saving get even better—now those
+ fulltext representations of file contents are themselves
+ compressed.</para>
+
+ <note>
+ <para>Because all of the data that is subject to
+ deltification in a BDB-backed repository is stored in a
+ single Berkeley DB database file, reducing the size of the
+ stored values will not immediately reduce the size of the
+ database file itself. Berkeley DB will, however, keep
+ internal records of unused areas of the database file, and
+ consume those areas first before growing the size of the
+ database file. So while deltification doesn't produce
+ immediate space savings, it can drastically slow future
+ growth of the database.</para>
+ </note>
+
+ </sect3>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <sect3 id="svn.reposadmin.maint.diskspace.deadtxns">
+ <title>Removing dead transactions</title>
+
+ <para>While generally not the common case, there are
+ circumstances in which a Subversion commit process might
+ fail, leaving behind in the repository the remnants of the
+ revision-to-be that wasn't—an uncommitted transaction
+ and all the file and directory changes associated with it.
+ This could happen for several reasons: perhaps the client
+ operation was inelegantly terminated by the user, or a
+ network failure might have occurred in the middle of an
+ operation, etc. Regardless of the reason, dead transactions
+ can happen. They don't do any real harm, other than
+ consuming disk space. A fastidious administrator may
+ nonetheless wish to remove them.</para>
+
+ <para>You can use <command>svnadmin</command>'s
+ <literal>lstxns</literal> command to list the names of the
+ currently outstanding transactions.</para>
+
+ <screen>
$ svnadmin lstxns myrepos
19
3a1
@@ -1653,34 +1697,36 @@
$
</screen>
- <para>Each item in the resultant output can then be used with
- <command>svnlook</command> (and its
- <option>--transaction</option> option) to determine who
- created the transaction, when it was created, what types of
- changes were made in the transaction—in other words,
- whether or not the transaction is a safe candidate for
- removal! If so, the transaction's name can be passed to
- <command>svnadmin rmtxns</command>, which will perform the
- cleanup of the transaction. In fact, the
- <literal>rmtxns</literal> subcommand can take its input
- directly from the output of <literal>lstxns</literal>!</para>
+ <para>Each item in the resultant output can then be used with
+ <command>svnlook</command> (and its
+ <option>--transaction</option> option) to determine who
+ created the transaction, when it was created, what types of
+ changes were made in the transaction—in other words,
+ whether or not the transaction is a safe candidate for
+ removal! If so, the transaction's name can be passed to
+ <command>svnadmin rmtxns</command>, which will perform the
+ cleanup of the transaction. In fact, the
+ <literal>rmtxns</literal> subcommand can take its input
+ directly from the output of
+ <literal>lstxns</literal>!</para>
- <screen>
+ <screen>
$ svnadmin rmtxns myrepos `svnadmin lstxns myrepos`
$
</screen>
- <para>If you use these two subcommands like this, you should
- consider making your repository temporarily inaccessible to
- clients. That way, no one can begin a legitimate transaction
- before you start your cleanup. The following is a little bit
- of shell-scripting that can quickly generate information about
- each outstanding transaction in your repository:</para>
+ <para>If you use these two subcommands like this, you should
+ consider making your repository temporarily inaccessible to
+ clients. That way, no one can begin a legitimate
+ transaction before you start your cleanup. The following is
+ a little bit of shell-scripting that can quickly generate
+ information about each outstanding transaction in your
+ repository:</para>
- <example id="svn.reposadmin.maint.cleanup.ex-1">
- <title>txn-info.sh (Reporting Outstanding Transactions)</title>
+ <example id="svn.reposadmin.maint.cleanup.ex-1">
+ <title>txn-info.sh (Reporting Outstanding Transactions)</title>
- <programlisting>
+ <programlisting>
#!/bin/sh
### Generate informational output for all outstanding transactions in
@@ -1697,16 +1743,16 @@
svnlook info "${REPOS}" --transaction "${TXN}"
done
</programlisting>
- </example>
+ </example>
- <para>You can run the previous script using
- <command>/path/to/txn-info.sh /path/to/repos</command>. The
- output is basically a concatenation of several chunks of
- <command>svnlook info</command> output (see <xref
- linkend="svn.reposadmin.maint.tk.svnlook"/>), and will look something
- like:</para>
+ <para>You can run the previous script using
+ <command>/path/to/txn-info.sh /path/to/repos</command>. The
+ output is basically a concatenation of several chunks of
+ <command>svnlook info</command> output (see <xref
+ linkend="svn.reposadmin.maint.tk.svnlook"/>), and will look
+ something like:</para>
- <screen>
+ <screen>
$ txn-info.sh myrepos
---[ Transaction 19 ]-------------------------------------------
sally
@@ -1724,49 +1770,37 @@
$
</screen>
- <para>A long-abandoned transaction usually represents some sort
- of failed or interrupted commit. A transaction's datestamp
- can provide interesting information—for example, how
- likely is it that an operation begun nine months ago is still
- active?</para>
-
- <para>In short, transaction cleanup decisions need not be made
- unwisely. Various sources of information—including
- Apache's error and access logs, the logs of successful
- Subversion commits, and so on—can be employed in the
- decision-making process. Finally, an administrator can often
- simply communicate with a seemingly dead transaction's owner
- (via email, for example) to verify that the transaction is, in
- fact, in a zombie state.</para>
-
- </sect2>
+ <para>A long-abandoned transaction usually represents some
+ sort of failed or interrupted commit. A transaction's
+ datestamp can provide interesting information—for
+ example, how likely is it that an operation begun nine
+ months ago is still active?</para>
+
+ <para>In short, transaction cleanup decisions need not be made
+ unwisely. Various sources of information—including
+ Apache's error and access logs, the logs of successful
+ Subversion commits, and so on—can be employed in the
+ decision-making process. Finally, an administrator can
+ often simply communicate with a seemingly dead transaction's
+ owner (via email, for example) to verify that the
+ transaction is, in fact, in a zombie state.</para>
- <!-- =============================================================== -->
- <sect2 id="svn.reposadmin.maint.diskspace">
- <title>Managing Disk Space</title>
+ </sect3>
- <para>While the cost of storage has dropped incredibly in the
- past few years, disk usage is still a valid concern for
- administrators seeking to version large amounts of data.
- Every additional byte consumed by the live repository is a
- byte that needs to be backed up offsite, perhaps multiple
- times as part of rotating backup schedules. If using a
- Berkeley DB repository, the primary storage mechanism is a
- complex database system, it is useful to know what pieces of
- data need to remain on the live site, which need to be
- backed up, and which can be safely removed. This section is
- specific to Berkeley DB; FSFS repositories have no extra
- data to be cleaned up or reclaimed.</para>
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <sect3 id="svn.reposadmin.maint.diskspace.bdblogs">
+ <title>Purging unused Berkeley DB logfiles</title>
<para>Until recently, the largest offender of disk space usage
- with respect to Subversion repositories was the log files to
- which Berkeley DB performs its pre-writes before modifying
- the actual database files. These files capture all the
- actions taken along the route of changing the database from
- one state to another—while the database files reflect
- at any given time some state, the log files contain all the
- many changes along the way between states. As such, they
- can start to accumulate quite rapidly.</para>
+ with respect to BDB-backed Subversion repositories was the
+ log files to which Berkeley DB performs its pre-writes
+ before modifying the actual database files. These files
+ capture all the actions taken along the route of changing
+ the database from one state to another—while the
+ database files reflect at any given time some state, the log
+ files contain all the many changes along the way between
+ states. As such, they can start to accumulate quite
+ rapidly.</para>
<para>Fortunately, beginning with the 4.2 release of Berkeley
DB, the database environment has the ability to remove its
@@ -1799,7 +1833,7 @@
list-unused-dblogs</command> command to list the unused
log files:</para>
- <screen>
+ <screen>
$ svnadmin list-unused-dblogs /path/to/repos
/path/to/repos/log.0000000031
/path/to/repos/log.0000000032
@@ -1809,38 +1843,7 @@
## disk space reclaimed!
</screen>
- <para>To keep the size of the repository as small as possible,
- Subversion uses <firstterm>deltification</firstterm> (or,
- <quote>deltified storage</quote>) within the repository
- itself. Deltification involves encoding the representation
- of a chunk of data as a collection of differences against
- some other chunk of data. If the two pieces of data are
- very similar, this deltification results in storage savings
- for the deltified chunk—rather than taking up space
- equal to the size of the original data, it only takes up
- enough space to say, <quote>I look just like this other
- piece of data over here, except for the following couple of
- changes</quote>. Specifically, each time a new version of a
- file is committed to the repository, Subversion encodes the
- previous version (actually, several previous versions) as a
- delta against the new version. The result is that most of
- the repository data that tends to be sizable—namely,
- the contents of versioned files—is stored at a much
- smaller size than the original <quote>fulltext</quote>
- representation of that data.</para>
-
- <note>
- <para>Because all of the Subversion repository data that is
- subject to deltification is stored in a single Berkeley DB
- database file, reducing the size of the stored values will
- not necessarily reduce the size of the database file
- itself. Berkeley DB will, however, keep internal records
- of unused areas of the database file, and use those areas
- first before growing the size of the database file. So
- while deltification doesn't produce immediate space
- savings, it can drastically slow future growth of the
- database.</para>
- </note>
+ </sect3>
</sect2>
@@ -1848,11 +1851,18 @@
<sect2 id="svn.reposadmin.maint.recovery">
<title>Repository Recovery</title>
- <para>As mentioned in <xref linkend="svn.reposadmin.basics.backends.bdb"/>, a
- Berkeley DB repository can sometimes be left in frozen state
- if not closed properly. When this happens, an administrator
- needs to rewind the database back into a consistent
- state.</para>
+ <para>As mentioned in <xref
+ linkend="svn.reposadmin.basics.backends.bdb"/>, a Berkeley DB
+ repository can sometimes be left in frozen state if not closed
+ properly. When this happens, an administrator needs to rewind
+ the database back into a consistent state. This is unique to
+ BDB-backed repositories, though—if you are using
+ FSFS-backed ones instead, this won't apply to you. And for
+ those of you using Subversion 1.4 with Berkeley DB 4.4 or
+ better, you should find that Subversion has become much more
+ resilient in these types of situations. Still, wedged
+ Berkeley DB repositories do occur, and an administrator needs
+ to know how to safely deal with this circumstance.</para>
<para>In order to protect the data in your repository, Berkeley
DB uses a locking mechanism. This mechanism ensures that
@@ -1865,11 +1875,11 @@
data, makes the change it wants to make, and then unlocks the
data. Other processes are forced to wait until that lock is
removed before they are permitted to continue accessing that
- section of the database. (This has nothing to do with the
+ section of the database. (This has nothing to do with the
locks that you, as a user, can apply to versioned files within
- the repository; see
- <xref linkend="svn.advanced.locking.meanings"/> for more
- information.)</para>
+ the repository; we try to clear up the confusion caused by
+ this terminology collision in <xref
+ linkend="svn.advanced.locking.meanings" />.)</para>
<para>In the course of using your Subversion repository, fatal
errors (such as running out of disk space or available memory)
@@ -1957,71 +1967,39 @@
<title>Migrating Repository Data Elsewhere</title>
<para>A Subversion filesystem has its data spread throughout
- various database tables in a fashion generally understood by
- (and of interest to) only the Subversion developers
- themselves. However, circumstances may arise that call for
- all, or some subset, of that data to be collected into a
- single, portable, flat file format. Subversion provides such
- a mechanism, implemented in a pair of
+ various back-end data store files in a fashion generally
+ understood by (and of interest to) only the Subversion
+ developers themselves. However, circumstances may arise that
+ call for all, or some subset, of that data to be collected
+ into a single, portable, flat file format and copied or moved
+ into another repository. Subversion provides such
+ functionality, implemented in a pair of
<command>svnadmin</command> subcommands:
<literal>dump</literal> and <literal>load</literal>.</para>
- <para>The most common reason to dump and load a Subversion
- repository is due to changes in Subversion itself. As
- Subversion matures, there are times when certain changes made
- to the back-end database schema cause Subversion to be
- incompatible with previous versions of the repository. Other
- reasons for dumping and loading might be to migrate a Berkeley
- DB repository to a new OS or CPU architecture, or to switch
- between Berkeley DB and FSFS back-ends. The recommended
- course of action is relatively simple:</para>
-
- <orderedlist>
- <listitem>
- <para>Using your <emphasis>current</emphasis> version of
- <command>svnadmin</command>, dump your repositories to
- dump files.</para>
- </listitem>
- <listitem>
- <para>Upgrade to the new version of Subversion.</para>
- </listitem>
- <listitem>
- <para>Move your old repositories out of the way, and create
- new empty ones in their place using your
- <emphasis>new</emphasis> <command>svnadmin</command>.</para>
- </listitem>
- <listitem>
- <para>Again using your <emphasis>new</emphasis>
- <command>svnadmin</command>, load your dump files into
- their respective, just-created repositories.</para>
- </listitem>
- <listitem>
- <para>Be sure to copy any customizations from your old
- repositories to the new ones, including
- <filename>DB_CONFIG</filename> files and hook programs.
- You'll want to pay attention to the release notes for the
- new release of Subversion to see if any changes since your
- last upgrade affect those hooks or configuration
- options.</para>
- </listitem>
- <listitem>
- <para>If the migration process made your repository
- accessible at a different URL (e.g. moved to a different
- computer, or is being accessed via a different schema),
- then you'll probably want to tell your users to run
- <command>svn switch --relocate</command> on their existing
- working copies. See <xref
- linkend="svn.ref.svn.c.switch"/>.</para>
- </listitem>
- </orderedlist>
-
- <para><command>svnadmin dump</command> will output a range of
- repository revisions that are formatted using Subversion's
- custom filesystem dump format. The dump format is printed to
- the standard output stream, while informative messages are
- printed to the standard error stream. This allows you to
- redirect the output stream to a file while watching the status
- output in your terminal window. For example:</para>
+ <para>There are many reasons for dumping and loading Subversion
+ repository data. Early in Subversion's life, the most common
+ reason was due to changes in Subversion itself. As Subversion
+ matured, there were times when certain changes made to the
+ back-end database schema caused Subversion to be incompatible
+ with previous versions of the repository, so users had to dump
+ their repository data using the previous version of
+ Subversion, and load it into a freshly created repository with
+ the new version of Subversion. Other reasons for dumping and
+ loading including re-deploying a Berkeley DB repository on a
+ new OS or CPU architecture, or switching between the Berkeley
+ DB and FSFS back-ends.</para>
+
+ <para>Whatever your reason, using the <command>svnadmin
+ dump</command> and <command>svnadmin load</command>
+ subcommands is straightforward. <command>svnadmin
+ dump</command> will output a range of repository revisions
+ that are formatted using Subversion's custom filesystem dump
+ format. The dump format is printed to the standard output
+ stream, while informative messages are printed to the standard
+ error stream. This allows you to redirect the output stream
+ to a file while watching the status output in your terminal
+ window. For example:</para>
<screen>
$ svnlook youngest myrepos
@@ -2111,18 +2089,18 @@
</screen>
<para>By default, the dump file will be quite large—much
- larger than the repository itself. That's because every
- version of every file is expressed as a full text in the
- dump file. This is the fastest and simplest behavior, and nice
- if you're piping the dump data directly into some other
+ larger than the repository itself. That's because by default
+ every version of every file is expressed as a full text in the
+ dump file. This is the fastest and simplest behavior, and
+ nice if you're piping the dump data directly into some other
process (such as a compression program, filtering program, or
- into a loading process). But if you're creating a dump file for
- longer-term storage, you'll likely want to save disk space by
- using the <option>--deltas</option> switch. With this option,
- successive revisions of files will be output as compressed,
- binary differences—just as file revisions are stored in
- a repository. This option is slower, but results in a
- dump file much closer in size to the original
+ into a loading process). But if you're creating a dump file
+ for longer-term storage, you'll likely want to save disk space
+ by using the <option>--deltas</option> switch. With this
+ option, successive revisions of files will be output as
+ compressed, binary differences—just as file revisions
+ are stored in a repository. This option is slower, but
+ results in a dump file much closer in size to the original
repository.</para>
<para>We mentioned previously that <command>svnadmin
@@ -2253,9 +2231,17 @@
changes—each of which should be treated as a new
revision—using this file format. In fact, the
<command>cvs2svn</command> utility (see <xref
- linkend="svn.forcvs.convert"/>) uses the dump format to represent the
- contents of a CVS repository so that those contents can be
- copied into a Subversion repository.</para>
+ linkend="svn.forcvs.convert"/>) uses the dump format to
+ represent the contents of a CVS repository so that those
+ contents can be copied into a Subversion repository.</para>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.maint.replication">
+ <title>Repository Replication</title>
+
+ <para>### TODO</para>
</sect2>
@@ -2273,83 +2259,106 @@
topic—how to make backup copies of your repository
data.</para>
- <para>There are generally two types of backup methods available
- for Subversion repository administrators—incremental and
- full. We discussed in an earlier section of this chapter how
- to use <command>svnadmin dump --incremental</command> to
- perform an incremental backup (see <xref
- linkend="svn.reposadmin.maint.migrate"/>). Essentially, the idea is to
- only backup at a given time the changes to the repository
- since the last time you made a backup.</para>
-
- <para>A full backup of the repository is quite literally a
+ <para>There are two types of backup methods available for
+ Subversion repository administrators—full and
+ incremental. A full backup of the repository involves
+ squirreling away in one sweeping action all the information
+ required to fully reconstruct that repository in the event of
+ a catastrophe. Usually, it means quite literally the
duplication of the entire repository directory (which includes
- either Berkeley database or FSFS environment). Now, unless
- you temporarily disable all other access to your repository,
- simply doing a recursive directory copy runs the risk of
- generating a faulty backup, since someone might be currently
- writing to the database.</para>
-
- <para>In the case of Berkeley DB, the documentation describes a
- certain order in which database files can be copied that will
- guarantee a valid backup copy. And a similar ordering exists
- for FSFS data. Better still, you don't have to implement
- these algorithms yourself, because the Subversion development
- team has already done so. The
- <command>hot-backup.py</command> script is found in the
- <filename>tools/backup/</filename> directory of the Subversion
- source distribution. Given a repository path and a backup
- location, <command>hot-backup.py</command>—which is
- really just a more intelligent wrapper around the
- <command>svnadmin hotcopy</command> command—will perform
- the necessary steps for backing up your live
- repository—without requiring that you bar public
- repository access at all—and then will clean out the
- dead Berkeley log files from your live repository.</para>
-
- <para>Even if you also have an incremental backup, you might
- want to run this program on a regular basis. For example, you
- might consider adding <command>hot-backup.py</command> to a
- program scheduler (such as <command>cron</command> on Unix
- systems). Or, if you prefer fine-grained backup solutions,
- you could have your post-commit hook program call
- <command>hot-backup.py</command> (see <xref
- linkend="svn.reposadmin.create.hooks" />), which will then cause a new
- backup of your repository to occur with every new revision
- created. Simply add the following to the
- <filename>hooks/post-commit</filename> script in your live
- repository directory:</para>
+ either a Berkeley DB or FSFS environment). Incremental
+ backups are lesser things, backups of only the portion of the
+ repository data that has changed since the previous
+ backup.</para>
- <programlisting>
-(cd /path/to/hook/scripts; ./hot-backup.py ${REPOS} /path/to/backups &)
-</programlisting>
+ <para>We discussed in <xref
+ linkend="svn.reposadmin.maint.migrate" /> how to use
+ <command>svnadmin dump --incremental</command> to perform an
+ incremental backup based on the repository dump format. We'll
+ not spend much time discussing that method any further
+ here.</para>
+
+ <para>As far as full backups go, the naive approach might seem
+ like a sane one, but unless you temporarily disable all other
+ access to your repository, simply doing a recursive directory
+ copy runs the risk of generating a faulty backup. In the case
+ of Berkeley DB, the documentation describes a certain order in
+ which database files can be copied that will guarantee a valid
+ backup copy. A similar ordering exists for FSFS data. But
+ you don't have to implement these algorithms yourself, because
+ the Subversion development team has already done so. The
+ <command>svnadmin hotcopy</command> command takes care of the
+ minutia involved in making a <firstterm>hot backup</firstterm>
+ (that is, a backup made without interrupting the repository's
+ general accessibility) of your repository. And its invocation
+ is as trivial as Unix's <command>cp</command> or Windows'
+ <command>copy</command> operations:</para>
+
+ <screen>
+$ svnadmin hotcopy /path/to/repos /path/to/repos-backup
+</screen>
<para>The resulting backup is a fully functional Subversion
repository, able to be dropped in as a replacement for your
live repository should something go horribly wrong.</para>
- <para>There are benefits to both types of backup methods. The
- easiest is by far the full backup, which will always result in
- a perfect working replica of your repository. This again
- means that should something bad happen to your live
- repository, you can restore from the backup with a simple
- recursive directory copy. Unfortunately, if you are
- maintaining multiple backups of your repository, these full
- copies will each eat up just as much disk space as your live
- repository.</para>
-
- <para>Incremental backups using the repository dump format are
- excellent to have on hand if the database schema changes
- between successive versions of Subversion itself. Since a
- complete repository dump and load are generally required to
- upgrade your repository to the new schema, it's very
- convenient to already have half of that process (the dump
- part) finished. Unfortunately, the creation of—and
- restoration from—incremental backups takes longer, as
- each commit is effectively replayed into either the dump file
- or the repository.</para>
+ <para>When making copies of a Berkeley DB repository, you can
+ even instruct <command>svnadmin hotcopy</command> to purge any
+ unused Berkeley DB logfiles (see <xref
+ linkend="svn.reposadmin.maint.diskspace.bdblogs" />) from the
+ original repository upon completion of the copy. Simply
+ provide the <option>--clean-logs</option> option on the
+ command-line.</para>
+
+ <screen>
+$ svnadmin hotcopy --clean-logs /path/to/bdb-repos /path/to/bdb-repos-backup
+</screen>
+
+ <para>There's additional tooling around this command that's
+ available, too. The <filename>tools/backup/</filename>
+ directory of the Subversion source distribution holds the
+ <command>hot-backup.py</command> script. This script adds a
+ bit of backup management atop <command>svnadmin
+ hotcopy</command>, allowing you to keep only the most recent
+ configured number of backups of each repository. It will
+ automatically manage the names of the backed-up repository
+ directories to avoid collisions with previous backups, and
+ will <quote>rotate off</quote> older backups, deleting them so
+ only the most ones remain. Even if you also have an
+ incremental backup, you might want to run this program on a
+ regular basis. For example, you might consider using
+ <command>hot-backup.py</command> from a program scheduler
+ (such as <command>cron</command> on Unix systems) which will
+ cause it to run nightly (or at whatever granularity of Time
+ you deem safe enough for you).</para>
+
+ <para>There are advantages and disadvantages to both backup
+ types. The easiest is by far the full backup, which will
+ always result in a perfect working replica of your repository.
+ Should something bad happen to your live repository, you can
+ restore from the backup with a simple recursive directory
+ copy. Unfortunately, if you are maintaining multiple backups
+ of your repository, these full copies will each eat up just as
+ much disk space as your live repository. Incremental backups,
+ by contrast, tend to be quicker to generate and smaller to
+ store. But the restoration process can be a pain, often
+ involving applying multiple incremental backups.</para>
+
+ <para>The <command>svnsync</command> program (see <xref
+ linkend="svn.reposadmin.maint.replication" />) actually
+ provides a rather handy middle-ground approach. If you are
+ regularly syncronizing a read-only mirror with your main
+ repository, then in a pinch, your read-only mirror is probably
+ a good candidate for replacing that main repository if it
+ falls over. The primary disadvantage of this method is that
+ only the versioned repository data gets
+ syncronized—repository configuration files,
+ user-specified repository path locks, and other items which
+ might live in the physical repository directory but not
+ <emphasis>inside</emphasis> the repository's virtual versioned
+ filesystem are not handled by svnsync.</para>
- <para>In either backup scenario, repository administrators need
+ <para>In any backup scenario, repository administrators need
to be aware of how modifications to unversioned revision
properties affect their backups. Since these changes do not
themselves generate new revisions, they will not trigger
@@ -2373,20 +2382,22 @@
granularity (like per-commit emails), a hot backup of the
database might be something that a repository administrator
would want to include as part of a system-wide nightly backup.
- For most repositories, archived commit emails alone provide
+ For many repositories, archived commit emails provide
sufficient redundancy as restoration sources, at least for the
- most recent few commits. But it's your data—protect it
- as much as you'd like.</para>
+ most recent few commits (and where the files being modified
+ are human-readable). But it's your data—protect it as
+ much as you'd like.</para>
<para>Often, the best approach to repository backups is a
diversified one. You can leverage combinations of full and
incremental backups, plus archives of commit emails. The
Subversion developers, for example, back up the Subversion
- source code repository after every new revision is created,
- and keep an archive of all the commit and property change
- notification emails. Your solution might be similar, but
- should be catered to your needs and that delicate balance of
- convenience with paranoia. And while all of this might not
+ source code repository nightly, keep multiple archives of all
+ the commit and property change notification emails, and almost
+ certainly have the repository mirrored by various folks using
+ <command>svnsync</command>. Your solution might be similar,
+ but should be catered to your needs and that delicate balance
+ of convenience with paranoia. And while all of this might not
save your hardware from the iron fist of Fate,
<footnote>
<para>You know—the collective term for all of her
@@ -2397,234 +2408,6 @@
</sect2>
- <!-- =============================================================== -->
- <sect2 id="svn.reposadmin.maint.replicating">
- <title>Replicating a Repository</title>
-
- <para>### TODO</para>
-
- </sect2>
-
- </sect1>
-
-
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.reposadmin.projects">
- <title>Adding Projects</title>
-
- <para>Once your repository is created and configured, all that
- remains is to begin using it. If you have a collection of
- existing data that is ready to be placed under version control,
- you will more than likely want to use the <command>svn</command>
- client program's <literal>import</literal> subcommand to
- accomplish that. Before doing this, though, you should
- carefully consider your long-term plans for the repository. In
- this section, we will offer some advice on how to plan the
- layout of your repository, and how to get your data arranged in
- that layout.</para>
-
- <!-- =============================================================== -->
- <sect2 id="svn.reposadmin.projects.chooselayout">
- <title>Choosing a Repository Layout</title>
-
- <para>While Subversion allows you to move around versioned files
- and directories without any loss of information, doing so can
- still disrupt the workflow of those who access the repository
- often and come to expect things to be at certain locations.
- Try to peer into the future a bit; plan ahead before placing
- your data under version control. By <quote>laying out</quote>
- the contents of your repositories in an effective manner the
- first time, you can prevent a load of future headaches.</para>
-
- <para>There are a few things to consider when setting up
- Subversion repositories. Let's assume that as repository
- administrator, you will be responsible for supporting the
- version control system for several projects. The first
- decision is whether to use a single repository for multiple
- projects, or to give each project its own repository, or some
- compromise of these two.</para>
-
- <para>There are benefits to using a single repository for
- multiple projects, most obviously the lack of duplicated
- maintenance. A single repository means that there is one set
- of hook programs, one thing to routinely backup, one thing to
- dump and load if Subversion releases an incompatible new
- version, and so on. Also, you can move data between projects
- easily, and without losing any historical versioning
- information.</para>
-
- <para>The downside of using a single repository is that
- different projects may have different commit mailing lists or
- different authentication and authorization requirements.
- Also, remember that Subversion uses repository-global revision
- numbers. Some folks don't like the fact that even though no
- changes have been made to their project lately, the youngest
- revision number for the repository keeps climbing because
- other projects are actively adding new revisions.</para>
-
- <para>A middle-ground approach can be taken, too. For example,
- projects can be grouped by how well they relate to each other.
- You might have a few repositories with a handful of projects
- in each repository. That way, projects that are likely to
- want to share data can do so easily, and as new revisions are
- added to the repository, at least the developers know that
- those new revisions are at least remotely related to everyone
- who uses that repository.</para>
-
- <para>After deciding how to organize your projects with respect
- to repositories, you'll probably want to think about directory
- hierarchies in the repositories themselves. Because
- Subversion uses regular directory copies for branching and
- tagging (see <xref linkend="svn.branchmerge"/>), the Subversion
- community recommends that you choose a repository location for
- each <firstterm>project root</firstterm>—the
- <quote>top-most</quote> directory which contains data related
- to that project—and then create three subdirectories
- beneath that root: <filename>trunk</filename>, meaning the
- directory under which the main project development occurs;
- <filename>branches</filename>, which is a directory in which
- to create various named branches of the main development line;
- <filename>tags</filename>, which is a directory of branches
- that are created, and perhaps destroyed, but never
- changed.
- <footnote>
- <para>The <filename>trunk</filename>, <filename>tags</filename>,
- and <filename>branches</filename> trio are sometimes referred
- to as <quote>the TTB directories</quote>.</para>
- </footnote>
- </para>
-
- <para>For example, your repository might look like:</para>
-
- <screen>
-/
- calc/
- trunk/
- tags/
- branches/
- calendar/
- trunk/
- tags/
- branches/
- spreadsheet/
- trunk/
- tags/
- branches/
- …
-</screen>
-
- <para>Note that it doesn't matter where in your repository each
- project root is. If you have only one project per repository,
- the logical place to put each project root is at the root of
- that project's respective repository. If you have multiple
- projects, you might want to arrange them in groups inside the
- repository, perhaps putting projects with similar goals or
- shared code in the same subdirectory, or maybe just grouping
- them alphabetically. Such an arrangement might look
- like:</para>
-
- <screen>
-/
- utils/
- calc/
- trunk/
- tags/
- branches/
- calendar/
- trunk/
- tags/
- branches/
- …
- office/
- spreadsheet/
- trunk/
- tags/
- branches/
- …
-</screen>
-
- <para>Lay out your repository in whatever way you see fit.
- Subversion does not expect or enforce a layout schema—in
- its eyes, a directory is a directory is a directory.
- Ultimately, you should choose the repository arrangement that
- meets the needs of the people who work on the projects that
- live there.</para>
-
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.reposadmin.projects.import">
- <title>Creating the Layout, and Importing Initial Data</title>
-
- <para>After deciding how to arrange the projects in your
- repository, you'll probably want to actually populate the
- repository with that layout and with initial project data.
- There are a couple of ways to do this in Subversion. You
- could use the <command>svn mkdir</command> command (see <xref
- linkend="svn.ref"/>) to create each directory in your
- skeletal repository layout, one-by-one. A quicker way to
- accomplish the same task is to use the <command>svn
- import</command> command (see <xref
- linkend="svn.tour.importing"/>). By first creating the layout
- in a temporary location on your drive, you can import the
- whole layout tree into the repository in a single
- commit:</para>
-
- <screen>
-$ mkdir tmpdir
-$ cd tmpdir
-$ mkdir projectA
-$ mkdir projectA/trunk
-$ mkdir projectA/branches
-$ mkdir projectA/tags
-$ mkdir projectB
-$ mkdir projectB/trunk
-$ mkdir projectB/branches
-$ mkdir projectB/tags
-…
-$ svn import . file:///path/to/repos --message "Initial repository layout"
-Adding projectA
-Adding projectA/trunk
-Adding projectA/branches
-Adding projectA/tags
-Adding projectB
-Adding projectB/trunk
-Adding projectB/branches
-Adding projectB/tags
-…
-Committed revision 1.
-$ cd ..
-$ rm -rf tmpdir
-$
-</screen>
-
- <para>You can verify the results of the import by running the
- <command>svn list</command> command:</para>
-
- <screen>
-$ svn list --verbose file:///path/to/repos
- 1 harry May 08 21:48 projectA/
- 1 harry May 08 21:48 projectB/
-…
-$
-</screen>
-
- <para>Once you have your skeletal layout in place, you can begin
- importing actual project data into your repository, if any
- such data exists yet. Once again, there are several ways to
- do this. You could use the <command>svn import</command>
- command. You could checkout a working copy from your new
- repository, move and arrange project data inside the working
- copy, and use the <command>svn add</command> and <command>svn
- commit</command> commands. But once we start talking about
- such things, we're no longer discussing repository
- administration. If you aren't already familiar with the
- <command>svn</command> client program, see <xref
- linkend="svn.tour"/>.</para>
-
- </sect2>
</sect1>
<!-- ================================================================= -->
More information about the svnbook-dev
mailing list