[svnbook commit] r3215 - trunk/src/en/book
cmpilato
noreply at red-bean.com
Mon Jul 28 20:59:09 CDT 2008
Author: cmpilato
Date: Mon Jul 28 20:59:09 2008
New Revision: 3215
Log:
Enter O'Reilly second-round copyedits.
Modified:
trunk/src/en/book/ch05-repository-admin.xml
Modified: trunk/src/en/book/ch05-repository-admin.xml
==============================================================================
--- trunk/src/en/book/ch05-repository-admin.xml (original)
+++ trunk/src/en/book/ch05-repository-admin.xml Mon Jul 28 20:59:09 2008
@@ -18,7 +18,7 @@
the repository.</para>
<para>If you plan to access a Subversion repository only in the
- role of a user whose data is under version control (that is, via
+ role of a user whose data is under version control (i.e., via
a Subversion client), you can skip this chapter altogether.
However, if you are, or wish to become, a Subversion repository
administrator,
@@ -48,7 +48,7 @@
<emphasis>inside</emphasis> the repository.</para>
<para>Seen through the eyes of a typical file browser application
- (such as the Windows Explorer) or command-line based filesystem
+ (such as Windows Explorer) or command-line based filesystem
navigation tools, the Subversion repository is just another
directory full of stuff. There are some subdirectories with
human-readable configuration files in them, some subdirectories
@@ -73,7 +73,7 @@
<varlistentry>
<term>conf</term>
<listitem>
- <para>A directory containing configuration files.</para>
+ <para>A directory containing configuration files</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -81,41 +81,41 @@
<listitem>
<para>A directory provided to
<filename>mod_dav_svn</filename> for its private
- housekeeping data.</para>
+ housekeeping data</para>
</listitem>
</varlistentry>
<varlistentry>
<term>db</term>
<listitem>
- <para>The data store for all of your versioned data.</para>
+ <para>The data store for all of your versioned data</para>
</listitem>
</varlistentry>
<varlistentry>
<term>format</term>
<listitem>
<para>A file that contains a single integer that
- indicates the version number of the repository layout.</para>
+ indicates the version number of the repository layout</para>
</listitem>
</varlistentry>
<varlistentry>
<term>hooks</term>
<listitem>
<para>A directory full of hook script templates (and hook
- scripts themselves, once you've installed some).</para>
+ scripts themselves, once you've installed some)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>locks</term>
<listitem>
<para>A directory for Subversion's repository lock
- files, used for tracking accessors to the repository.</para>
+ files, used for tracking accessors to the repository</para>
</listitem>
</varlistentry>
<varlistentry>
<term>README.txt</term>
<listitem>
<para>A file whose contents merely inform its readers that
- they are looking at a Subversion repository.</para>
+ they are looking at a Subversion repository</para>
</listitem>
</varlistentry>
</variablelist>
@@ -126,7 +126,7 @@
filesystem, complete with customizable event triggers. This
filesystem has its own notions of directories and files, very
similar to the notions of such things held by real filesystems
- (such as NTFS, FAT32, ext3, and so on). But this is a special
+ (such as NTFS, FAT32, ext3, etc.). But this is a special
filesystem—it hangs these directories and files from
revisions, keeping all the changes you've ever made to them
safely stored and forever accessible. This is where the
@@ -145,11 +145,11 @@
creating and configuring a repository are fairly straightforward
tasks. There are a few preliminary decisions you'll want to
make, but the actual work involved in any given setup of a
- Subversion repository is pretty basic, tending towards
+ Subversion repository is pretty basic, tending toward
mindless repetition if you find yourself setting up multiples of
these things.</para>
- <para>Some things you'll want to consider up front, though, are:</para>
+ <para>Some things you'll want to consider beforehand, though, are:</para>
<itemizedlist>
<listitem>
@@ -247,7 +247,7 @@
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
+ root</firstterm>—the <quote>topmost</quote> directory
that contains data related to that project—and then
create three subdirectories beneath that root:
<filename>trunk</filename>, meaning the directory under which
@@ -259,12 +259,12 @@
changed.
<footnote>
<para>The <filename>trunk</filename>, <filename>tags</filename>,
- and <filename>branches</filename> trio are sometimes referred
+ and <filename>branches</filename> trio is sometimes referred
to as <quote>the TTB directories.</quote></para>
</footnote>
</para>
- <para>For example, your repository might look like:</para>
+ <para>For example, your repository might look like this:</para>
<screen>
/
@@ -291,7 +291,7 @@
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>
+ like this:</para>
<screen>
/
@@ -325,7 +325,7 @@
<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>
+ subdirectories beneath those, like so:</para>
<screen>
/
@@ -351,9 +351,9 @@
users. Especially in large, multiproject 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
+ projects-as-branch-siblings approach tends to deemphasize project
individuality and focus on the entire set of projects as a
- single entity. That's a social issue though. We like our
+ 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
@@ -443,68 +443,68 @@
<entry morerows="1">Reliability</entry>
<entry>Data integrity</entry>
<entry>When properly deployed, extremely reliable;
- Berkeley DB 4.4 brings auto-recovery.</entry>
+ Berkeley DB 4.4 brings auto-recovery</entry>
<entry>Older versions had some rarely demonstrated, but
- data-destroying bugs.</entry>
+ data-destroying bugs</entry>
</row>
<row>
<entry>Sensitivity to interruptions</entry>
<entry>Very; crashes and permission problems can leave the
database <quote>wedged,</quote> requiring journaled
- recovery procedures.</entry>
- <entry>Quite insensitive.</entry>
+ recovery procedures</entry>
+ <entry>Quite insensitive</entry>
</row>
<row>
<entry morerows="3">Accessibility</entry>
<entry>Usable from a read-only mount</entry>
- <entry>No.</entry>
- <entry>Yes.</entry>
+ <entry>No</entry>
+ <entry>Yes</entry>
</row>
<row>
<entry>Platform-independent storage</entry>
- <entry>No.</entry>
- <entry>Yes.</entry>
+ <entry>No</entry>
+ <entry>Yes</entry>
</row>
<row>
<entry>Usable over network filesystems</entry>
- <entry>Generally, no.</entry>
- <entry>Yes.</entry>
+ <entry>Generally, no</entry>
+ <entry>Yes</entry>
</row>
<row>
<entry>Group permissions handling</entry>
<entry>Sensitive to user umask problems; best if accessed
- by only one user.</entry>
- <entry>Works around umask problems.</entry>
+ by only one user</entry>
+ <entry>Works around umask problems</entry>
</row>
<row>
<entry morerows="2">Scalability</entry>
<entry>Repository disk usage</entry>
- <entry>Larger (especially if logfiles aren't purged).</entry>
- <entry>Smaller.</entry>
+ <entry>Larger (especially if logfiles aren't purged)</entry>
+ <entry>Smaller</entry>
</row>
<row>
<entry>Number of revision trees</entry>
- <entry>Database; no problems.</entry>
+ <entry>Database; no problems</entry>
<entry>Some older native filesystems don't scale well with
- thousands of entries in a single directory.</entry>
+ thousands of entries in a single directory</entry>
</row>
<row>
<entry>Directories with many files</entry>
- <entry>Slower.</entry>
- <entry>Faster.</entry>
+ <entry>Slower</entry>
+ <entry>Faster</entry>
</row>
<row>
<entry morerows="1">Performance</entry>
<entry>Checking out latest revision</entry>
- <entry>No meaningful difference.</entry>
- <entry>No meaningful difference.</entry>
+ <entry>No meaningful difference</entry>
+ <entry>No meaningful difference</entry>
</row>
<row>
<entry>Large commits</entry>
<entry>Slower overall, but cost is amortized across the
- lifetime of the commit.</entry>
+ lifetime of the commit</entry>
<entry>Faster overall, but finalization delay may cause
- client timeouts.</entry>
+ client timeouts</entry>
</row>
</tbody>
</tgroup>
@@ -545,7 +545,7 @@
progress, the developers decided to use Berkeley DB for a
variety of reasons, including its open source license,
transaction support, reliability, performance, API
- simplicity, thread-safety, support for cursors, and so
+ simplicity, thread safety, support for cursors, and so
on.</para>
<para>Berkeley DB provides real transaction
@@ -558,7 +558,7 @@
is constantly changing at the hand of some other
process—and can make decisions based on that view. If
the decision made happens to conflict with what another
- process is doing, the entire operation is rolled back as if
+ process is doing, the entire operation is rolled back as though
it never happened, and Subversion gracefully retries the
operation against a new, updated (and yet still static) view
of the database.</para>
@@ -591,11 +591,11 @@
Subversion repository that was created on a Unix system onto
a Windows system and expect it to work. While much of the
Berkeley DB database format is architecture-independent,
- there are other aspects of the environment that are not.
- Secondly, Subversion uses Berkeley DB in a way that will not
+ other aspects of the environment are not.
+ Second, Subversion uses Berkeley DB in a way that will not
operate on Windows 95/98 systems—if you need to house
a BDB-backed repository on a Windows machine, stick with
- Windows 2000 or newer.</para>
+ Windows 2000 or later.</para>
<para>While Berkeley DB promises to behave correctly on
network shares that meet a particular set of specifications,
@@ -644,14 +644,14 @@
ownership and permissions on the database files.</para>
<note>
- <para>Berkeley DB 4.4 brings (to Subversion 1.4 and better)
+ <para>Berkeley DB 4.4 brings (to Subversion 1.4 and later)
the ability for Subversion to automatically and
transparently recover Berkeley DB environments in need of
such recovery. When a Subversion process attaches to a
repository's Berkeley DB environment, it uses some process
accounting mechanisms to detect any unclean disconnections
by previous processes, performs any necessary recovery,
- and then continues on as if nothing happened. This
+ and then continues on as though nothing happened. This
doesn't completely eliminate instances of repository
wedging, but it does drastically reduce the amount of
human interaction required to recover from them.</para>
@@ -663,7 +663,7 @@
or <command>svnserve</command> (see <xref
linkend="svn.serverconfig"/>)—rather than accessing it
as many different users via <literal>file://</literal> or
- <literal>svn+ssh://</literal> URLs. If accessing a Berkeley
+ <literal>svn+ssh://</literal> URLs. If you're accessing a Berkeley
DB repository directly as multiple users, be sure to read
<xref linkend="svn.serverconfig.multimethod"/> later in this
chapter.</para>
@@ -693,19 +693,19 @@
in other revision trees. Unlike a Berkeley DB database,
this storage format is portable across different operating
systems and isn't sensitive to CPU architecture. Because
- there's no journaling or shared-memory files being used, the
+ no journaling or shared-memory files are being used, the
repository can be safely accessed over a network filesystem
and examined in a read-only environment. The lack of
- database overhead also means that the overall repository
+ database overhead also means the overall repository
size is a bit smaller.</para>
- <para>FSFS has different performance characteristics too.
+ <para>FSFS has different performance characteristics, too.
When committing a directory with a huge number of files,
FSFS is able to more quickly append directory entries. On
the other hand, FSFS writes the latest version of a file as
a delta against an earlier version, which means that
checking out the latest tree is a bit slower than fetching
- the fulltexts stored in a Berkeley DB HEAD revision. FSFS
+ the full-texts 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 while
waiting for a response.</para>
@@ -729,7 +729,7 @@
</footnote>
FSFS is a newer bit of engineering. Prior to Subversion
1.4, it was still shaking out some pretty serious data
- integrity bugs, which, while only triggered in very rare
+ integrity bugs, which, while triggered in only very rare
cases, nonetheless did occur. That said, FSFS has quickly
become the backend of choice for some of the largest public
and private Subversion repositories, and it promises a lower
@@ -746,7 +746,7 @@
<sect1 id="svn.reposadmin.create">
<title>Creating and Configuring Your Repository</title>
- <para>Earlier, in <xref linkend="svn.reposadmin.planning" />, we
+ <para>Earlier in this chapter (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! In this section,
@@ -845,7 +845,7 @@
or the modification of an unversioned property. Some hooks
(the so-called <quote>pre hooks</quote>) run in advance of a
repository operation and provide a means by which to both
- report what is about to happen and to prevent it from
+ report what is about to happen and prevent it from
happening at all. Other hooks (the <quote>post hooks</quote>)
run after the completion of a repository event and are useful
for performing tasks that examine—but don't
@@ -931,11 +931,11 @@
the big picture of how your repository is deployed.
For example, if you are using server configuration
to determine which users are permitted to commit
- changes to your repository, then you don't need to do this
+ changes to your repository, you don't need to do this
sort of access control via the hook system.</para>
<para>There is no shortage of Subversion hook programs and
- scripts freely available either from the Subversion community
+ scripts that are freely available either from the Subversion community
itself or elsewhere. These scripts cover a wide range of
utility—basic access control, policy adherence checking,
issue tracker integration, email- or syndication-based commit
@@ -969,11 +969,11 @@
<title>Berkeley DB Configuration</title>
<para>A Berkeley DB environment is an encapsulation of one or
- more databases, logfiles, region files and configuration
+ more databases, logfiles, region files, and configuration
files. The Berkeley DB environment has its own set of default
configuration values for things such as the number of database
locks allowed to be taken out at any given time, the maximum
- size of the journaling logfiles, etc. Subversion's
+ size of the journaling logfiles, and so on. Subversion's
filesystem logic additionally chooses default values for some
of the Berkeley DB configuration options. However, sometimes
your particular repository, with its unique collection of data
@@ -991,7 +991,7 @@
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
+ documentation so that 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
@@ -1020,7 +1020,7 @@
section will introduce you to the repository administration
tools provided by Subversion and discuss how to wield them to
accomplish tasks such as repository data migration, upgrades,
- backups and cleanups.</para>
+ backups, and cleanups.</para>
<!-- =============================================================== -->
<sect2 id="svn.reposadmin.maint.tk">
@@ -1161,17 +1161,17 @@
<orderedlist>
<listitem>
- <para>The author, followed by a newline.</para>
+ <para>The author, followed by a newline</para>
</listitem>
<listitem>
- <para>The date, followed by a newline.</para>
+ <para>The date, followed by a newline</para>
</listitem>
<listitem>
<para>The number of characters in the log message,
- followed by a newline.</para>
+ followed by a newline</para>
</listitem>
<listitem>
- <para>The log message itself, followed by a newline.</para>
+ <para>The log message itself, followed by a newline</para>
</listitem>
</orderedlist>
@@ -1313,7 +1313,7 @@
<command>fsfs-reshard.py</command> comes in. This script
reshuffles the repository's file structure into a new
arrangement that reflects the requested number of sharding
- subdirecties. This is especially useful for converting an
+ subdirectories. This is especially useful for converting an
older Subversion repository into the new Subversion 1.5
sharded layout (which Subversion will not automatically do
for you) or for fine-tuning an already sharded
@@ -1325,7 +1325,7 @@
<sect3 id="svn.reposadmin.maint.tk.bdbutil">
<title>Berkeley DB utilities</title>
- <para>If you're using a Berkeley DB repository, then all of
+ <para>If you're using a Berkeley DB repository, all of
your versioned filesystem's structure and data live in a set
of database tables within the <filename>db/</filename>
subdirectory of your repository. This subdirectory is a
@@ -1341,7 +1341,7 @@
<command>svnadmin list-unused-dblogs</command> and
<command>svnadmin list-dblogs</command> perform a
subset of what is provided by the Berkeley
- <command>db_archive</command> command, and <command>svnadmin
+ <command>db_archive</command> utility, and <command>svnadmin
recover</command> reflects the common use cases of the
<command>db_recover</command> utility.</para>
@@ -1384,7 +1384,7 @@
repository is configured (using the
<literal>pre-revprop-change</literal> hook; see <xref
linkend="svn.reposadmin.create.hooks"/>) to accept changes to
- this log message after the commit is finished, then the user
+ this log message after the commit is finished, the user
can <quote>fix</quote> her log message remotely using
<command>svn propset</command> (see <xref
linkend="svn.ref.svn.c.propset"/>). However, because of the
@@ -1446,8 +1446,8 @@
<title>How Subversion saves disk space</title>
<para>To keep the repository small,
- Subversion uses <firstterm>deltification</firstterm> (or,
- <quote>deltified storage</quote>) within the repository
+ Subversion uses <firstterm>deltification</firstterm> (or
+ deltified storage) 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
@@ -1459,10 +1459,10 @@
changes.</quote> The result is that most of the repository
data that tends to be bulky—namely, the contents of
versioned files—is stored at a much smaller size than
- the original <quote>fulltext</quote> representation of that
+ the original full-text representation of that
data. And for repositories created with Subversion 1.4 or
later, the space savings are even better—now those
- fulltext representations of file contents are themselves
+ full-text representations of file contents are themselves
compressed.</para>
<note>
@@ -1515,7 +1515,7 @@
to determine who created the transaction, when it was
created, what types of changes were made in the
transaction—information that is helpful in determining
- whether or not the transaction is a safe candidate for
+ whether the transaction is a safe candidate for
removal! If you do indeed want to remove a transaction, its
name can be passed to <command>svnadmin rmtxns</command>,
which will perform the cleanup of the transaction. In fact,
@@ -1562,7 +1562,7 @@
<para>The output of the script 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>
+ will look something like this:</para>
<screen>
$ txn-info.sh myrepos
@@ -1594,7 +1594,7 @@
logs, Subversion revision history, and so on—can be
employed in the decision-making process. And of course, an
administrator can often simply communicate with a seemingly
- dead transaction's owner (via email, for example) to verify
+ dead transaction's owner (via email, e.g.) to verify
that the transaction is, in fact, in a zombie state.</para>
</sect3>
@@ -1610,7 +1610,7 @@
all the actions taken along the route of changing the
database from one state to another—while the database
files, at any given time, reflect a particular state, the
- logfiles contain all the many changes along the way
+ logfiles contain all of the many changes along the way
<emphasis>between</emphasis> states. Thus, they can grow
and accumulate quite rapidly.</para>
@@ -1618,8 +1618,8 @@
DB, the database environment has the ability to remove its
own unused logfiles automatically. Any
repositories created using <command>svnadmin</command>
- when compiled against Berkeley DB version 4.2 or greater
- will be configured for this automatic log file removal. If
+ when compiled against Berkeley DB version 4.2 or later
+ will be configured for this automatic logfile removal. If
you don't want this feature enabled, simply pass the
<option>--bdb-log-keep</option> option to the
<command>svnadmin create</command> command. If you forget
@@ -1633,7 +1633,7 @@
linkend="svn.reposadmin.create.bdb"/> for more information about
database configuration.</para>
- <para>Without some sort of automatic log file removal in
+ <para>Without some sort of automatic logfile removal in
place, logfiles will accumulate as you use your repository.
This is actually somewhat of a feature of the database
system—you should be able to recreate your entire
@@ -1658,13 +1658,13 @@
<warning>
<para>BDB-backed repositories whose logfiles are used as
part of a backup or disaster recovery plan should
- <emphasis>not</emphasis> make use of the log file
+ <emphasis>not</emphasis> make use of the logfile
autoremoval feature. Reconstruction of a repository's
- data from logfiles can only be accomplished when
+ data from logfiles can only be accomplished only when
<emphasis>all</emphasis> the logfiles are available. If
some of the logfiles are removed from disk before the
backup system has a chance to copy them elsewhere, the
- incomplete set of backed-up log files is essentially
+ incomplete set of backed-up logfiles is essentially
useless.</para> </warning>
</sect3>
@@ -1683,12 +1683,12 @@
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
+ later, 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
+ <para>To protect the data in your repository, Berkeley
DB uses a locking mechanism. This mechanism ensures that
portions of the database are not simultaneously modified by
multiple database accessors, and that each process sees the
@@ -1702,7 +1702,7 @@
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; we try to clear up the confusion caused by
- this terminology collision in <xref
+ this terminology collision in the sidebar <xref
linkend="svn.advanced.locking.meanings" />.)</para>
<para>In the course of using your Subversion repository, fatal
@@ -1719,7 +1719,7 @@
transactions, checkpoints, and prewrite journaling to
ensure that only the most catastrophic of events
<footnote>
- <para>e.g., hard drive + huge electromagnet = disaster</para>
+ <para>For example, hard drive + huge electromagnet = disaster.</para>
</footnote>
can permanently destroy a database environment. A
sufficiently paranoid repository administrator will have made
@@ -1731,7 +1731,7 @@
<orderedlist>
<listitem>
- <para>Make sure that there are no processes accessing (or
+ <para>Make sure no processes are accessing (or
attempting to access) the repository. For networked
repositories, this also means shutting down the Apache HTTP
Server or svnserve daemon.</para>
@@ -1746,7 +1746,7 @@
</listitem>
<listitem>
<para>Run the command <userinput>svnadmin recover
- /var/svn/repos</userinput>. You should see output like
+ /var/svn/repos</userinput>. You should see output such as
this:</para>
<screen>
@@ -1767,8 +1767,8 @@
wedging. Make sure that you run this command as the user that
owns and manages the database, not just as
<literal>root</literal>. Part of the recovery process might
- involve recreating from scratch various database files (shared
- memory regions, for example). Recovering as
+ involve re-creating from scratch various database files (shared
+ memory regions, e.g.). Recovering as
<literal>root</literal> will create those files such that they
are owned by <literal>root</literal>, which means that even
after you restore connectivity to your repository, regular
@@ -1814,8 +1814,8 @@
<warning>
<para>While the Subversion repository dump format contains
human-readable portions and a familiar structure (it
- resembles an RFC-822 format, the same type of format used
- for most email), it is <emphasis>not</emphasis> a plaintext
+ resembles an RFC 822 format, the same type of format used
+ for most email), it is <emphasis>not</emphasis> a plain-text
file format. It is a binary file format, highly sensitive
to meddling. For example, many text editors will corrupt
the file by automatically converting line endings.</para>
@@ -1837,7 +1837,7 @@
are still other reasons for dumping and loading, including
re-deploying a Berkeley DB repository on a new OS or CPU
architecture, switching between the Berkeley DB and FSFS
- backends, or (as we'll cover later in <xref
+ backends, or (as we'll cover later in this chapter in <xref
linkend="svn.reposadmin.maint.filtering" />) purging versioned
data from repository history.</para>
@@ -1879,7 +1879,7 @@
requested range of revisions. Note that <command>svnadmin
dump</command> is reading revision trees from the repository
just like any other <quote>reader</quote> process would
- (<command>svn checkout</command>, for example), so it's safe
+ (e.g., <command>svn checkout</command>), so it's safe
to run this command at any time.</para>
<para>The other subcommand in the pair, <command>svnadmin
@@ -1940,8 +1940,8 @@
<para>Note that because <command>svnadmin</command> uses
standard input and output streams for the repository dump and
- load process, people who are feeling especially saucy can try
- things like this (perhaps even using different versions of
+ load processes, people who are feeling especially saucy can try
+ things such as this (perhaps even using different versions of
<command>svnadmin</command> on each side of the pipe):</para>
<screen>
@@ -1960,7 +1960,7 @@
by using the <option>--deltas</option> option. 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
+ are stored in a repository. This option is slower, but it
results in a dump file much closer in size to the original
repository.</para>
@@ -1988,11 +1988,11 @@
<para>By default, Subversion will not express the first dumped
revision as merely differences to be applied to the previous
revision. For one thing, there is no previous revision in the
- dump file! And secondly, Subversion cannot know the state of
+ dump file! And second, Subversion cannot know the state of
the repository into which the dump data will be loaded (if it
ever is). To ensure that the output of each
execution of <command>svnadmin dump</command> is
- self-sufficient, the first dumped revision is by default a
+ self-sufficient, the first dumped revision is, by default, a
full representation of every directory, file, and property in
that revision of the repository.</para>
@@ -2040,10 +2040,10 @@
using the <option>--parent-dir</option> option of
<command>svnadmin load</command>, you can specify a new
virtual root directory for the load process. That means if
- you have dump files for three repositories, say
+ you have dump files for three repositories—say
<filename>calc-dumpfile</filename>,
<filename>cal-dumpfile</filename>, and
- <filename>ss-dumpfile</filename>, you can first create a new
+ <filename>ss-dumpfile</filename>—you can first create a new
repository to hold them all:</para>
<screen>
@@ -2141,7 +2141,7 @@
to manually inspect and modify it.</para>
<para>That's where <command>svndumpfilter</command> becomes
- useful. This program acts as path-based filter for
+ useful. This program acts as a path-based filter for
repository dump streams. Simply give it either a list of
paths you wish to keep or a list of paths you wish to not
keep, and then pipe your repository dump data through this
@@ -2149,9 +2149,9 @@
that contains only the versioned paths you (explicitly or
implicitly) requested.</para>
- <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
+ <para>Let's look at a realistic example of how you might use this
+ program. Earlier in this chapter (see <xref
+ linkend="svn.reposadmin.projects.chooselayout"/>), we discussed 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
@@ -2220,7 +2220,7 @@
<filename>branches</filename> directories to live in the root
of your repository, you might wish to edit your dump files,
tweaking the <literal>Node-path</literal> and
- <literal>Node-copyfrom-path</literal> headers so they no
+ <literal>Node-copyfrom-path</literal> headers so that they no
longer have that first <filename>calc/</filename> path
component. Also, you'll want to remove the section of dump
data that creates the <filename>calc</filename> directory. It
@@ -2236,9 +2236,9 @@
<warning>
<para>If you do plan on manually editing the dump file to
- remove a top-level directory, make sure that your editor is
+ remove a top-level directory, make sure your editor is
not set to automatically convert end-of-line characters to
- the native format (e.g. <literal>\r\n</literal> to
+ the native format (e.g., <literal>\r\n</literal> to
<literal>\n</literal>), as the content will then not agree
with the metadata. This will render the dump file
useless.</para>
@@ -2246,7 +2246,7 @@
<para>All that remains now is to create your three new
repositories, and load each dump file into the right
- repository, ignoring the UUID found in the dumpstream:</para>
+ repository, ignoring the UUID found in the dump stream:</para>
<screen>
$ svnadmin create calc
@@ -2302,7 +2302,7 @@
<para>If empty revisions are not dropped, preserve the
revision properties (log message, author, date, custom
properties, etc.) for those empty revisions.
- Otherwise, empty revisions will only contain the
+ Otherwise, empty revisions will contain only the
original datestamp, and a generated log message that
indicates that this revision was emptied by
<command>svndumpfilter</command>.</para>
@@ -2336,7 +2336,7 @@
them), other programs that generate dump data might
not be so consistent.</para>
</footnote>
- you should probably normalize those paths so they all
+ you should probably normalize those paths so that they all
have, or all lack, leading slashes.</para>
<para>Also, copied paths can give you some trouble.
@@ -2345,7 +2345,7 @@
It is possible that at some point in the lifetime of your
repository, you might have copied a file or directory from
some location that <command>svndumpfilter</command> is
- excluding, to a location that it is including. In order to
+ excluding, to a location that it is including. To
make the dump data self-sufficient,
<command>svndumpfilter</command> needs to still show the
addition of the new path—including the contents of any
@@ -2367,7 +2367,7 @@
repository of its own, you would, of course, use the
<command>svndumpfilter include</command> command to keep all
the changes in and under
- <filename>trunk/my-project</filename>. But the resulting
+ <filename>trunk/my-project</filename>. But the resultant
dump file makes no assumptions about the repository into
which you plan to load this data. Specifically, the dump
data might begin with the revision that added the
@@ -2397,7 +2397,7 @@
as a soft-upgrade mechanism, and so on.</para>
<para>As of version 1.4, Subversion provides a program for
- managing scenarios like
+ managing scenarios such as
these—<command>svnsync</command>. This works by
essentially asking the Subversion server to
<quote>replay</quote> revisions, one at a time. It then uses
@@ -2405,7 +2405,7 @@
another repository. Neither repository needs to be locally
accessible to the machine on which <command>svnsync</command> is
running—its parameters are repository URLs, and it does
- all its work through Subversion's repository access (RA)
+ all its work through Subversion's Repository Access (RA)
interfaces. All it requires is read access to the source
repository and read/write access to the destination
repository.</para>
@@ -2413,7 +2413,7 @@
<note>
<para>When using <command>svnsync</command> against a remote
source repository, the Subversion server for that repository
- must be running Subversion version 1.4 or better.</para>
+ must be running Subversion version 1.4 or later.</para>
</note>
<para>Assuming you already have a source repository that you'd
@@ -2481,7 +2481,7 @@
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
- in order to modify those repositories. (Please forgive us for
+ 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
@@ -2543,7 +2543,7 @@
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 scripts
- like the one in <xref
+ such as the one in <xref
linkend="svn.reposadmin.maint.replication.start-commit"
/>.</para>
@@ -2642,7 +2642,7 @@
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> get the
- resulting response from the source repository's server, it
+ resultant response from the source repository's server, it
begins forwarding those revisions to the target repository's
server as new commits.</para>
@@ -2699,7 +2699,7 @@
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 to do
- in order to keep your mirror up to date.</para>
+ to keep your mirror up to date.</para>
<sidebar>
<title>svnsync Bookkeeping</title>
@@ -2743,11 +2743,11 @@
<para>That <command>svnsync</command> stores the source
repository URL in a bookkeeping property on the mirror
- repository is the reason why you only have to specify that
- URL once, during <command>svnsync init</command>. Future
+ repository is the reason why you have to specify that
+ URL only once, during <command>svnsync init</command>. Future
synchronization operations against that mirror simply
consult the special <literal>svn:sync-from-url</literal>
- property stored on the mirror itself in order to know where
+ 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
@@ -2785,7 +2785,7 @@
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 simple ignores them.</para>
+ repository, it simply ignores them.</para>
</sidebar>
@@ -2800,7 +2800,7 @@
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 re-replicates all the revision
+ subcommand, which simply rereplicates all the revision
properties for a particular revision or range thereof.</para>
<screen>
@@ -2826,9 +2826,9 @@
<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 only has partial
+ 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
+ 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
@@ -2839,15 +2839,15 @@
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 only copy the bits that changed under that source
+ 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
+ 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. Secondly, the filtering
+ 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 only contain the revisions since the directory appeared
+ 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
@@ -2898,7 +2898,7 @@
<para>Despite numerous advances in technology since the birth of
the modern computer, one thing unfortunately rings true with
- crystalline clarity—sometimes, things go very, very
+ crystalline clarity—sometimes things go very, very
awry. Power outages, network connectivity dropouts, corrupt
RAM, and crashed hard drives are but a taste of the evil that
Fate is poised to unleash on even the most conscientious
@@ -2929,15 +2929,15 @@
the Subversion development team has already done so. The
<command>svnadmin hotcopy</command> command takes care of the
minutia involved in making a hot backup of your repository.
- And its invocation is as trivial as Unix's
- <command>cp</command> or Windows' <command>copy</command>
+ And its invocation is as trivial as the Unix
+ <command>cp</command> or Windows <command>copy</command>
operations:</para>
<screen>
$ svnadmin hotcopy /var/svn/repos /var/svn/repos-backup
</screen>
- <para>The resulting backup is a fully functional Subversion
+ <para>The resultant 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>
@@ -2963,12 +2963,12 @@
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 recent ones remain. Even if you also have an
+ that only the most recent 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 can
- cause it to run nightly (or at whatever granularity of Time
+ cause it to run nightly (or at whatever granularity of time
you deem safe).</para>
<para>Some administrators use a different backup mechanism built
@@ -2976,8 +2976,8 @@
described in <xref linkend="svn.reposadmin.maint.migrate" />
how to use <command>svnadmin dump</command> with the <option>--incremental</option> option to
perform an incremental backup of a given revision or range of
- revisions. And of course, there is a full backup variation of
- this achieved by omitting the <option>--incremental</option>
+ revisions. And of course, you can achieve a full backup variation of
+ this by omitting the <option>--incremental</option>
option to that command. There is some value in these methods,
in that the format of your backed-up information is
flexible—it's not tied to a particular platform,
@@ -3011,7 +3011,7 @@
linkend="svn.reposadmin.maint.replication" />) actually
provides a rather handy middle-ground approach. If you are
regularly synchronizing a read-only mirror with your main
- repository, then in a pinch, your read-only mirror is probably
+ repository, 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
@@ -3019,7 +3019,7 @@
user-specified repository path locks, and other items that
might live in the physical repository directory but not
<emphasis>inside</emphasis> the repository's virtual versioned
- filesystem are not handled by svnsync.</para>
+ filesystem are not handled by <command>svnsync</command>.</para>
<para>In any backup scenario, repository administrators need
to be aware of how modifications to unversioned revision
@@ -3052,7 +3052,7 @@
diversified one that leverages combinations of the methods
described here. The Subversion developers, for example, back
up the Subversion source code repository nightly using
- <command>hot-backup.py</command> and an offsite
+ <command>hot-backup.py</command> and an off-site
<command>rsync</command> of those full backups; keep multiple
archives of all the commit and property change notification
emails; and have repository mirrors maintained by various
@@ -3097,7 +3097,7 @@
loading repository history (as described earlier in <xref
linkend="svn.reposadmin.maint.migrate" />), you get to decide
whether to apply the UUID encapsulated in the data dump
- stream to the repository you are loading the data into. The
+ stream to the repository in which you are loading the data. The
particular circumstance will dictate the correct
behavior.</para>
@@ -3140,7 +3140,7 @@
$
</screen>
- <para>Having older versions of Subversion generate a brand new
+ <para>Having older versions of Subversion generate a brand-new
UUID is not quite as simple to do, though. Your best bet here
is to find some other way to generate a UUID, and then
explicitly set the repository's UUID to that value.</para>
@@ -3162,7 +3162,7 @@
tools provided by your operating system for manipulating
directories—<command>mv</command>, <command>cp
-a</command>, and <command>rm -r</command> on Unix platforms;
- <command>copy</command>, <command>move</command> and
+ <command>copy</command>, <command>move</command>, and
<command>rmdir /s /q</command> on Windows; vast numbers of mouse
and menu gyrations in various graphical file explorer
applications, and so on.</para>
@@ -3183,7 +3183,7 @@
the fact that Subversion uses repository UUIDs to distinguish
repositories. If you copy a Subversion repository using a
typical shell recursive copy command, you'll wind up with two
- repositories identical in every way—including their UUIDs.
+ repositories that are identical in every way—including their UUIDs.
In some circumstances, this might be desirable. But in the
instances where it is not, you'll need to generate a new UUID
for one of these identical repositories. See <xref
@@ -3199,9 +3199,9 @@
<title>Summary</title>
<para>By now you should have a basic understanding of how to
- create, configure, and maintain Subversion repositories. We've
+ create, configure, and maintain Subversion repositories. We
introduced you to the various tools that will assist you with
- this task. Throughout the chapter, we've noted common
+ this task. Throughout the chapter, we noted common
administration pitfalls and offered suggestions for avoiding
them.</para>
More information about the svnbook-dev
mailing list