[svnbook commit] r3032 - trunk/src/de/book
khmarbaise
noreply at red-bean.com
Mon Apr 7 15:06:31 CDT 2008
Author: khmarbaise
Date: Mon Apr 7 15:06:30 2008
New Revision: 3032
Log:
* src/de/book/book.xml
* src/de/book/ch03-advanced-topics.xml
* src/de/book/ch05-repository-admin.xml
* src/de/book/ch07-customizing-svn.xml
* src/de/book/ch08-embedding-svn.xml
* src/de/book/appd-third-party-tools.xml
* src/de/book/styles.css
- merged the changes from the english book into
current translation area.
/trunk/src/en/book (r2996-3028).
Removed:
trunk/src/de/book/appd-third-party-tools.xml
Modified:
trunk/src/de/book/book.xml
trunk/src/de/book/ch03-advanced-topics.xml
trunk/src/de/book/ch05-repository-admin.xml
trunk/src/de/book/ch07-customizing-svn.xml
trunk/src/de/book/ch08-embedding-svn.xml
trunk/src/de/book/styles.css
Modified: trunk/src/de/book/book.xml
==============================================================================
--- trunk/src/de/book/book.xml (original)
+++ trunk/src/de/book/book.xml Mon Apr 7 15:06:30 2008
@@ -17,7 +17,6 @@
<!ENTITY appa SYSTEM "appa-quickstart.xml">
<!ENTITY appb SYSTEM "appb-svn-for-cvs-users.xml">
<!ENTITY appc SYSTEM "appc-webdav.xml">
-<!ENTITY appd SYSTEM "appd-third-party-tools.xml">
<!ENTITY license SYSTEM "copyright.xml">
<!ENTITY index SYSTEM "index.xml">
]>
@@ -99,7 +98,6 @@
&appa;
&appb;
&appc;
- &appd;
&license;
&index;
Modified: trunk/src/de/book/ch03-advanced-topics.xml
==============================================================================
--- trunk/src/de/book/ch03-advanced-topics.xml (original)
+++ trunk/src/de/book/ch03-advanced-topics.xml Mon Apr 7 15:06:30 2008
@@ -1280,23 +1280,22 @@
<screen>
$ ls ### the book sources
-appa-quickstart.xml ch06-server-configuration.xml
-appb-svn-for-cvs-users.xml ch07-customizing-svn.xml
-appc-webdav.xml ch08-embedding-svn.xml
-appd-third-party-tools.xml ch09-reference.xml
-book.xml ch10-world-peace-thru-svn.xml
-ch00-preface.xml copyright.xml
-ch01-fundamental-concepts.xml foreword.xml
-ch02-basic-usage.xml images/
-ch03-advanced-topics.xml index.xml
-ch04-branching-and-merging.xml styles.css
-ch05-repository-admin.xml
+appa-quickstart.xml ch06-server-configuration.xml
+appb-svn-for-cvs-users.xml ch07-customizing-svn.xml
+appc-webdav.xml ch08-embedding-svn.xml
+book.xml ch09-reference.xml
+ch00-preface.xml ch10-world-peace-thru-svn.xml
+ch01-fundamental-concepts.xml copyright.xml
+ch02-basic-usage.xml foreword.xml
+ch03-advanced-topics.xml images/
+ch04-branching-and-merging.xml index.xml
+ch05-repository-admin.xml styles.css
$ ls ch* ### the book chapters
-ch00-preface.xml ch06-server-configuration.xml
-ch01-fundamental-concepts.xml ch07-customizing-svn.xml
-ch02-basic-usage.xml ch08-embedding-svn.xml
-ch03-advanced-topics.xml ch09-reference.xml
-ch04-branching-and-merging.xml ch10-world-peace-thru-svn.xml
+ch00-preface.xml ch06-server-configuration.xml
+ch01-fundamental-concepts.xml ch07-customizing-svn.xml
+ch02-basic-usage.xml ch08-embedding-svn.xml
+ch03-advanced-topics.xml ch09-reference.xml
+ch04-branching-and-merging.xml ch10-world-peace-thru-svn.xml
ch05-repository-admin.xml
$ ls ch?0-* ### the book chapters whose numbers end in zero
ch00-preface.xml ch10-world-peace-thru-svn.xml
Modified: trunk/src/de/book/ch05-repository-admin.xml
==============================================================================
--- trunk/src/de/book/ch05-repository-admin.xml (original)
+++ trunk/src/de/book/ch05-repository-admin.xml Mon Apr 7 15:06:30 2008
@@ -6,7 +6,7 @@
all the love and attention an administrator can offer. While the
repository is generally a low-maintenance item, it is important to
understand how to properly configure and care for it so that
- potential problems are avoided, and actual problems are safely
+ potential problems are avoided, and so actual problems are safely
resolved.</para>
<para>In this chapter, we'll discuss how to create and configure a
@@ -14,7 +14,7 @@
maintenance, providing examples of how and when to use the
<command>svnlook</command> and <command>svnadmin</command> tools
provided with Subversion. We'll address some common questions and
- mistakes, and give some suggestions on how to arrange the data in
+ mistakes and give some suggestions on how to arrange the data in
the repository.</para>
<para>If you plan to access a Subversion repository only in the
@@ -79,7 +79,8 @@
<varlistentry>
<term>dav</term>
<listitem>
- <para>A directory provided to mod_dav_svn for its private
+ <para>A directory provided to
+ <filename>mod_dav_svn</filename> for its private
housekeeping data.</para>
</listitem>
</varlistentry>
@@ -144,7 +145,7 @@
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 straightforward, tending towards
+ Subversion repository is pretty basic, tending towards
mindless repetition if you find yourself setting up multiples of
these things.</para>
@@ -198,10 +199,10 @@
<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
+ of hook programs, one thing to routinely back up, 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
+ easily, without losing any historical versioning
information.</para>
<para>The downside of using a single repository is that
@@ -247,19 +248,19 @@
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
+ that 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 collection of tree
+ and <filename>tags</filename>, which is a collection of tree
snapshots 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>
+ to as <quote>the TTB directories.</quote></para>
</footnote>
</para>
@@ -347,7 +348,7 @@
<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
+ 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
@@ -373,7 +374,7 @@
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 interfaces, e-mail based
+ Subversion (repository browsing interfaces, email-based
commit notification, etc.), your data backup strategy, and so
on.</para>
@@ -385,14 +386,14 @@
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
+ a repository backend data store turns out not to be a choice
+ at all because only one of the available backends will work
in this scenario.</para>
<para>Addressing each possible way to deploy
- Subversion is both impossible, and outside the scope of this
+ Subversion is both impossible 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
+ these pages and other sources as your reference material and to
plan ahead.</para>
</sect2>
@@ -403,20 +404,20 @@
<para>As of version 1.1, Subversion provides two options for the
type of underlying data store—often referred to as
- <quote>the back-end</quote> or, somewhat confusingly,
+ <quote>the backend</quote> or, somewhat confusingly,
<quote>the (versioned) filesystem</quote>—that each
repository uses. One type of data store keeps everything in a
Berkeley DB (or BDB) database environment; repositories that
use this type are often referred to as being
- <quote>BDB-backed</quote>. The other type stores data in
+ <quote>BDB-backed.</quote> The other type stores data in
ordinary flat files, using a custom format. Subversion
developers have adopted the habit of referring to this latter
data storage mechanism as <firstterm>FSFS</firstterm>
<footnote>
- <para>Often pronounced <quote>fuzz-fuzz</quote>, if Jack
+ <para>Often pronounced <quote>fuzz-fuzz,</quote> if Jack
Repenning has anything to say about it. (This book,
however, assumes that the reader is thinking
- <quote>eff-ess-eff-ess</quote>.)</para>
+ <quote>eff-ess-eff-ess.</quote>)</para>
</footnote>
—a versioned filesystem implementation that uses the
native OS filesystem directly—rather than via a database
@@ -427,7 +428,7 @@
repositories.</para>
<table id="svn.reposadmin.basics.backends.tbl-1">
- <title>Repository Data Store Comparison</title>
+ <title>Repository data store comparison</title>
<tgroup cols="4">
<thead>
<row>
@@ -441,76 +442,76 @@
<row>
<entry morerows="1">Reliability</entry>
<entry>Data integrity</entry>
- <entry>when properly deployed, extremely reliable;
- Berkeley DB 4.4 brings auto-recovery</entry>
- <entry>older versions had some rarely demonstrated, but
- data-destroying bugs</entry>
+ <entry>When properly deployed, extremely reliable;
+ Berkeley DB 4.4 brings auto-recovery.</entry>
+ <entry>Older versions had some rarely demonstrated, but
+ 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>
+ <entry>Very; crashes and permission problems can leave the
+ database <quote>wedged,</quote> requiring journaled
+ 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>
+ <entry>Sensitive to user umask problems; best if accessed
+ 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>some older native filesystems don't scale well with
- thousands of entries in a single directory</entry>
+ <entry>Database; no problems.</entry>
+ <entry>Some older native filesystems don't scale well with
+ 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>
- <entry>faster overall, but finalization delay may cause
- client timeouts</entry>
+ <entry>Slower overall, but cost is amortized across the
+ lifetime of the commit.</entry>
+ <entry>Faster overall, but finalization delay may cause
+ client timeouts.</entry>
</row>
</tbody>
</tgroup>
</table>
<para>There are advantages and disadvantages to each of these
- two back-end types. Neither of them is more
+ two backend types. Neither of them is more
<quote>official</quote> than the other, though the newer FSFS
is the default data store as of Subversion 1.2. Both are
reliable enough to trust with your versioned data. But as you
@@ -524,17 +525,17 @@
system—largely explain why today almost everyone uses
the FSFS backend when creating new repositories.</para>
- <para>Fortunately, most programs which access Subversion
- repositories are blissfully ignorant of which back-end data
+ <para>Fortunately, most programs that access Subversion
+ repositories are blissfully ignorant of which backend data
store is in use. And you aren't even necessarily stuck with
your first choice of a data store—in the event that you
change your mind later, Subversion provides ways of migrating
your repository's data into another repository that uses a
- different back-end data store. We talk more about that later
+ different backend data store. We talk more about that later
in this chapter.</para>
<para>The following subsections provide a more detailed look at
- the available back-end data store types.</para>
+ the available backend data store types.</para>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.reposadmin.basics.backends.bdb">
@@ -542,7 +543,7 @@
<para>When the initial design phase of Subversion was in
progress, the developers decided to use Berkeley DB for a
- variety of reasons, including its open-source license,
+ variety of reasons, including its open source license,
transaction support, reliability, performance, API
simplicity, thread-safety, support for cursors, and so
on.</para>
@@ -563,32 +564,33 @@
of the database.</para>
<para>Another great feature of Berkeley DB is <firstterm>hot
- backups</firstterm>—the ability to backup the database
- environment without taking it <quote>offline</quote>. We'll
- discuss how to backup your repository in <xref
- linkend="svn.reposadmin.maint.backup"/>, but the benefits of being
- able to make fully functional copies of your repositories
- without any downtime should be obvious.</para>
+ backups</firstterm>—the ability to back up the
+ database environment without taking it
+ <quote>offline.</quote> We'll discuss how to back up your
+ repository later in this chapter (in <xref
+ linkend="svn.reposadmin.maint.backup"/>), but the benefits
+ of being able to make fully functional copies of your
+ repositories without any downtime should be obvious.</para>
<para>Berkeley DB is also a very reliable database system when
properly used. Subversion uses Berkeley DB's logging
facilities, which means that the database first writes to
- on-disk log files a description of any modifications it is
+ on-disk logfiles a description of any modifications it is
about to make, and then makes the modification itself. This
is to ensure that if anything goes wrong, the database
system can back up to a previous
<firstterm>checkpoint</firstterm>—a location in the
- log files known not to be corrupt—and replay
+ logfiles known not to be corrupt—and replay
transactions until the data is restored to a usable state.
- See <xref linkend="svn.reposadmin.maint.diskspace"/> for
- more about Berkeley DB log files.</para>
+ See <xref linkend="svn.reposadmin.maint.diskspace"/> later
+ in this chapter for more about Berkeley DB logfiles.</para>
<para>But every rose has its thorn, and so we must note some
known limitations of Berkeley DB. First, Berkeley DB
environments are not portable. You cannot simply copy a
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,
+ 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
operate on Windows 95/98 systems—if you need to house
@@ -612,7 +614,7 @@
in the first place).</para>
<warning>
- <para>If you attempt to use Berkeley DB on a non-compliant
+ <para>If you attempt to use Berkeley DB on a noncompliant
remote filesystem, the results are unpredictable—you
may see mysterious errors right away, or it may be months
before you discover that your repository database is
@@ -661,9 +663,10 @@
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 DB
- repository directly as multiple users, be sure to read <xref
- linkend="svn.serverconfig.multimethod"/>.</para>
+ <literal>svn+ssh://</literal> URLs. If accessing a Berkeley
+ DB repository directly as multiple users, be sure to read
+ <xref linkend="svn.serverconfig.multimethod"/> later in this
+ chapter.</para>
</sect3>
@@ -672,7 +675,7 @@
<title>FSFS</title>
<para>In mid-2004, a second type of repository storage
- system—one which doesn't use a database at
+ system—one that doesn't use a database at
all—came into being. An FSFS repository stores the
changes associated with a revision in a single file, and so
all of a repository's revisions can be found in a single
@@ -682,7 +685,7 @@
into the revisions directory, thus guaranteeing that commits
are atomic. And because a revision file is permanent and
unchanging, the repository also can be backed up while
- <quote>hot</quote>, just like a BDB-backed
+ <quote>hot,</quote> just like a BDB-backed
repository.</para>
<para>The FSFS revision files describe a revision's
@@ -708,28 +711,28 @@
waiting for a response.</para>
<para>The most important distinction, however, is FSFS's
- imperviousness to <quote>wedging</quote> when something goes
- wrong. If a process using a Berkeley DB database runs into
- 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>
+ imperviousness to wedging when something goes wrong. If a
+ process using a Berkeley DB database runs into 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. Unlike Berkeley DB,
which has years of history, its own dedicated development
- team and, now, Oracle's mighty name attached to it,
+ 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. Prior to
- Subversion 1.4, it was still shaking out some pretty serious
- data integrity bugs which, while only triggered in very rare
+ 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
cases, nonetheless did occur. 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
+ become the backend of choice for some of the largest public
+ and private Subversion repositories, and it promises a lower
barrier to entry for Subversion across the board.</para>
</sect3>
@@ -743,13 +746,13 @@
<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! In this section, we'll see
- how to actually create a Subversion repository and configure it
- to perform custom actions when special repository events
- occur.</para>
+ <para>Earlier, 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,
+ we'll see how to actually create a Subversion repository and
+ configure it to perform custom actions when special repository
+ events occur.</para>
<!-- =============================================================== -->
<sect2 id="svn.reposadmin.basics.creating">
@@ -757,11 +760,13 @@
<para>Subversion repository creation is an incredibly simple
task. The <command>svnadmin</command> utility that comes with
- Subversion provides a subcommand (<literal>create</literal>)
- for doing just that.</para>
+ Subversion provides a subcommand (<command>svnadmin
+ create</command>) for doing just that.</para>
<screen>
+$ # Create a repository
$ svnadmin create /var/svn/repos
+$
</screen>
<para>This creates a new repository in the directory
@@ -819,7 +824,7 @@
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 other parts of the
- repository <quote>by hand</quote>. 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
@@ -842,7 +847,7 @@
repository operation and provide a means by which to both
report what is about to happen and to prevent it from
happening at all. Other hooks (the <quote>post hooks</quote>)
- run after the completion of a repository event, and are useful
+ run after the completion of a repository event and are useful
for performing tasks that examine—but don't
modify—the repository. Each hook is handed enough
information to tell what that event is (or was), the specific
@@ -851,25 +856,26 @@
<para>The <filename>hooks</filename> subdirectory is, by
default, filled with templates for various repository
- hooks.</para>
+ hooks:</para>
<screen>
$ ls repos/hooks/
-post-commit.tmpl post-unlock.tmpl pre-revprop-change.tmpl
-post-lock.tmpl pre-commit.tmpl pre-unlock.tmpl
+post-commit.tmpl post-unlock.tmpl pre-revprop-change.tmpl
+post-lock.tmpl pre-commit.tmpl pre-unlock.tmpl
post-revprop-change.tmpl pre-lock.tmpl start-commit.tmpl
+$
</screen>
<para>There is one template for each hook that the Subversion
- repository supports, and by examining the contents of those
+ repository supports; by examining the contents of those
template scripts, you can see what triggers each script
to run and what data is passed to that script. Also present
in many of these templates are examples of how one might use
that script, in conjunction with other Subversion-supplied
programs, to perform common useful tasks. To actually install
a working hook, you need only place some executable program or
- script into the <filename>repos/hooks</filename> directory
- which can be executed as the name (like
+ script into the <filename>repos/hooks</filename> directory,
+ which can be executed as the name (such as
<command>start-commit</command> or
<command>post-commit</command>) of the hook.</para>
@@ -880,14 +886,14 @@
files are present for more than just informational
purposes—the easiest way to install a hook on Unix
platforms is to simply copy the appropriate template file to a
- new file that lacks the <literal>.tmpl</literal> extension,
+ new file that lacks the <filename>.tmpl</filename> extension,
customize the hook's contents, and ensure that the script is
executable. Windows, however, uses file extensions to
- determine whether or not a program is executable, so you would
+ determine whether a program is executable, so you would
need to supply a program whose basename is the name of the
- hook, and whose extension is one of the special extensions
+ hook and whose extension is one of the special extensions
recognized by Windows for executable programs, such as
- <filename>.exe</filename> for programs, and
+ <filename>.exe</filename> for programs and
<filename>.bat</filename> for batch files.</para>
<tip>
@@ -903,13 +909,13 @@
</tip>
<para>Subversion executes hooks as the same user who owns the
- process which is accessing the Subversion repository. In most
+ process that is accessing the Subversion repository. In most
cases, the repository is being accessed via a Subversion
- server, so this user is the same user as which that server
+ server, so this user is the same user as whom the server
runs on the system. The hooks themselves will need to be
configured with OS-level permissions that allow that user to
- execute them. Also, this means that any file or programs
- (including the Subversion repository itself) accessed directly
+ execute them. Also, this means that any programs or files
+ (including the Subversion repository) accessed directly
or indirectly by the hook will be accessed as the same user.
In other words, be alert to potential permission-related
problems that could prevent the hook from performing the tasks
@@ -918,7 +924,7 @@
<para>There are nine hooks implemented by the Subversion
repository, and you can get details about each of them in
<xref linkend="svn.ref.reposhooks" />. As a repository
- administrator, you'll need to decide which of hooks you wish
+ administrator, you'll need to decide which hooks you wish
to implement (by way of providing an appropriately named and
permissioned hook program), and how. When you make this
decision, keep in mind
@@ -933,10 +939,8 @@
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
- notification, and beyond. See <xref linkend="svn.3rdparty" />
- for discussion of some of the most commonly used hook
- programs. Or, if you wish to write your own, see <xref
- linkend="svn.developer" />.</para>
+ notification, and beyond. Or, if you wish to write your own,
+ see <xref linkend="svn.developer" />.</para>
<warning>
<para>While hook scripts can do almost
@@ -944,7 +948,7 @@
authors should show restraint: do <emphasis>not</emphasis>
modify a commit transaction using hook scripts. While it
might be tempting to use hook scripts to automatically
- correct errors or shortcomings or policy violations present
+ correct errors, shortcomings, or policy violations present
in the files being committed, doing so can cause problems.
Subversion keeps client-side caches of certain bits of
repository data, and if you change a commit transaction in
@@ -965,39 +969,39 @@
<title>Berkeley DB Configuration</title>
<para>A Berkeley DB environment is an encapsulation of one or
- more databases, log files, 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 like the number of database locks
- allowed to be taken out at any given time, or the maximum size
- of the journaling log files, etc. 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 and
- access patterns, might require a different set of
+ 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
+ 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
+ and access patterns, might require a different set of
configuration option values.</para>
<para>The producers of Berkeley DB understand that different
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: BDB checks for the presence of
- a file named <filename>DB_CONFIG</filename> in the environment
- directory (namely, the repository's
- <filename>db</filename> subdirectory), and parses the options found in that file . 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 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 at odds with
- what Subversion might expect. Also, changes made to
- <filename>DB_CONFIG</filename> won't take effect until you
- recover the database environment (using <command>svnadmin
- recover</command>).</para>
+ requirements, so they have provided a mechanism for overriding
+ at runtime many of the configuration values for the Berkeley
+ DB environment. BDB checks for the presence of a file named
+ <filename>DB_CONFIG</filename> in the environment directory
+ (namely, the repository's <filename>db</filename>
+ subdirectory), and parses the options found in that file.
+ 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 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 at odds with what Subversion might expect.
+ Also, changes made to <filename>DB_CONFIG</filename> won't
+ take effect until you recover the database environment (using
+ <command>svnadmin recover</command>).</para>
</sect2>
</sect1>
@@ -1009,21 +1013,21 @@
<sect1 id="svn.reposadmin.maint">
<title>Repository Maintenance</title>
- <para>Maintaining a Subversion repository can be daunting,
- mostly due to the complexities inherent in systems which have a
- database backend. Doing the task well is all about knowing the
- 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 data migration,
- upgrades, backups and cleanups.</para>
+ <para>Maintaining a Subversion repository can be daunting, mostly
+ due to the complexities inherent in systems that have a database
+ backend. Doing the task well is all about knowing the
+ tools—what they are, when to use them, and how. This
+ 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>
<!-- =============================================================== -->
<sect2 id="svn.reposadmin.maint.tk">
<title>An Administrator's Toolkit</title>
<para>Subversion provides a handful of utilities useful for
- creating, inspecting, modifying and repairing your repository.
+ creating, inspecting, modifying, and repairing your repository.
Let's look more closely at each of those tools. Afterward,
we'll briefly examine some of the utilities included in the
Berkeley DB distribution that provide functionality specific
@@ -1055,13 +1059,13 @@
…
</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 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>
+ <para>Previously in this chapter (in <xref
+ linkend="svn.reposadmin.basics.creating"/>), we were
+ introduced to the <command>svnadmin create</command>
+ subcommand. Most of the other <command>svnadmin</command>
+ subcommands we will cover 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>
@@ -1072,7 +1076,7 @@
<para><command>svnlook</command> is a tool provided by
Subversion for examining the various revisions and
<firstterm>transactions</firstterm> (which are revisions
- in-the-making) in a repository. No part of this program
+ in the making) in a repository. No part of this program
attempts to change the repository. <command>svnlook</command>
is typically used by the repository hooks for reporting the
changes that are about to be committed (in the case of the
@@ -1095,7 +1099,7 @@
…
</screen>
- <para>Nearly every one of <command>svnlook</command>'s
+ <para>Most of <command>svnlook</command>'s
subcommands can operate on either a revision or a
transaction tree, printing information about the tree
itself, or how it differs from the previous revision of the
@@ -1106,7 +1110,7 @@
both the <option>--revision</option> (<option>-r</option>)
and <option>--transaction</option> (<option>-t</option>)
options, <command>svnlook</command> will examine the
- youngest (or <quote>HEAD</quote>) revision in the
+ youngest (or <literal>HEAD</literal>) revision in the
repository. So the following two commands do exactly the
same thing when 19 is the youngest revision in the
repository located at
@@ -1117,20 +1121,21 @@
$ svnlook info /var/svn/repos -r 19
</screen>
- <para>The only exception to these rules about subcommands is
+ <para>One exception to these rules about subcommands is
the <command>svnlook youngest</command> subcommand, which
- takes no options, and simply prints out the repository's
- youngest revision number.</para>
+ takes no options and simply prints out the repository's
+ youngest revision number:</para>
<screen>
$ svnlook youngest /var/svn/repos
19
+$
</screen>
<note>
<para>Keep in mind that the only transactions you can browse
are uncommitted ones. Most repositories will have no such
- transactions, because transactions are usually either
+ transactions because transactions are usually either
committed (in which case, you should access them as
revision with the <option>--revision</option>
(<option>-r</option>) option) or aborted and
@@ -1138,8 +1143,8 @@
</note>
<para>Output from <command>svnlook</command> is designed to be
- both human- and machine-parsable. Take as an example the output
- of the <literal>info</literal> subcommand:</para>
+ both human- and machine-parsable. Take, as an example, the
+ output of the <command>svnlook info</command> subcommand:</para>
<screen>
$ svnlook info /var/svn/repos
@@ -1148,10 +1153,11 @@
27
Added the usual
Greek tree.
+$
</screen>
- <para>The output of the <literal>info</literal> subcommand is
- defined as:</para>
+ <para>The output of <command>svnlook info</command> consists
+ of the following, in the order given:</para>
<orderedlist>
<listitem>
@@ -1169,7 +1175,7 @@
</listitem>
</orderedlist>
- <para>This output is human-readable, meaning items like the
+ <para>This output is human-readable, meaning items such as the
datestamp are displayed using a textual representation
instead of something more obscure (such as the number of
nanoseconds since the Tasty Freeze guy drove by). But the
@@ -1221,11 +1227,12 @@
</screen>
<para>There are only two interesting subcommands:
- <literal>exclude</literal> and <literal>include</literal>.
- They allow you to make the choice between implicit or
- explicit inclusion of paths in the stream. You can learn
- more about these subcommands and
- <command>svndumpfilter</command>'s unique purpose in <xref
+ <command>svndumpfilter exclude</command> and
+ <command>svndumpfilter include</command>. They allow you to
+ make the choice between implicit or explicit inclusion of
+ paths in the stream. You can learn more about these
+ subcommands and <command>svndumpfilter</command>'s unique
+ purpose later in this chapter, in <xref
linkend="svn.reposadmin.maint.filtering" />.</para>
</sect3>
@@ -1267,9 +1274,9 @@
$
</screen>
- <para>We talk more about replication repositories with
- <command>svnsync</command> in <xref
- linkend="svn.reposadmin.maint.replication" />.</para>
+ <para>We talk more about replicating repositories with
+ <command>svnsync</command> later in this chapter (see <xref
+ linkend="svn.reposadmin.maint.replication" />).</para>
</sect3>
@@ -1283,13 +1290,13 @@
directory of the Subversion source distribution) is a useful
performance tuning tool for administrators of FSFS-backed
Subversion repositories. FSFS repositories contain files
- which describe the changes made in a single revision, and
- files which contain the revision properties associated with
+ that describe the changes made in a single revision, and
+ files that contain the revision properties associated with
a single revision. Repositories created in versions of
Subversion prior to 1.5 keep these files in two
directories—one for each type of file. As new
revisions are committed to the repository, Subversion drops
- more files into these two directories, and over time, the
+ more files into these two directories—over time, the
number of these files in each directory can grow to be quite
large. This has been observed to cause perfomance problems
on certain network-based filesystems.</para>
@@ -1303,26 +1310,26 @@
Subversion when reading from the repository. The number of
subdirectories used to house these files is configurable,
though, and that's where
- <filename>fsfs-reshard.py</filename> comes in. This script
+ <command>fsfs-reshard.py</command> comes in. This script
reshuffles the repository's file structure into a new
- arrangement which reflects the requested number of sharding
+ arrangement that reflects the requested number of sharding
subdirecties. 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
+ for you) or for fine-tuning an already sharded
repository.</para>
</sect3>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.reposadmin.maint.tk.bdbutil">
- <title>Berkeley DB Utilities</title>
+ <title>Berkeley DB utilities</title>
<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>
subdirectory of your repository. This subdirectory is a
- regular Berkeley DB environment directory, and can therefore
+ regular Berkeley DB environment directory and can therefore
be used in conjunction with any of the Berkeley database
tools, typically provided as part of the Berkeley DB
distribution.</para>
@@ -1341,7 +1348,7 @@
<para>However, there are still a few Berkeley DB utilities
that you might find useful. The <command>db_dump</command>
and <command>db_load</command> programs write and read,
- respectively, a custom file format which describes the keys
+ respectively, a custom file format that describes the keys
and values in a Berkeley DB database. Since Berkeley
databases are not portable across machine architectures,
this format is a useful way to transfer those databases from
@@ -1361,7 +1368,7 @@
<para>For more information on the Berkeley DB tool chain,
visit the documentation section of the Berkeley DB section
- of Oracle's website, located at <ulink
+ of Oracle's web site, located at <ulink
url="http://www.oracle.com/technology/documentation/berkeley-db/db/"
/>.</para>
@@ -1378,12 +1385,12 @@
<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
- can <quote>fix</quote> her log message remotely using the
- <command>svn</command> program's <literal>propset</literal>
- command (see <xref linkend="svn.ref.svn.c.propset"/>).
- However, because of the potential to lose information forever,
- Subversion repositories are not, by default, configured to
- allow changes to unversioned properties—except by an
+ 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
+ potential to lose information forever, Subversion repositories
+ are not, by default, configured to allow changes to
+ unversioned properties—except by an
administrator.</para>
<para>If a log message needs to be changed by an administrator,
@@ -1411,7 +1418,7 @@
<warning>
<para>Remember, though, that by bypassing the hooks, you are
likely avoiding such things as email notifications of
- property changes, backup systems which track unversioned
+ property changes, backup systems that track unversioned
property changes, and so on. In other words, be very
careful about what you are changing, and how you change
it.</para>
@@ -1449,7 +1456,7 @@
equal to the size of the original data, it takes up only
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
+ 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
@@ -1464,7 +1471,7 @@
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
+ 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
@@ -1490,9 +1497,9 @@
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>
+ <para>You can use the <command>svnadmin lstxns</command>
+ command to list the names of the currently outstanding
+ transactions:</para>
<screen>
$ svnadmin lstxns myrepos
@@ -1512,9 +1519,9 @@
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,
- the <literal>rmtxns</literal> subcommand can take its input
+ <command>svnadmin rmtxns</command> can take its input
directly from the output of
- <literal>lstxns</literal>!</para>
+ <command>svnadmin lstxns</command>!</para>
<screen>
$ svnadmin rmtxns myrepos `svnadmin lstxns myrepos`
@@ -1531,7 +1538,7 @@
repository.</para>
<example id="svn.reposadmin.maint.diskspace.deadtxns.ex-1">
- <title>txn-info.sh (Reporting Outstanding Transactions)</title>
+ <title>txn-info.sh (reporting outstanding transactions)</title>
<programlisting>
#!/bin/sh
@@ -1554,7 +1561,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
+ (see <xref linkend="svn.reposadmin.maint.tk.svnlook"/>) and
will look something like:</para>
<screen>
@@ -1597,29 +1604,29 @@
<title>Purging unused Berkeley DB logfiles</title>
<para>Until recently, the largest offender of disk space usage
- with respect to BDB-backed Subversion repositories was the
- log files in 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, at any given time, reflect a particular state, the log
- files contain all the many changes along the way <emphasis>between</emphasis>
- states. Thus, they can grow and accumulate quite
- rapidly.</para>
+ with respect to BDB-backed Subversion repositories were the
+ logfiles in which Berkeley DB performs its prewrites 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, at any given time, reflect a particular state, the
+ logfiles contain all the many changes along the way
+ <emphasis>between</emphasis> states. Thus, they can grow
+ and accumulate quite rapidly.</para>
<para>Fortunately, beginning with the 4.2 release of Berkeley
DB, the database environment has the ability to remove its
- own unused log files automatically. Any
- repositories created using an <command>svnadmin</command>
- which is compiled against Berkeley DB version 4.2 or greater
+ 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
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
- to do this, or change your mind at a later time, simply edit
+ to do this or change your mind at a later time, simply edit
the <filename>DB_CONFIG</filename> file found in your
repository's <filename>db</filename> directory, comment out
- the line which contains the <literal>set_flags
+ the line that contains the <literal>set_flags
DB_LOG_AUTOREMOVE</literal> directive, and then run
<command>svnadmin recover</command> on your repository to
force the configuration changes to take effect. See <xref
@@ -1627,16 +1634,16 @@
database configuration.</para>
<para>Without some sort of automatic log file removal in
- place, log files will accumulate as you use your repository.
+ 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
- database using nothing but the log files, so these files can
+ database using nothing but the logfiles, so these files can
be useful for catastrophic database recovery. But
- typically, you'll want to archive the log files that are no
+ typically, you'll want to archive the logfiles that are no
longer in use by Berkeley DB, and then remove them from disk
to conserve space. Use the <command>svnadmin
list-unused-dblogs</command> command to list the unused
- log files:</para>
+ logfiles:</para>
<screen>
$ svnadmin list-unused-dblogs /var/svn/repos
@@ -1649,16 +1656,16 @@
</screen>
<warning>
- <para>BDB-backed repositories whose log files are used
- as part of a backup or disaster recovery plan should
+ <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
autoremoval feature. Reconstruction of a repository's
- data from log files can only be accomplished when <emphasis>all</emphasis> the log
- files are available. If some of the log files 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 useless.</para>
- </warning>
+ data from logfiles can only be accomplished 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
+ useless.</para> </warning>
</sect3>
@@ -1670,7 +1677,7 @@
<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
+ repository can sometimes be left in a 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
@@ -1701,18 +1708,18 @@
<para>In the course of using your Subversion repository, fatal
errors or interruptions can prevent a process from having the
chance to remove the locks it has placed in the database. The
- result is that the back-end database system gets
- <quote>wedged</quote>. When this happens, any attempts to
+ result is that the backend database system gets
+ <quote>wedged.</quote> When this happens, any attempts to
access the repository hang indefinitely (since each new
accessor is waiting for a lock to go away—which isn't
going to happen).</para>
<para>If this happens to your repository, don't panic. The
Berkeley DB filesystem takes advantage of database
- transactions and checkpoints and pre-write journaling to
+ 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>e.g., hard drive + huge electromagnet = disaster</para>
</footnote>
can permanently destroy a database environment. A
sufficiently paranoid repository administrator will have made
@@ -1726,8 +1733,8 @@
<listitem>
<para>Make sure that there are no processes accessing (or
attempting to access) the repository. For networked
- repositories, this means shutting down the Apache HTTP
- Server or svnserve daemon, too.</para>
+ repositories, this also means shutting down the Apache HTTP
+ Server or svnserve daemon.</para>
</listitem>
<listitem>
<para>Become the user who owns and manages the repository.
@@ -1735,7 +1742,7 @@
running as the wrong user can tweak the permissions of the
repository's files in such a way that your repository will
still be inaccessible even after it is
- <quote>unwedged</quote>.</para>
+ <quote>unwedged.</quote></para>
</listitem>
<listitem>
<para>Run the command <command>svnadmin recover
@@ -1757,7 +1764,7 @@
</orderedlist>
<para>This procedure fixes almost every case of repository
- lock-up. Make sure that you run this command as the user that
+ 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
@@ -1773,7 +1780,7 @@
(perhaps by renaming it to something like
<filename>repos.BROKEN</filename>) and then restore your
latest backup of it. Then, send an email to the Subversion
- user list (at <email>users at subversion.tigris.org</email>)
+ users mailing list (at <email>users at subversion.tigris.org</email>)
describing your problem in detail. Data integrity is an
extremely high priority to the Subversion developers.</para>
@@ -1791,17 +1798,18 @@
moved into another repository.</para>
<para>Subversion provides such functionality by way of
- repository dump streams. A repository dump stream (often
- referred to as a <quote>dumpfile</quote> when stored as a file
- on disk) is a portable, flat file format that describes the
- various revisions in your repository—what was changed,
- by whom, when, and so on. This dump stream is the primary
- mechanism used to marshal versioned history—in whole or
- in part, with or without modification—between
- repositories. And Subversion provides the tools necessary for
- creating and loading these dump streams—the
- <command>svnadmin dump</command> and <command>svnadmin
- load</command> subcommands, respectively.</para>
+ <firstterm>repository dump streams</firstterm>. A repository
+ dump stream (often referred to as a <quote>dumpfile</quote>
+ when stored as a file on disk) is a portable, flat file format
+ that describes the various revisions in your
+ repository—what was changed, by whom, when, and so on.
+ This dump stream is the primary mechanism used to marshal
+ versioned history—in whole or in part, with or without
+ modification—between repositories. And Subversion
+ provides the tools necessary for creating and loading these
+ dump streams: the <command>svnadmin dump</command> and
+ <command>svnadmin load</command> subcommands,
+ respectively.</para>
<warning>
<para>While the Subversion repository dump format contains
@@ -1813,22 +1821,14 @@
the file by automatically converting line endings.</para>
</warning>
- <note>
- <para>The Subversion repository dump format describes
- versioned repository changes only. It will not carry any
- information about uncommitted transactions, user locks on
- filesystem paths, repository or server configuration
- customizations (including hook scripts), and so on.</para>
- </note>
-
<para>There are many reasons for dumping and loading Subversion
repository data. Early in Subversion's life, the most common
reason was due to the evolution of Subversion itself. As
Subversion matured, there were times when changes made to the
- back-end database schema caused compatibility issues with
+ backend database schema caused compatibility issues 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
+ Subversion and load it into a freshly created repository with
the new version of Subversion. Now, these types of schema
changes haven't occurred since Subversion's 1.0 release, and
the Subversion developers promise not to force users to dump
@@ -1837,10 +1837,18 @@
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
- back-ends, or (as we'll cover in <xref
+ backends, or (as we'll cover later in <xref
linkend="svn.reposadmin.maint.filtering" />) purging versioned
data from repository history.</para>
+ <note>
+ <para>The Subversion repository dump format describes
+ versioned repository changes only. It will not carry any
+ information about uncommitted transactions, user locks on
+ filesystem paths, repository or server configuration
+ customizations (including hook scripts), and so on.</para>
+ </note>
+
<para>Whatever your reason for migrating repository history,
using the <command>svnadmin dump</command> and
<command>svnadmin load</command> subcommands is
@@ -1876,7 +1884,7 @@
<para>The other subcommand in the pair, <command>svnadmin
load</command>, parses the standard input stream as a
- Subversion repository dump file, and effectively replays those
+ Subversion repository dump file and effectively replays those
dumped revisions into the target repository for that
operation. It also gives informative feedback, this time
using the standard output stream:</para>
@@ -1912,8 +1920,8 @@
<para>The result of a load is new revisions added to a
repository—the same thing you get by making commits
- against that repository from a regular Subversion client. And
- just as in a commit, you can use hook programs to perform
+ against that repository from a regular Subversion client.
+ Just as in a commit, you can use hook programs to perform
actions before and after each of the commits made during a
load process. By passing the
<option>--use-pre-commit-hook</option> and
@@ -1945,9 +1953,9 @@
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
+ it's 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
+ 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> option. With this
option, successive revisions of files will be output as
@@ -1959,7 +1967,7 @@
<para>We mentioned previously that <command>svnadmin
dump</command> outputs a range of revisions. Use the
<option>--revision</option> (<option>-r</option>) option to
- specify a single revision to dump, or a range of revisions.
+ specify a single revision, or a range of revisions, to dump.
If you omit this option, all the existing repository revisions
will be dumped.</para>
@@ -1992,7 +2000,7 @@
the <option>--incremental</option> option when you dump your
repository, <command>svnadmin</command> will compare the first
dumped revision against the previous revision in the
- repository, the same way it treats every other revision that
+ repository—the same way it treats every other revision that
gets dumped. It will then output the first revision exactly
as it does the rest of the revisions in the dump
range—mentioning only the changes that occurred in that
@@ -2043,7 +2051,7 @@
$
</screen>
- <para>Then, make new directories in the repository which will
+ <para>Then, make new directories in the repository that will
encapsulate the contents of each of the three previous
repositories:</para>
@@ -2090,7 +2098,7 @@
<para>Since Subversion stores your versioned history using, at
the very least, binary differencing algorithms and data
compression (optionally in a completely opaque database
- system), attempting manual tweaks is unwise, if not quite
+ system), attempting manual tweaks is unwise if not quite
difficult, and at any rate strongly discouraged. And once
data has been stored in your repository, Subversion
generally doesn't provide an easy way to remove that data.
@@ -2105,7 +2113,7 @@
reason).
<footnote>
<para>Conscious, cautious removal of certain bits of
- versioned data is actually supported by real use-cases.
+ versioned data is actually supported by real use cases.
That's why an <quote>obliterate</quote> feature has been
one of the most highly requested Subversion features,
and one which the Subversion developers hope to soon
@@ -2113,33 +2121,30 @@
</footnote>
Or, perhaps you have multiple projects sharing a
single repository, and you decide to split them up into
- their own repositories. To accomplish tasks like this,
+ their own repositories. To accomplish tasks such as these,
administrators need a more manageable and malleable
representation of the data in their repositories—the
Subversion repository dump format.</para>
- <para>As we described in <xref
- linkend="svn.reposadmin.maint.migrate" />, the
- Subversion repository dump format is a human-readable
- representation of the changes that you've made to your
- versioned data over time. You use the <command>svnadmin
- dump</command> command to generate the dump data, and
- <command>svnadmin load</command> to populate a new
- repository with it (see <xref
- 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 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>
+ <para>As we described earlier in <xref
+ linkend="svn.reposadmin.maint.migrate" />, the Subversion
+ repository dump format is a human-readable representation of
+ the changes that you've made to your versioned data over time.
+ Use the <command>svnadmin dump</command> command to generate
+ the dump data, and <command>svnadmin load</command> to
+ populate a new repository with it. 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 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>
<para>That's where <command>svndumpfilter</command> becomes
useful. This program acts as 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, then pipe your repository dump data through this
+ paths you wish to keep or a list of paths you wish to not
+ keep, and then pipe your repository dump data through this
filter. The result will be a modified stream of dump data
that contains only the versioned paths you (explicitly or
implicitly) requested.</para>
@@ -2153,7 +2158,7 @@
so on. But sometimes after new revisions start flying in,
you rethink your layout and would like to make some changes.
A common change is the decision to move multiple projects
- which are sharing a single repository into separate
+ that are sharing a single repository into separate
repositories for each project.</para>
<para>Our imaginary repository contains three projects:
@@ -2191,8 +2196,8 @@
</screen>
<para>Next, run that dump file through the filter, each time
- including only one of our top-level directories, and
- resulting in three new dump files:</para>
+ including only one of our top-level directories. This results
+ in three new dump files:</para>
<screen>
$ svndumpfilter include calc < repos-dumpfile > calc-dumpfile
@@ -2204,22 +2209,22 @@
$
</screen>
- <para>At this point, you have to make a decision. Each of
- your dump files will create a valid repository,
- but will preserve the paths exactly as they were in the
- original repository. This means that even though you would
- have a repository solely for your <literal>calc</literal>
- project, that repository would still have a top-level
- directory named <filename>calc</filename>. If you want
- your <filename>trunk</filename>, <filename>tags</filename>,
- and <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 to 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 will look
- something like:</para>
+ <para>At this point, you have to make a decision. Each of your
+ dump files will create a valid repository, but will preserve
+ the paths exactly as they were in the original repository.
+ This means that even though you would have a repository solely
+ for your <literal>calc</literal> project, that repository
+ would still have a top-level directory named
+ <filename>calc</filename>. If you want your
+ <filename>trunk</filename>, <filename>tags</filename>, and
+ <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
+ 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
+ will look something like the following:</para>
<screen>
Node-path: calc
@@ -2232,8 +2237,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
- not set to automatically convert end-of-line characters to the native
- format (e.g. \r\n to \n), as the content will then not agree
+ not set to automatically convert end-of-line characters 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>
</warning>
@@ -2264,7 +2270,7 @@
<para>Both of <command>svndumpfilter</command>'s subcommands
accept options for deciding how to deal with
<quote>empty</quote> revisions. If a given revision
- contained only changes to paths that were filtered out, that
+ contains only changes to paths that were filtered out, that
now-empty revision could be considered uninteresting or even
unwanted. So to give the user control over what to do with
those revisions, <command>svndumpfilter</command> provides
@@ -2302,7 +2308,7 @@
</variablelist>
<para>While <command>svndumpfilter</command> can be very
- useful, and a huge timesaver, there are unfortunately a
+ useful and a huge timesaver, there are unfortunately a
couple of gotchas. First, this utility is overly sensitive
to path semantics. Pay attention to whether paths in your
dump file are specified with or without leading slashes.
@@ -2323,12 +2329,12 @@
usage of leading slashes for some reason,
<footnote>
<para>While <command>svnadmin dump</command> has a
- consistent leading slash policy—to not include
- them—other programs which generate dump data might
+ consistent leading slash policy (to not include
+ them), other programs that generate dump data might
not be so consistent.</para>
</footnote>
you should probably normalize those paths so they all
- have, or lack, leading slashes.</para>
+ have, or all lack, leading slashes.</para>
<para>Also, copied paths can give you some trouble.
Subversion supports copy operations in the repository, where
@@ -2343,7 +2349,7 @@
files created by the copy—and not represent that
addition as a copy from a source that won't exist in your
filtered dump data stream. But because the Subversion
- repository dump format only shows what was changed in each
+ repository dump format shows only what was changed in each
revision, the contents of the copy source might not be
readily available. If you suspect that you have any copies
of this sort in your repository, you might want to rethink
@@ -2361,13 +2367,13 @@
<filename>trunk/my-project</filename>. But the resulting
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 which added the
+ data might begin with the revision that added the
<filename>trunk/my-project</filename> directory, but it will
- <emphasis>not</emphasis> contain directives which would
+ <emphasis>not</emphasis> contain directives that would
create the <filename>trunk</filename> directory itself
(because <filename>trunk</filename> doesn't match the
include filter). You'll need to make sure that any
- directories which the new dump stream expect to exist
+ directories that the new dump stream expects to exist
actually do exist in the target repository before trying to
load the stream into that repository.</para>
@@ -2389,17 +2395,17 @@
<para>As of version 1.4, Subversion provides a program for
managing scenarios like
- these—<command>svnsync</command>.
- <command>svnsync</command> works by essentially asking the
- Subversion server to <quote>replay</quote> revisions, one at a
- time. It then uses that revision information to mimic a
- commit of the same to another repository. Neither repository
- needs to be locally accessible to 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) interfaces. All it requires is read
- access to the source repository and read/write access to the
- destination repository.</para>
+ these—<command>svnsync</command>. This works by
+ essentially asking the Subversion server to
+ <quote>replay</quote> revisions, one at a time. It then uses
+ that revision information to mimic a commit of the same to
+ 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)
+ interfaces. All it requires is read access to the source
+ repository and read/write access to the destination
+ repository.</para>
<note>
<para>When using <command>svnsync</command> against a remote
@@ -2409,12 +2415,12 @@
<para>Assuming you already have a source repository that you'd
like to mirror, the next thing you need is an empty target
- repository which will actually serve as that mirror. This
+ repository that will actually serve as that mirror. This
target repository can use either of the available filesystem
- data-store back-ends (see <xref
+ data-store backends (see <xref
linkend="svn.reposadmin.basics.backends" />), but it must not
- yet have any version history in it. The protocol via which
- <command>svnsync</command> communicates revision information
+ yet have any version history in it. The protocol that
+ <command>svnsync</command> uses to communicate revision information
is highly sensitive to mismatches between the versioned
histories contained in the source and target repositories.
For this reason, while <command>svnsync</command> cannot
@@ -2455,14 +2461,14 @@
<tip>
<para>It's a good idea to implement authorization measures
- which allow your repository replication process to perform
+ that allow your repository replication process to perform
its tasks while preventing other users from modifying the
contents of your mirror repository at all.</para>
</tip>
<para>Let's walk through the use of <command>svnsync</command>
in a somewhat typical mirroring scenario. We'll pepper this
- discourse with practical recommendations which you are free to
+ discourse with practical recommendations, which you are free to
disregard if they aren't required by or suitable for your
environment.</para>
@@ -2472,14 +2478,14 @@
publicly on the Internet, hosted on a different machine than
the one on which the original Subversion source code
repository lives. This remote host has a global configuration
- which permits anonymous users to read the contents of
+ 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
glossing over the details of Subversion server configuration
for the moment—those are covered thoroughly in <xref
linkend="svn.serverconfig" />.) And for no other reason than
that it makes for a more interesting example, we'll be driving
- the replication process from a third machine, the one which
+ the replication process from a third machine—the one that
we currently find ourselves using.</para>
<para>First, we'll create the repository which will be our
@@ -2506,7 +2512,7 @@
<literal>syncuser</literal> will be allowed.</para>
<para>We'll use the repository's hook system both to allow the
- replication process to do what it needs to do, and to enforce
+ replication process to do what it needs to do and to enforce
that only it is doing those things. We accomplish this by
implementing two of the repository event
hooks—pre-revprop-change and start-commit. Our
@@ -2564,7 +2570,12 @@
<command>svnsync</command> is to register in our target
repository the fact that it will be a mirror of the source
repository. We do this using the <command>svnsync
- initialize</command> subcommand.</para>
+ initialize</command> subcommand. The URLs we provide point to
+ the root directories of the target and source repositories,
+ respectively. In Subversion 1.4, this is required—only
+ full mirroring of repositories is permitted. In Subversion
+ 1.5, though, you can use <command>svnsync</command> to mirror
+ only some subtree of the repository, too.</para>
<screen>
$ svnsync help init
@@ -2587,34 +2598,26 @@
pre-revprop-change hook on our mirror repository.</para>
<note>
- <para>The URLs provided to <command>svnsync</command> must
- point to the root directories of the target and source
- repositories, respectively. The tool does not handle
- mirroring of repository subtrees.</para>
- </note>
-
- <note>
- <para>In Subversion 1.4, the values
- given to <command>svnsync</command>'s <option>--username</option> and
+ <para>In Subversion 1.4, the values given to
+ <command>svnsync</command>'s <option>--username</option> and
<option>--password</option> command-line options were used
for authentication against both the source and destination
repositories. This caused problems when a user's
credentials weren't exactly the same for both repositories,
- especially when running in non-interactive
- mode (with the <option>--non-interactive</option> option)
- might experience problems.</para>
+ especially when running in noninteractive mode (with the
+ <option>--non-interactive</option> option).</para>
<para>This has been fixed in Subversion 1.5 with the
- introduction of two new pairs of options. Use the
+ introduction of two new pairs of options. Use
<option>--source-username</option> and
- <option>--source-password</option> options to provide
- authentication credentials for the source repository; use
+ <option>--source-password</option> to provide authentication
+ credentials for the source repository; use
<option>--sync-username</option> and
<option>--sync-password</option> to provide credentials for
the destination repository. (The old
- <command>--username</command> and
- <command>--password</command> options still exist for
- compatibility, but we advise against using them.)</para>
+ <option>--username</option> and <option>--password</option>
+ options still exist for compatibility, but we advise against
+ using them.)</para>
</note>
@@ -2625,22 +2628,22 @@
<footnote>
<para>Be forewarned that while it will take only a few
seconds for the average reader to parse this paragraph and
- the sample output which follows it, the actual time
+ the sample output that follows it, the actual time
required to complete such a mirroring operation is, shall
we say, quite a bit longer.</para>
</footnote>
The <command>svnsync synchronize</command> subcommand will
peek into the special revision properties previously stored on
- the target repository, and determine what repository it is
- mirroring and that the most recently mirrored revision was
- revision 0. Then it will query the source repository and
- determine what the latest revision in that repository is.
- Finally, it asks the source repository's server to start
- replaying all the revisions between 0 and that latest
- revision. As <command>svnsync</command> get the resulting
- response from the source repository's server, it begins
- forwarding those revisions to the target repository's server
- as new commits.</para>
+ the target repository, and determine both what repository it
+ is mirroring as well as that the most recently mirrored
+ revision was revision 0. Then it will query the source
+ repository and determine what the latest revision in that
+ repository is. Finally, it asks the source repository's
+ server to start replaying all the revisions between 0 and that
+ latest revision. As <command>svnsync</command> get the
+ resulting response from the source repository's server, it
+ begins forwarding those revisions to the target repository's
+ server as new commits.</para>
<screen>
$ svnsync help synchronize
@@ -2676,37 +2679,37 @@
revision, there is first a commit of that revision to the
target repository, and then property changes follow. This is
because the initial commit is performed by (and attributed to)
- the user <literal>syncuser</literal>, and datestamped with the
- time as of that revision's creation. Also, Subversion's
- underlying repository access interfaces don't provide a
- mechanism for setting arbitrary revision properties as part of
- a commit. So <command>svnsync</command> follows up with an
- immediate series of property modifications which copy all the
- revision properties found for that revision in the source
- repository into the target repository. This also has the
- effect of fixing the author and datestamp of the revision
- to match that of the source repository.</para>
+ the user <literal>syncuser</literal>, and it is datestamped
+ with the time as of that revision's creation. Also,
+ Subversion's underlying repository access interfaces don't
+ provide a mechanism for setting arbitrary revision properties
+ as part of a commit. So <command>svnsync</command> follows up
+ with an immediate series of property modifications that copy
+ into the target repository all the revision properties found
+ for that revision in the source repository. This also has the
+ effect of fixing the author and datestamp of the revision to
+ match that of the source repository.</para>
<para>Also noteworthy is that <command>svnsync</command>
performs careful bookkeeping that allows it to be safely
interrupted and restarted without ruining the integrity of the
mirrored data. If a network glitch occurs while mirroring a
repository, simply repeat the <command>svnsync
- synchronize</command> command and it will happily pick up
+ 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>
+ in order to keep your mirror up to date.</para>
<para>There is, however, one bit of inelegance in the process.
Because Subversion revision properties can be changed at any
- time throughout the lifetime of the repository, and don't
- leave an audit trail that indicates when they were changed,
- replication processes have to pay special attention to them.
- If you've already mirrored the first 15 revisions of a
- repository and someone then changes a revision property on
+ time throughout the lifetime of the repository, and because
+ they don't leave an audit trail that indicates when they were
+ changed, replication processes have to pay special attention
+ to them. If you've already mirrored the first 15 revisions of
+ a repository and someone then changes a revision property on
revision 12, <command>svnsync</command> won't know to go back
and patch up its copy of revision 12. You'll need to tell it
- to do so manually by using (or with some additionally tooling
+ 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
properties for a particular revision or range thereof.</para>
@@ -2729,7 +2732,7 @@
might wish to have your primary repository push changes to one
or more blessed mirrors as part of its post-commit and
post-revprop-change hook implementations. This would enable
- the mirror to be up-to-date in as near to realtime as is
+ the mirror to be up to date in as near to real time as is
likely possible.</para>
<para>Also, while it isn't very commonplace to do so,
@@ -2745,25 +2748,25 @@
through some hoops to make it happen. First, you need to
ensure that both the primary and mirror repositories have the
same repository UUID (which is not the case by default). See
- <xref linkend="svn.reposadmin.maint.uuids" /> for more about
- managing repository UUIDs.</para>
+ <xref linkend="svn.reposadmin.maint.uuids" /> later in this
+ chapter for more about this.</para>
- <para>Once the two repositories have the same UUID, you can
- use <command>svn switch --relocate</command> to point your
- working copy to whichever of the repositories you wish to
- operate against, a process which is described in <xref
+ <para>Once the two repositories have the same UUID, you can use
+ <command>svn switch --relocate</command> to point your working
+ copy to whichever of the repositories you wish to operate
+ against, a process that is described in <xref
linkend="svn.ref.svn.c.switch" />. There is a possible danger
here, though, in that if the primary and mirror repositories
- aren't in close synchronization, a working copy up-to-date
+ aren't in close synchronization, a working copy up to date
with, and pointing to, the primary repository will, if
relocated to point to an out-of-date mirror, become confused
about the apparent sudden loss of revisions it fully expects
- to be present, and throws errors to that effect. If this
- occurs, you can relocate your working copy back to the primary
- repository and then either wait until the mirror repository is
- up-to-date, or backdate your working copy to a revision you
- know is present in the sync repository and then retry the
- relocation.</para>
+ to be present, and it will throw errors to that effect. If
+ this occurs, you can relocate your working copy back to the
+ primary repository and then either wait until the mirror
+ repository is up to date, or backdate your working copy to a
+ revision you know is present in the sync repository, and then
+ retry the relocation.</para>
<para>Finally, be aware that the revision-based replication
provided by <command>svnsync</command> is only
@@ -2786,7 +2789,7 @@
the modern computer, one thing unfortunately rings true with
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
+ RAM, and crashed hard drives are but a taste of the evil that
Fate is poised to unleash on even the most conscientious
administrator. And so we arrive at a very important
topic—how to make backup copies of your repository
@@ -2800,11 +2803,11 @@
a catastrophe. Usually, it means, quite literally, the
duplication of the entire repository directory (which includes
either a Berkeley DB or FSFS environment). Incremental
- backups are lesser things, backups of only the portion of the
+ backups are lesser things: backups of only the portion of the
repository data that has changed since the previous
backup.</para>
- <para>As far as full backups go, the naive approach might seem
+ <para>As far as full backups go, the naïve 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
@@ -2833,7 +2836,7 @@
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>
+ command line.</para>
<screen>
$ svnadmin hotcopy --clean-logs /var/svn/bdb-repos /var/svn/bdb-repos-backup
@@ -2847,13 +2850,13 @@
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
+ 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
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
+ (such as <command>cron</command> on Unix systems), which can
cause it to run nightly (or at whatever granularity of Time
you deem safe).</para>
@@ -2872,10 +2875,10 @@
that restoring that data can take a long time—longer
with each new revision committed to your repository. Also, as
is the case with so many of the various backup methods,
- revision property changes made to already-backed-up revisions
- won't get picked up by a non-overlapping, incremental dump
- generation. For these reasons, we recommend against relying
- solely on dump-based backup approaches.</para>
+ revision property changes that are made to already backed-up
+ revisions won't get picked up by a nonoverlapping,
+ incremental dump generation. For these reasons, we recommend
+ against relying solely on dump-based backup approaches.</para>
<para>As you can see, each of the various backup types and
methods has its advantages and disadvantages. The easiest is
@@ -2902,7 +2905,7 @@
falls over. The primary disadvantage of this method is that
only the versioned repository data gets
synchronized—repository configuration files,
- user-specified repository path locks, and other items which
+ 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>
@@ -2925,17 +2928,17 @@
backup.</para>
<para>Generally speaking, only the truly paranoid would need to
- backup their entire repository, say, every time a commit
+ back up their entire repository, say, every time a commit
occurred. However, assuming that a given repository has some
other redundancy mechanism in place with relatively fine
- granularity (like per-commit emails or incremental dumps), a
+ granularity (such as per-commit emails or incremental dumps), 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. 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 which leverages combinations of the methods
+ 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
@@ -2950,7 +2953,7 @@
might not save your hardware from the iron fist of Fate,
<footnote>
<para>You know—the collective term for all of her
- <quote>fickle fingers</quote>.</para>
+ <quote>fickle fingers.</quote></para>
</footnote>
it should certainly help you recover from those trying
times.</para>
@@ -2980,9 +2983,9 @@
original so that, in the event that you have to restore that
backup and replace the live repository, users don't suddenly
see what looks like a different repository. When dumping and
- loading repository history (as described in <xref
+ loading repository history (as described earlier in <xref
linkend="svn.reposadmin.maint.migrate" />), you get to decide
- whether or not to apply the UUID encapsulated in the data dump
+ whether to apply the UUID encapsulated in the data dump
stream to the repository you are loading the data into. The
particular circumstance will dictate the correct
behavior.</para>
@@ -2993,7 +2996,7 @@
setuuid</command> command. If you provide this subcommand
with an explicit UUID, it will validate that the UUID is
well-formed and then set the repository UUID to that value.
- If you omit the UUID, a brand new UUID will be generated for
+ If you omit the UUID, a brand-new UUID will be generated for
your repository.</para>
<screen>
@@ -3054,9 +3057,9 @@
applications, and so on.</para>
<para>Of course, there's often still more to be done when trying
- to cleanly affect changes like this. For example, you might
+ to cleanly affect changes such as this. For example, you might
need to update your Subversion server configuration to point to
- the new location of a relocated repository, or to remove
+ the new location of a relocated repository or to remove
configuration bits for a now-deleted repository. If you have
automated processes that publish information from or about your
repositories, they may need to be updated. Hook scripts might
@@ -3088,7 +3091,7 @@
create, configure, and maintain Subversion repositories. We've
introduced you to the various tools that will assist you with
this task. Throughout the chapter, we've noted common
- administration pitfalls, and suggestions for avoiding
+ administration pitfalls and offered suggestions for avoiding
them.</para>
<para>All that remains is for you to decide what exciting data to
Modified: trunk/src/de/book/ch07-customizing-svn.xml
==============================================================================
--- trunk/src/de/book/ch07-customizing-svn.xml (original)
+++ trunk/src/de/book/ch07-customizing-svn.xml Mon Apr 7 15:06:30 2008
@@ -2,9 +2,9 @@
<title>Customizing Your Subversion Experience</title>
<para>Version control can be a complex subject, as much art as
- science, and offering myriad ways of getting stuff done.
- Throughout this book you've read of the various Subversion
- command-line client subcommands and the options which modify their
+ science, that offers myriad ways of getting stuff done.
+ Throughout this book, you've read of the various Subversion
+ command-line client subcommands and the options that modify their
behavior. In this chapter, we'll look into still more ways to
customize the way Subversion works for you—setting up the
Subversion runtime configuration, using external helper
@@ -27,7 +27,7 @@
controlled by the user. Many of these options are of the kind
that a user would wish to apply to all Subversion operations.
So, rather than forcing users to remember command-line arguments
- for specifying these options, and to use them for every
+ for specifying these options and to use them for every
operation they perform, Subversion uses configuration files,
segregated into a Subversion configuration area.</para>
@@ -38,7 +38,7 @@
which are just text files in standard INI format (with
<quote>sections</quote> providing the second tier). These files
can be easily edited using your favorite text editor (such as
- Emacs or vi), and contain directives read by the client to
+ Emacs or vi), and that contain directives read by the client to
determine which of several optional behaviors the user
prefers.</para>
@@ -54,8 +54,8 @@
folder named <filename>Subversion</filename>, typically inside
the <filename>Application Data</filename> area of the user's
profile directory (which, by the way, is usually a hidden
- directory). However, on this platform the exact location
- differs from system to system, and is dictated by the Windows
+ directory). However, on this platform, the exact location
+ differs from system to system and is dictated by the Windows
registry.
<footnote>
<para>The <literal>APPDATA</literal> environment variable
@@ -87,13 +87,13 @@
<para>The per-user configuration area currently contains three
files—two configuration files (<filename>config</filename> and
<filename>servers</filename>), and a <filename>README.txt</filename>
- file which describes the INI format. At the time of their
+ file, which describes the INI format. At the time of their
creation, the files contain default values for each of the
supported Subversion options, mostly commented out and grouped
with textual descriptions about how the values for the key
affect Subversion's behavior. To change a certain behavior,
you need only to load the appropriate configuration file into
- a text editor, and modify the desired option's value. If at
+ a text editor, and to modify the desired option's value. If at
any time you wish to have the default configuration settings
restored, you can simply remove (or rename) your configuration
directory and then run some innocuous <command>svn</command>
@@ -161,7 +161,7 @@
</orderedlist>
<para>Also, the Windows Registry doesn't really support the
- notion of something being <quote>commented out</quote>.
+ notion of something being <quote>commented out.</quote>
However, Subversion will ignore any option key whose name
begins with a hash (<literal>#</literal>) character. This
allows you to effectively comment out a Subversion option
@@ -169,16 +169,18 @@
simplifying the process of restoring that option.</para>
<para>The <command>svn</command> command-line client never
- attempts to write to the Windows Registry, and will not
- attempt to create a default configuration area there. You can
- create the keys you need using the <command>REGEDIT</command>
+ attempts to write to the Windows Registry and will not attempt
+ to create a default configuration area there. You can create
+ the keys you need using the <command>REGEDIT</command>
program. Alternatively, you can create a
- <filename>.reg</filename> file, and then double-click on that
- file from the Explorer shell, which will cause the data to be
- merged into your registry.</para>
+ <filename>.reg</filename> file (such as the one in <xref
+ linkend="svn.advanced.confarea.windows-registry.ex-1" />), and
+ then double-click on that file's icon in the Explorer shell,
+ which will cause the data to be merged into your
+ registry.</para>
<example id="svn.advanced.confarea.windows-registry.ex-1">
- <title>Sample Registration Entries (.reg) File.</title>
+ <title>Sample registration entries (.reg) file.</title>
<programlisting>
REGEDIT4
@@ -219,19 +221,18 @@
"#enable-auto-props"=""
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]
-
</programlisting>
</example>
<para>The previous example shows the contents of a
- <filename>.reg</filename> file which contains some of the most
+ <filename>.reg</filename> file, which contains some of the most
commonly used configuration options and their default values.
Note the presence of both system-wide (for network
proxy-related options) and per-user settings (editor programs
and password storage, among others). Also note that all the
options are effectively commented out. You need only to
remove the hash (<literal>#</literal>) character from the
- beginning of the option names, and set the values as you
+ beginning of the option names and set the values as you
desire.</para>
</sect2>
@@ -243,7 +244,7 @@
<!-- TODO(cmpilato): Rework and move this section to the Reference -->
<para>In this section, we will discuss the specific
- run-time configuration options that are currently supported
+ runtime configuration options that are currently supported
by Subversion.</para>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
@@ -258,7 +259,7 @@
section is essentially a cross-reference table. The keys in
this section are the names of other sections in the file;
their values are <firstterm>globs</firstterm>—textual
- tokens which possibly contain wildcard
+ tokens that possibly contain wildcard
characters—that are compared against the hostnames of
the machine to which Subversion requests are sent.</para>
@@ -279,14 +280,14 @@
group name under the <literal>groups</literal> section. If
a match is made, Subversion then looks for a section in the
<filename>servers</filename> file whose name is the matched
- group's name. From that section it reads the actual network
+ group's name. From that section, it reads the actual network
configuration settings.</para>
<para>The <literal>global</literal> section contains the
settings that are meant for all of the servers not matched
by one of the globs under the <literal>groups</literal>
section. The options available in this section are
- exactly the same as those valid for the other server
+ exactly the same as those that are valid for the other server
sections in the file (except, of course, the special
<literal>groups</literal> section), and are as
follows:</para>
@@ -364,8 +365,8 @@
<term><literal>http-library</literal></term>
<listitem>
<para>Subversion provides a pair of repository access
- modules which understand its WebDAV network protocol.
- The original one which shipped with Subversion 1.0 is
+ modules that understand its WebDAV network protocol.
+ The original one, which shipped with Subversion 1.0, is
<literal>libsvn_ra_neon</literal> (though back then it
was called <literal>libsvn_ra_dav</literal>). Newer
Subversion versions also provide
@@ -458,14 +459,15 @@
<title>Config</title>
<para>The <filename>config</filename> file contains the rest
- of the currently available Subversion run-time options,
- those not related to networking. There are only a few
- options in use as of this writing, but they are again grouped into
- sections in expectation of future additions.</para>
+ of the currently available Subversion runtime
+ options—those not related to networking. There are
+ only a few options in use as of this writing, but they are
+ again grouped into sections in expectation of future
+ additions.</para>
<para>The <literal>auth</literal> section contains settings
related to Subversion's authentication and authorization
- against the repository. It contains:</para>
+ against the repository. It contains the following:</para>
<variablelist>
<varlistentry>
@@ -519,7 +521,7 @@
<para>This specifies the absolute path of a differencing
program, used when Subversion generates
<quote>diff</quote> output (such as when using the
- <command>svn diff</command> command). By default
+ <command>svn diff</command> command). By default,
Subversion uses an internal differencing
library—setting this option will cause it to
perform this task using an external program. See
@@ -533,7 +535,7 @@
<para>This specifies the absolute path of a three-way
differencing program. Subversion uses this program to
merge changes made by the user with those received
- from the repository. By default Subversion uses an
+ from the repository. By default, Subversion uses an
internal differencing library—setting this
option will cause it to perform this task using an
external program. See <xref
@@ -589,7 +591,7 @@
items—for example, object files that result from
a program's compilation—in this display. The
<literal>global-ignores</literal> option is a list of
- whitespace-delimited globs which describe the names of
+ whitespace-delimited globs that describe the names of
files and directories that Subversion should not
display unless they are versioned. The default value
is <literal>*.o *.lo *.la #*# .*.rej *.rej .*~ *~
@@ -599,8 +601,8 @@
<command>svn add</command> and <command>svn import</command>
commands also ignore files that match the list
when they are scanning a directory. You can override this
- behaviour for a single instance of any of these commands
- by explicitly specifying the file name, or by using
+ behavior for a single instance of any of these commands
+ by explicitly specifying the filename, or by using
the <option>--no-ignore</option> command-line flag.</para>
<para>For information on more fine-grained control of
@@ -615,7 +617,7 @@
<para>This instructs Subversion to automatically set
properties on newly added or imported files. The
default value is <literal>no</literal>, so set this to
- <literal>yes</literal> to enable Auto-props.
+ <literal>yes</literal> to enable this feature.
The <literal>auto-props</literal> section of this file
specifies which properties are to be set on which files.</para>
</listitem>
@@ -628,7 +630,7 @@
encoding for commit log messages. It's a permanent
form of the <option>--encoding</option> option (see
<xref linkend="svn.ref.svn.sw"/>). The Subversion
- repository stores log messages in UTF-8, and assumes
+ repository stores log messages in UTF-8 and assumes
that your log message is written using your operating
system's native locale. You should specify a
different encoding if your commit messages are written
@@ -681,8 +683,8 @@
<term><literal>preserved-conflict-file-exts</literal></term>
<listitem>
<para>The value of this option is a space-delimited list
- of file extensions which Subversion should preserve
- when generating conflict file names. By default, the
+ of file extensions that Subversion should preserve
+ when generating conflict filenames. By default, the
list is empty. This option is new to Subversion
1.5.</para>
@@ -692,9 +694,9 @@
pristine copies of the various competing versions of
the file in the working copy. By default, those
conflict files have names constructed by appending to
- the original file name a custom extension such as
- <literal>.mine</literal> or
- <literal>.<replaceable>REV</replaceable></literal>
+ the original filename a custom extension such as
+ <filename>.mine</filename> or
+ <filename>.<replaceable>REV</replaceable></filename>
(where <replaceable>REV</replaceable> is a revision
number). A mild annoyance with this naming scheme is
that on operating systems where a file's extension
@@ -708,10 +710,10 @@
<filename>ReleaseNotes.pdf.r4231</filename>. While
your system might be configured to use Adobe's Acrobat
Reader to open files whose extensions are
- <literal>.pdf</literal>, there probably isn't an
+ <filename>.pdf</filename>, there probably isn't an
application configured on your system to open all
files whose extensions are
- <literal>.r4321</literal>.</para>
+ <filename>.r4321</filename>.</para>
<para>You can fix this annoyance by using this
configuration option, though. For files with one of
@@ -719,14 +721,14 @@
the conflict file names the custom extension just as
before, but then also re-append the file's original
extension. Using the previous example, and assuming
- that <literal>pdf</literal> is one of the extensions
+ that <filename>pdf</filename> is one of the extensions
configured in this list thereof, the conflict files
generated for <filename>ReleaseNotes.pdf</filename>
would instead be named
<filename>ReleaseNotes.pdf.mine.pdf</filename> and
<filename>ReleaseNotes.pdf.r4231.pdf</filename>.
Because each of these files end in
- <literal>.pdf</literal>, the correct default
+ <filename>.pdf</filename>, the correct default
application will be used to view them.</para>
</listitem>
</varlistentry>
@@ -734,8 +736,8 @@
<varlistentry>
<term><literal>interactive-conflicts</literal></term>
<listitem>
- <para>This is a boolean option which specifies whether
- or not Subversion should try to resolve conflicts
+ <para>This is a boolean option that specifies whether
+ Subversion should try to resolve conflicts
interactively. If its value is <literal>yes</literal>
(which is the default value), Subversion will prompt
the user for how to handle conflicts in the manner
@@ -749,14 +751,15 @@
<varlistentry>
<term><literal>no-unlock</literal></term>
<listitem>
- <para>This boolean option corresponds to the
- <option>--no-unlock</option> option to <command>svn
- commit</command>, which tells Subversion not to release
- locks on files you've just committed. If this runtime
- option is set to <literal>yes</literal>, Subversion will
+ <para>This boolean option corresponds to <command>svn
+ commit</command>'s <option>--no-unlock</option>
+ option, which tells Subversion not to release locks on
+ files you've just committed. If this runtime option
+ is set to <literal>yes</literal>, Subversion will
never release locks automatically, leaving you to run
- <command>svn unlock</command> explicitly. It defaults to
- <literal>no</literal>.</para>
+ <command>svn unlock</command> explicitly. It defaults
+ to <literal>no</literal>.</para>
+
</listitem>
</varlistentry>
@@ -766,7 +769,7 @@
the Subversion client's ability to automatically set
properties on files when they are added or imported.
It contains any number of key-value pairs in the
- format <literal>PATTERN = PROPNAME=PROPVALUE</literal>
+ format <literal>PATTERN = PROPNAME=PROPVALUE</literal>,
where <literal>PATTERN</literal> is a file pattern
that matches a set of filenames and the rest of the
line is the property and its value. Multiple matches
@@ -795,14 +798,14 @@
<para><firstterm>Localization</firstterm> is the act of making
programs behave in a region-specific way. When a program
formats numbers or dates in a way specific to your part of the
- world, or prints messages (or accepts input) in your native
+ world or prints messages (or accepts input) in your native
language, the program is said to
be <firstterm>localized</firstterm>. This section describes
steps Subversion has made towards localization.</para>
<!-- =============================================================== -->
<sect2 id="svn.advanced.l10n.understanding">
- <title>Understanding locales</title>
+ <title>Understanding Locales</title>
<para>Most modern operating systems have a notion of the
<quote>current locale</quote>—that is, the region or
@@ -826,6 +829,7 @@
LC_NUMERIC="C"
LC_TIME="C"
LC_ALL="C"
+$
</screen>
<para>The output is a list of locale-related environment
@@ -858,7 +862,7 @@
<!-- =============================================================== -->
<sect2 id="svn.advanced.l10n.svnuse">
- <title>Subversion's use of locales</title>
+ <title>Subversion's Use of Locales</title>
<para>The Subversion client, <command>svn</command>, honors the
current locale configuration in two ways. First, it notices
@@ -911,11 +915,11 @@
<para>For example, suppose you create a file named
<filename>caffè.txt</filename>, and then when committing the
file, you write the log message as <quote>Adesso il caffè è
- più forte</quote>. Both the filename and log message contain
+ più forte.</quote> Both the filename and log message contain
non-ASCII characters, but because your locale is set to
<literal>it_IT</literal>, the Subversion client knows to
interpret them as Italian. It uses an Italian character set
- to convert the data to UTF-8 before sending them off to the
+ to convert the data to UTF-8 before sending it off to the
repository.</para>
<para>Note that while the repository demands UTF-8 filenames and
@@ -926,7 +930,7 @@
contents.</para>
<sidebar>
- <title>Character set conversion errors</title>
+ <title>Character Set Conversion Errors</title>
<para>While using Subversion, you might get hit with an error
related to character set conversions:</para>
@@ -948,7 +952,7 @@
update</command>.</para>
<para>The solution is either to set your locale to something
- which <emphasis>can</emphasis> represent the incoming UTF-8
+ that <emphasis>can</emphasis> represent the incoming UTF-8
data, or to change the filename or log message in the
repository. (And don't forget to slap your collaborator's
hand—projects should decide on common languages ahead of
@@ -991,7 +995,7 @@
on demand.</para>
<para>Subversion supports this by allowing you to specify an
- external text editor which it will launch as necessary in order
+ external text editor that it will launch as necessary in order
to give you a more powerful input mechanism for this textual
metadata. There are several ways to tell Subversion which
editor you'd like use. Subversion checks the following things,
@@ -1053,7 +1057,7 @@
<sect1 id="svn.advanced.externaldifftools">
<title>Using External Differencing and Merge Tools</title>
- <para>The interface between Subversion and external 2- and 3-way
+ <para>The interface between Subversion and external two- and three-way
differencing tools harkens back to a time when Subversion's only
contextual differencing capabilities were built around
invocations of the GNU diffutils toolchain, specifically the
@@ -1086,19 +1090,19 @@
that program can understand those options. And that's where
things get unintuitive for most users.</para>
- <para>The key to using external 2- and 3-way differencing tools
+ <para>The key to using external two- and three-way differencing tools
(other than GNU diff and diff3, of course) with Subversion is to
- use wrapper scripts which convert the input from Subversion into
+ use wrapper scripts, which convert the input from Subversion into
something that your differencing tool can understand, and then
- to convert the output of your tool back into a format which
+ to convert the output of your tool back into a format that
Subversion expects—the format that the GNU tools would
have used. The following sections cover the specifics of those
expectations.</para>
<note>
- <para>The decision on when to fire off a contextual 2- or 3-way
+ <para>The decision on when to fire off a contextual two- or three-way
diff as part of a larger Subversion operation is made entirely
- by Subversion, and is affected by, among other things, whether
+ by Subversion and is affected by, among other things, whether
or not the files being operated on are human-readable as
determined by their <literal>svn:mime-type</literal> property.
This means, for example, that even if you had the niftiest
@@ -1119,16 +1123,16 @@
runtime configuration option to find the name of an external
merge tool and, upon finding one, launch that tool with the
appropriate input files. This differs from the configurable
- 3-way differencing tool in a couple of ways. First, the
- differencing tool is always used to handle 3-way differences,
- whereas the merge tool is only employed when 3-way difference
- application has detected a conflict. Secondly, the interface is
- much cleaner—your configured merge tool need only accept
- on its command line four path specifications: the base file, the
- <quote>theirs</quote> file (which contains upstream changes),
- the <quote>mine</quote> file (which contains local
- modifications), and the path of the file where the final
- resolved contents should be stored.</para>
+ three-way differencing tool in a couple of ways. First, the
+ differencing tool is always used to handle three-way
+ differences, whereas the merge tool is only employed when
+ three-way difference application has detected a conflict.
+ Secondly, the interface is much cleaner—your configured
+ merge tool need only accept as command-line parameters four path
+ specifications: the base file, the <quote>theirs</quote> file
+ (which contains upstream changes), the <quote>mine</quote> file
+ (which contains local modifications), and the path of the file
+ where the final resolved contents should be stored.</para>
<!-- =============================================================== -->
<sect2 id="svn.advanced.externaldifftools.diff">
@@ -1138,7 +1142,7 @@
suitable for the GNU diff utility, and expects only that the
external program return with a successful error code. For
most alternative diff programs, only the sixth and seventh
- arguments—the paths of the files which represent the left and
+ arguments—the paths of the files that represent the left and
right sides of the diff, respectively—are of interest. Note
that Subversion runs the diff program once per modified file
covered by the Subversion operation, so if your program runs
@@ -1213,15 +1217,15 @@
<para>Subversion calls external merge programs with parameters
suitable for the GNU diff3 utility, expecting that the
external program return with a successful error code and that
- the full file contents which result from the completed merge
+ the full file contents that result from the completed merge
operation are printed on the standard output stream (so that
Subversion can redirect them into the appropriate version
controlled file). For most alternative merge programs, only
the ninth, tenth, and eleventh arguments, the paths of the
- files which represent the <quote>mine</quote>,
- <quote>older</quote>, and <quote>yours</quote> inputs,
+ files which represent the <quote>mine,</quote>
+ <quote>older,</quote> and <quote>yours</quote> inputs,
respectively, are of interest. Note that because Subversion
- depends on the output of your merge program, you wrapper
+ depends on the output of your merge program, your wrapper
script must not exit before that output has been delivered to
Subversion. When it finally does exit, it should return an
error code of 0 if the merge was successful, or 1 if unresolved
Modified: trunk/src/de/book/ch08-embedding-svn.xml
==============================================================================
--- trunk/src/de/book/ch08-embedding-svn.xml (original)
+++ trunk/src/de/book/ch08-embedding-svn.xml Mon Apr 7 15:06:30 2008
@@ -36,7 +36,8 @@
these layers shortly, but first, let's briefly summarize
Subversion's various libraries. For the sake of consistency, we
will refer to the libraries by their extensionless Unix library
- names (libsvn_fs, libsvn_wc, mod_dav_svn, etc.).</para>
+ names (<filename>libsvn_fs</filename>, <filename>libsvn_wc</filename>,
+ <filename>mod_dav_svn</filename>, etc.).</para>
<variablelist>
<varlistentry>
@@ -62,12 +63,12 @@
<varlistentry>
<term>libsvn_fs_base</term>
<listitem><para>The Berkeley DB filesystem
- back-end</para></listitem>
+ backend</para></listitem>
</varlistentry>
<varlistentry>
<term>libsvn_fs_fs</term>
<listitem><para>The native filesystem (FSFS)
- back-end</para></listitem>
+ backend</para></listitem>
</varlistentry>
<varlistentry>
<term>libsvn_ra</term>
@@ -75,7 +76,7 @@
loader</para></listitem>
</varlistentry>
<varlistentry>
- <term>libsvn_ra_dav</term>
+ <term>libsvn_ra_neon</term>
<listitem><para>The WebDAV Repository Access
module</para></listitem>
</varlistentry>
@@ -120,8 +121,8 @@
</varlistentry>
</variablelist>
- <para>The fact that the word <quote>miscellaneous</quote> only
- appears once in the previous list is a good sign. The
+ <para>The fact that the word <quote>miscellaneous</quote>
+ appears only once in the previous list is a good sign. The
Subversion development team is serious about making sure that
functionality lives in the right layer and libraries. Perhaps
the greatest advantage of the modular design is its lack of
@@ -133,24 +134,30 @@
<para>Another benefit of modularity is the ability to replace a
given module with a whole new library that implements the same
API without affecting the rest of the code base. In some sense,
- this happens within Subversion already. The libsvn_ra_dav,
- libsvn_ra_local, libsvn_ra_serf, and libsvn_ra_svn libraries
- each implement the same interface, all working as plugins to
- libsvn_ra. And all four communicate with the Repository
- Layer—libsvn_ra_local connects to the repository directly;
- the other three do so over a network. The libsvn_fs_base and
- libsvn_fs_fs libraries are another pair of libraries that
- implement the same functionality in different ways—both
- are plugins to the common libsvn_fs library.</para>
+ this happens within Subversion already. The
+ <filename>libsvn_ra_neon</filename>,
+ <filename>libsvn_ra_local</filename>,
+ <filename>libsvn_ra_serf</filename>, and
+ <filename>libsvn_ra_svn</filename> libraries each implement the
+ same interface, all working as plugins to
+ <filename>libsvn_ra</filename>. And all four communicate with
+ the Repository Layer—libsvn_ra_local connects to the
+ repository directly; the other three do so over a network. The
+ <filename>libsvn_fs_base</filename> and
+ <filename>libsvn_fs_fs</filename> libraries are another pair of
+ libraries that implement the same functionality in different
+ ways—both are plugins to the common
+ <filename>libsvn_fs</filename> library.</para>
<para>The client itself also highlights the benefits of modularity
- in the Subversion design. Subversion's libsvn_client library is
- a one-stop shop for most of the functionality necessary for
- designing a working Subversion client (see <xref
+ in the Subversion design. Subversion's
+ <filename>libsvn_client</filename> library is a one-stop shop
+ for most of the functionality necessary for designing a working
+ Subversion client (see <xref
linkend="svn.developer.layerlib.client"/>). So while the
Subversion distribution provides only the <command>svn</command>
command-line client program, there are several third-party
- programs which provide various forms of graphical client UI.
+ programs that provide various forms of graphical client UIs.
These GUIs use the same APIs that the stock command-line client
does. This type of modularity has played a large role in the
proliferation of available Subversion clients and IDE
@@ -163,42 +170,46 @@
<para>When referring to Subversion's Repository Layer, we're
generally talking about two basic concepts—the versioned
- filesystem implementation (accessed via libsvn_fs, and
- supported by its libsvn_fs_base and libsvn_fs_fs plugins), and
- the repository logic that wraps it (as implemented in
- libsvn_repos). These libraries provide the storage and
- reporting mechanisms for the various revisions of your
- version-controlled data. This layer is connected to the
- Client Layer via the Repository Access Layer, and is, from the
- perspective of the Subversion user, the stuff at the
+ filesystem implementation (accessed via
+ <filename>libsvn_fs</filename>, and supported by its
+ <filename>libsvn_fs_base</filename> and
+ <filename>libsvn_fs_fs</filename> plugins), and the repository
+ logic that wraps it (as implemented in
+ <filename>libsvn_repos</filename>). These libraries provide
+ the storage and reporting mechanisms for the various revisions
+ of your version-controlled data. This layer is connected to
+ the Client Layer via the Repository Access Layer, and is, from
+ the perspective of the Subversion user, the stuff at the
<quote>other end of the line.</quote></para>
<para>The Subversion Filesystem is not a kernel-level filesystem
- that one would install in an operating system (like the Linux
- ext2 or NTFS), but a virtual filesystem. Rather than storing
- <quote>files</quote> and <quote>directories</quote> as real
- files and directories (as in, the kind you can navigate
- through using your favorite shell program), it uses one of two
- available abstract storage backends—either a Berkeley DB
- database environment, or a flat-file representation. (To
- learn more about the two repository back-ends, see <xref
+ that one would install in an operating system (such as the
+ Linux ext2 or NTFS), but instead is a a virtual filesystem.
+ Rather than storing <quote>files</quote> and
+ <quote>directories</quote> as real files and directories (the
+ kind you can navigate through using your favorite shell
+ program), it uses one of two available abstract storage
+ backends—either a Berkeley DB database environment or a
+ flat-file representation. (To learn more about the two
+ repository backends, see <xref
linkend="svn.reposadmin.basics.backends"/>.) There has even
been considerable interest by the development community in
giving future releases of Subversion the ability to use other
- back-end database systems, perhaps through a mechanism such as
+ backend database systems, perhaps through a mechanism such as
Open Database Connectivity (ODBC). In fact, Google did
something similar to this before launching the Google Code
- Project Hosting service: they announced in mid-2006 that members
- of its Open Source team had written a new proprietary
- Subversion filesystem plugin which used their ultra-scalable
+ Project Hosting service: they announced in mid-2006 that
+ members of its open source team had written a new proprietary
+ Subversion filesystem plugin that used their ultra-scalable
Bigtable database for its storage.</para>
- <para>The filesystem API exported by libsvn_fs contains the
- kinds of functionality you would expect from any other
- filesystem API—you can create and remove files and
- directories, copy and move them around, modify file contents,
- and so on. It also has features that are not quite as common,
- such as the ability to add, modify, and remove metadata
+ <para>The filesystem API exported by
+ <filename>libsvn_fs</filename> contains the kinds of
+ functionality you would expect from any other filesystem
+ API—you can create and remove files and directories,
+ copy and move them around, modify file contents, and so on.
+ It also has features that are not quite as common, such as the
+ ability to add, modify, and remove metadata
(<quote>properties</quote>) on each file or directory.
Furthermore, the Subversion Filesystem is a versioning
filesystem, which means that as you make changes to your
@@ -239,21 +250,21 @@
confused with the transaction support provided by the
underlying database itself, especially given the former's
close proximity to the Berkeley DB database code in
- libsvn_fs_base. Both types of transaction exist to provide
- atomicity and isolation. In other words, transactions give
- you the ability to perform a set of actions in an
- all-or-nothing fashion—either all the actions in the
- set complete with success, or they all get treated as if
- <emphasis>none</emphasis> of them ever happened—and in
- a way that does not interfere with other processes acting on
- the data.</para>
+ <filename>libsvn_fs_base</filename>. Both types of
+ transaction exist to provide atomicity and isolation. In
+ other words, transactions give you the ability to perform a
+ set of actions in an all-or-nothing fashion—either all
+ the actions in the set complete with success, or they all
+ get treated as if <emphasis>none</emphasis> of them ever
+ happened—and in a way that does not interfere with
+ other processes acting on the data.</para>
<para>Database transactions generally encompass small
operations related specifically to the modification of data
in the database itself (such as changing the contents of a
table row). Subversion transactions are larger in scope,
- encompassing higher-level operations like making
- modifications to a set of files and directories which are
+ encompassing higher-level operations such as making
+ modifications to a set of files and directories that are
intended to be stored as the next revision of the filesystem
tree. If that isn't confusing enough, consider the fact
that Subversion uses a database transaction during the
@@ -277,7 +288,7 @@
filesystem paths. That is, from outside of the filesystem, the
primary mechanism for describing and accessing the individual
revisions of files and directories comes through the use of
- path strings like <filename>/foo/bar</filename>, just as if
+ path strings such as <filename>/foo/bar</filename>, just as if
you were addressing files and directories through your
favorite shell program. You add new files and directories by
passing their paths-to-be to the right API functions. You
@@ -287,8 +298,8 @@
enough information to identify a file or directory in
Subversion. Think of a directory tree as a two-dimensional
system, where a node's siblings represent a sort of
- left-and-right motion, and descending into subdirectories a
- downward motion. <xref
+ left-and-right motion, and navigating into the node's
+ subdirectories represents a downward motion. <xref
linkend="svn.developer.layerlib.repos.dia-1"/> shows a typical
representation of a tree as exactly that.</para>
@@ -310,9 +321,9 @@
In the filesystem interface, nearly every function that has a
<parameter>path</parameter> argument also expects a
<parameter>root</parameter> argument. This
- <structname>svn_fs_root_t</structname> argument describes
+ <literal>svn_fs_root_t</literal> argument describes
either a revision or a Subversion transaction (which is simply
- a revision-in-the-making), and provides that third-dimensional
+ a revision in the making) and provides that third-dimensional
context needed to understand the difference between
<filename>/foo/bar</filename> in revision 32, and the same
path as it exists in revision 98. <xref
@@ -325,24 +336,26 @@
<graphic fileref="images/ch08dia2.png"/>
</figure>
- <para>As we mentioned earlier, the libsvn_fs API looks and feels
- like any other filesystem, except that it has this wonderful
- versioning capability. It was designed to be usable by any
- program interested in a versioning filesystem. Not
- coincidentally, Subversion itself is interested in that
- functionality. But while the filesystem API should be
- sufficient for basic file and directory versioning support,
- Subversion wants more—and that is where libsvn_repos
+ <para>As we mentioned earlier, the
+ <filename>libsvn_fs</filename> API looks and feels like any
+ other filesystem, except that it has this wonderful versioning
+ capability. It was designed to be usable by any program
+ interested in a versioning filesystem. Not coincidentally,
+ Subversion itself is interested in that functionality. But
+ while the filesystem API should be sufficient for basic file
+ and directory versioning support, Subversion wants
+ more—and that is where <filename>libsvn_repos</filename>
comes in.</para>
- <para>The Subversion repository library (libsvn_repos) sits
- (logically speaking) atop the libsvn_fs API, providing
+ <para>The Subversion repository library
+ (<filename>libsvn_repos</filename>) sits (logically speaking)
+ atop the <filename>libsvn_fs</filename> API, providing
additional functionality beyond that of the underlying
versioned filesystem logic. It does not completely wrap each
and every filesystem function—only certain major steps
in the general cycle of filesystem activity are wrapped by the
repository interface. Some of these include the creation and
- commit of Subversion transactions, and the modification of
+ commit of Subversion transactions and the modification of
revision properties. These particular events are wrapped by
the repository layer because they have hooks associated with
them. A repository hook system is not strictly related to
@@ -351,32 +364,32 @@
<para>The hooks mechanism is but one of the reasons for the
abstraction of a separate repository library from the rest of
- the filesystem code. The libsvn_repos API provides several
- other important utilities to Subversion. These include the
- abilities to:</para>
+ the filesystem code. The <filename>libsvn_repos</filename>
+ API provides several other important utilities to Subversion.
+ These include the abilities to:</para>
<itemizedlist>
<listitem>
- <para>create, open, destroy, and perform recovery steps on a
+ <para>Create, open, destroy, and perform recovery steps on a
Subversion repository and the filesystem included in that
repository.</para>
</listitem>
<listitem>
- <para>describe the differences between two filesystem
+ <para>Describe the differences between two filesystem
trees.</para>
</listitem>
<listitem>
- <para>query for the commit log messages associated with all
+ <para>Query for the commit log messages associated with all
(or some) of the revisions in which a set of files was
modified in the filesystem.</para>
</listitem>
<listitem>
- <para>generate a human-readable <quote>dump</quote> of the
- filesystem, a complete representation of the revisions in
+ <para>Generate a human-readable <quote>dump</quote> of the
+ filesystem—a complete representation of the revisions in
the filesystem.</para>
</listitem>
<listitem>
- <para>parse that dump format, loading the dumped revisions
+ <para>Parse that dump format, loading the dumped revisions
into a different Subversion repository.</para>
</listitem>
</itemizedlist>
@@ -392,14 +405,18 @@
<title>Repository Access Layer</title>
<para>If the Subversion Repository Layer is at <quote>the other
- end of the line</quote>, the Repository Access (RA) Layer is
+ end of the line,</quote> the Repository Access (RA) Layer is
the line itself. Charged with marshaling data between the
client libraries and the repository, this layer includes the
- libsvn_ra module loader library, the RA modules themselves
- (which currently includes libsvn_ra_dav, libsvn_ra_local,
- libsvn_ra_serf, and libsvn_ra_svn), and any additional
+ <filename>libsvn_ra</filename> module loader library, the RA
+ modules themselves (which currently includes
+ <filename>libsvn_ra_neon</filename>,
+ <filename>libsvn_ra_local</filename>,
+ <filename>libsvn_ra_serf</filename>, and
+ <filename>libsvn_ra_svn</filename>), and any additional
libraries needed by one or more of those RA modules (such as
- the mod_dav_svn Apache module or libsvn_ra_svn's server,
+ the <filename>mod_dav_svn</filename> Apache module or
+ <filename>libsvn_ra_svn</filename>'s server,
<command>svnserve</command>).</para>
<para>Since Subversion uses URLs to identify its repository
@@ -417,22 +434,25 @@
<screen>
$ svn --version
-svn, version 1.4.3 (r23084)
- compiled Jan 18 2007, 07:47:40
+svn, version 1.5.0 (Beta 1)
+ compiled Mar 19 2008, 14:19:42
-Copyright (C) 2000-2006 CollabNet.
+Copyright (C) 2000-2008 CollabNet.
Subversion is open source software, see http://subversion.tigris.org/
This product includes software developed by CollabNet (http://www.Collab.Net/).
The following repository access (RA) modules are available:
-* ra_dav : Module for accessing a repository via WebDAV (DeltaV) protocol.
+* ra_neon : Module for accessing a repository via WebDAV protocol using Neon.
- handles 'http' scheme
- handles 'https' scheme
* ra_svn : Module for accessing a repository using the svn network protocol.
- handles 'svn' scheme
* ra_local : Module for accessing a repository on local disk.
- handles 'file' scheme
+* ra_serf : Module for accessing a repository via WebDAV protocol using serf.
+ - handles 'http' scheme
+ - handles 'https' scheme
$
</screen>
@@ -441,19 +461,21 @@
functionality necessary for sending and receiving versioned
data to and from the repository. And each of the available RA
plugins is able to perform that task using a specific
- protocol—libsvn_ra_dav speaks HTTP/WebDAV (optionally
- using SSL encryption) with an Apache HTTP Server that is
- running the mod_dav_svn Subversion server module;
- libsvn_ra_svn speaks a custom network protocol with the
- <command>svnserve</command> program; and so on.</para>
+ protocol—<filename>libsvn_ra_dav</filename> speaks
+ HTTP/WebDAV (optionally using SSL encryption) with an Apache
+ HTTP Server that is running the
+ <filename>mod_dav_svn</filename> Subversion server module;
+ <filename>libsvn_ra_svn</filename> speaks a custom network
+ protocol with the <command>svnserve</command> program; and so
+ on.</para>
- <para>And for those who wish to access a Subversion repository
+ <para>For those who wish to access a Subversion repository
using still another protocol, that is precisely why the
Repository Access Layer is modularized! Developers can simply
write a new library that implements the RA interface on one
side and communicates with the repository on the other. Your
- new library can use existing network protocols, or you can
- invent your own. You could use inter-process communication
+ new library can use existing network protocols or you can
+ invent your own. You could use interprocess communication
(IPC) calls, or—let's get crazy, shall we?—you
could even implement an email-based protocol. Subversion
supplies the APIs; you supply the creativity.</para>
@@ -468,32 +490,34 @@
all the action takes place. The bulk of functionality
implemented by the client-side libraries exists for the sole
purpose of managing working copies—directories full of
- files and other subdirectories which serve as a sort of local,
+ files and other subdirectories that serve as a sort of local,
editable <quote>reflection</quote> of one or more repository
locations—and propagating changes to and from the
Repository Access layer.</para>
- <para>Subversion's working copy library, libsvn_wc, is directly
- responsible for managing the data in the working copies. To
- accomplish this, the library stores administrative information
- about each working copy directory within a special
- subdirectory. This subdirectory, named
- <filename>.svn</filename>, is present in each working copy
- directory and contains various other files and directories
- which record state and provide a private workspace for
- administrative action. For those familiar with CVS, this
- <filename>.svn</filename> subdirectory is similar in purpose
- to the <filename>CVS</filename> administrative directories
- found in CVS working copies. For more information about the
- <filename>.svn</filename> administrative area, see <xref
- linkend="svn.developer.insidewc"/>in this chapter.</para>
-
- <para>The Subversion client library, libsvn_client, has the
- broadest responsibility; its job is to mingle the
- functionality of the working copy library with that of the
- Repository Access Layer, and then to provide the highest-level
- API to any application that wishes to perform general revision
- control actions. For example, the function
+ <para>Subversion's working copy library,
+ <filename>libsvn_wc</filename>, is directly responsible for
+ managing the data in the working copies. To accomplish this,
+ the library stores administrative information about each
+ working copy directory within a special subdirectory. This
+ subdirectory, named <filename>.svn</filename>, is present in
+ each working copy directory and contains various other files
+ and directories that record state and provide a private
+ workspace for administrative action. For those familiar with
+ CVS, this <filename>.svn</filename> subdirectory is similar in
+ purpose to the <filename>CVS</filename> administrative
+ directories found in CVS working copies. For more information
+ about the <filename>.svn</filename> administrative area, see
+ <xref linkend="svn.developer.insidewc"/> later in this
+ chapter.</para>
+
+ <para>The Subversion client library,
+ <filename>libsvn_client</filename>, has the broadest
+ responsibility; its job is to mingle the functionality of the
+ working copy library with that of the Repository Access Layer,
+ and then to provide the highest-level API to any application
+ that wishes to perform general revision control actions. For
+ example, the function
<function>svn_client_checkout()</function> takes a URL as an
argument. It passes this URL to the RA layer and opens an
authenticated session with a particular repository. It then
@@ -508,37 +532,39 @@
any number of GUI clients on top of the client library. New
GUIs (or any new client, really) for Subversion need not be
clunky wrappers around the included command-line
- client—they have full access via the libsvn_client API
- to same functionality, data, and callback mechanisms that the
- command-line client uses. In fact, the Subversion source code
- tree contains a small C program (which can be found at
- <filename>tools/examples/minimal_client.c</filename> that
+ client—they have full access via the
+ <filename>libsvn_client</filename> API to the same functionality,
+ data, and callback mechanisms that the command-line client
+ uses. In fact, the Subversion source code tree contains a
+ small C program (which can be found at
+ <filename>tools/examples/minimal_client.c</filename>) that
exemplifies how to wield the Subversion API to create a simple
- client program</para>
+ client program.</para>
<sidebar>
<title>Binding Directly—A Word About Correctness</title>
<para>Why should your GUI program bind directly with a
- libsvn_client instead of acting as a wrapper around a
- command-line program? Besides simply being more efficient,
- it can be more correct as well. A
- command-line program (like the one supplied with Subversion)
- that binds to the client library needs to effectively
- translate feedback and requested data bits from C types to
- some form of human-readable output. This type of
+ <filename>libsvn_client</filename> instead of acting as a
+ wrapper around a command-line program? Besides simply being
+ more efficient, it can be more correct as well. A
+ command-line program (such as the one supplied with
+ Subversion) that binds to the client library needs to
+ effectively translate feedback and requested data bits from
+ C types to some form of human-readable output. This type of
translation can be lossy. That is, the program may not
- display all of the information harvested from the API, or
- may combine bits of information for compact representation.</para>
+ display all of the information harvested from the API or may
+ combine bits of information for compact
+ representation.</para>
<para>If you wrap such a command-line program with yet another
program, the second program has access only to
- already-interpreted (and as we mentioned, likely incomplete)
+ already interpreted (and as we mentioned, likely incomplete)
information, which it must <emphasis>again</emphasis>
translate into <emphasis>its</emphasis> representation
format. With each layer of wrapping, the integrity of the
original data is potentially tainted more and more, much
- like the result of making a copy of a copy (of a copy …)
+ like the result of making a copy of a copy (of a copy…)
of a favorite audio or video cassette.</para>
<para>But the most compelling argument for binding directly to
@@ -568,7 +594,7 @@
<para>As we mentioned earlier, each directory of a Subversion
working copy contains a special subdirectory called
- <filename>.svn</filename> which houses administrative data about
+ <filename>.svn</filename> that houses administrative data about
that working copy directory. Subversion uses the information in
<filename>.svn</filename> to keep track of things like:</para>
@@ -587,7 +613,7 @@
to those files and directories.</para>
</listitem>
<listitem>
- <para>Pristine (un-edited) copies of the working copy
+ <para>Pristine (unedited) copies of the working copy
files.</para>
</listitem>
</itemizedlist>
@@ -595,14 +621,14 @@
<para>The Subversion working copy administration area's layout and
contents are considered implementation details not really
intended for human consumption. Developers are encouraged to
- use Subversion's public APIs, or the tools that Subversion provides, to access and
- manipulate the working copy data, instead of directly reading
- or modifying those files. The file formats employed by the working
- copy library for its administrative data do change from time to
- time—a fact that the public APIs do a great job of
- hiding from the average user. In this section, we
- expose some of these implementation details sheerly to appease
- your overwhelming curiosity.</para>
+ use Subversion's public APIs, or the tools that Subversion
+ provides, to access and manipulate the working copy data,
+ instead of directly reading or modifying those files. The file
+ formats employed by the working copy library for its
+ administrative data do change from time to time—a fact
+ that the public APIs do a great job of hiding from the average
+ user. In this section, we expose some of these implementation
+ details sheerly to appease your overwhelming curiosity.</para>
<!-- =============================================================== -->
<sect2 id="svn.developer.insidewc.entries">
@@ -613,7 +639,7 @@
<filename>entries</filename> file. It
contains the bulk of the administrative
information about the versioned items in a working copy
- directory. It is this one file which tracks the repository
+ directory. It is this one file that tracks the repository
URLs, pristine revision, file checksums, pristine text and
property timestamps, scheduling and conflict state
information, last-known commit information (author, revision,
@@ -635,10 +661,10 @@
Subversion who were frequently debugging the file's contents
(and Subversion's behavior in light of them), the need for
easy developer debugging has diminished as Subversion has
- matured, and has been replaced by the user's need for snappier
+ matured and has been replaced by the user's need for snappier
performance. Be aware that Subversion's working copy library
automatically upgrades working copies from one format to
- another—it reads the old formats, and writes the
+ another—it reads the old formats and writes the
new—which saves you the hassle of checking out a new
working copy, but can also complicate situations where
different versions of Subversion might be trying to use the
@@ -656,12 +682,12 @@
<filename>.svn/text-base</filename>. The benefits of these
pristine copies are multiple—network-free checks for
local modifications and difference reporting, network-free
- reversion of modified or missing files, more efficient transmission
- of changes to the server—but comes at the cost of having
- each versioned file stored at least twice on disk. These
- days, this seems to be a negligible penalty for most files.
- However, the situation gets uglier as the size of your
- versioned files grows. Some attention is being given to
+ reversion of modified or missing files, more efficient
+ transmission of changes to the server—but comes at the
+ cost of having each versioned file stored at least twice on
+ disk. These days, this seems to be a negligible penalty for
+ most files. However, the situation gets uglier as the size of
+ your versioned files grows. Some attention is being given to
making the presence of the <quote>text-base</quote> an option.
Ironically though, it is as your versioned files' sizes get
larger that the existence of the <quote>text-base</quote>
@@ -674,7 +700,7 @@
<quote>prop-base</quote> copies, located in
<filename>.svn/props</filename> and
<filename>.svn/prop-base</filename> respectively. Since
- directories can have properties, too, there are also
+ directories can have properties too, there are also
<filename>.svn/dir-props</filename> and
<filename>.svn/dir-prop-base</filename> files.</para>
@@ -690,41 +716,41 @@
<para>Developing applications against the Subversion library APIs
is fairly straightforward. Subversion is primarily a set of C
- libraries, with header (.h) files that live in the
- <filename>subversion/include</filename> directory of the source
- tree. These headers are copied into your system locations (for
- example, <filename>/usr/local/include</filename>) when you build
- and install Subversion itself from source. These headers
- represent the entirety of the functions and types meant to be
- accessible by users of the Subversion libraries. The Subversion
- developer community is meticulous about ensuring that the public
- API is well-documented—refer directly to the header files
- for that documentation.</para>
+ libraries, with header (<filename>.h</filename>) files that live
+ in the <filename>subversion/include</filename> directory of the
+ source tree. These headers are copied into your system
+ locations (for example, <filename>/usr/local/include</filename>)
+ when you build and install Subversion itself from source. These
+ headers represent the entirety of the functions and types meant
+ to be accessible by users of the Subversion libraries. The
+ Subversion developer community is meticulous about ensuring that
+ the public API is well-documented—refer directly to the
+ header files for that documentation.</para>
<para>When examining the public header files, the first thing you
might notice is that Subversion's datatypes and functions are
- namespace protected. That is, every public Subversion symbol name begins
- with <literal>svn_</literal>, followed by a short code for the
- library in which the symbol is defined (such as
+ namespace-protected. That is, every public Subversion symbol
+ name begins with <literal>svn_</literal>, followed by a short
+ code for the library in which the symbol is defined (such as
<literal>wc</literal>, <literal>client</literal>,
<literal>fs</literal>, etc.), followed by a single underscore
- (<literal>_</literal>) and then the rest of the symbol name.
+ (<literal>_</literal>), and then the rest of the symbol name.
Semi-public functions (used among source files of a given
library but not by code outside that library, and found inside
the library directories themselves) differ from this naming
scheme in that instead of a single underscore after the library
- code, they use a double underscore (<literal>__</literal>).
- Functions that are private to a given source file have no
- special prefixing, and are declared <literal>static</literal>.
- Of course, a compiler isn't interested in these naming
- conventions, but they help to clarify the scope of a given
- function or datatype.</para>
+ code, they use a double underscore
+ (<literal>_ _</literal>). Functions that are private to
+ a given source file have no special prefixing and are declared
+ <literal>static</literal>. Of course, a compiler isn't
+ interested in these naming conventions, but they help to clarify
+ the scope of a given function or datatype.</para>
<para>Another good source of information about programming against
the Subversion APIs is the project's own hacking guidelines,
which can be found at <ulink
url="http://subversion.tigris.org/hacking.html" />. This
- document contains useful information which, while aimed at
+ document contains useful information, which, while aimed at
developers and would-be developers of Subversion itself, is
equally applicable to folks developing against Subversion as a
set of third-party libraries.
@@ -752,8 +778,8 @@
well. This means that there is practically no OS-specific
code in Subversion itself. Also, it means that the Subversion
client compiles and runs anywhere that Apache HTTP Server
- itself does. Currently this list includes all flavors of
- Unix, Win32, BeOS, OS/2, and Mac OS X.</para>
+ does. Currently this list includes all flavors of Unix,
+ Win32, BeOS, OS/2, and Mac OS X.</para>
<para>In addition to providing consistent implementations of
system calls that differ across operating systems,
@@ -766,22 +792,22 @@
uses these types extensively. But
perhaps the most pervasive APR datatype, found in nearly every
Subversion API prototype, is the
- <structname>apr_pool_t</structname>—the APR memory pool.
+ <literal>apr_pool_t</literal>—the APR memory pool.
Subversion uses pools internally for all its memory allocation
needs (unless an external library requires a different memory
management mechanism for data passed through its API),
<footnote>
<para>Neon and Berkeley DB are examples of such libraries.</para>
</footnote>
- and while a person coding against the Subversion APIs is
- not required to do the same, they <emphasis>are</emphasis> required to provide
- pools to the API functions that need them. This means that
- users of the Subversion API must also link against APR, must
- call <function>apr_initialize()</function> to initialize the
- APR subsystem, and then must create and manage pools for use with
- Subversion API calls, typically by using
- <function>svn_pool_create()</function>,
- <function>svn_pool_clear()</function>, and
+ and while a person coding against the Subversion APIs is not
+ required to do the same, they <emphasis>are</emphasis>
+ required to provide pools to the API functions that need them.
+ This means that users of the Subversion API must also link
+ against APR, must call <function>apr_initialize()</function>
+ to initialize the APR subsystem, and then must create and
+ manage pools for use with Subversion API calls, typically by
+ using <function>svn_pool_create()</function>,
+ <function>svn_pool_clear()</function>, and
<function>svn_pool_destroy()</function>.</para>
<sidebar>
@@ -796,32 +822,31 @@
can result in a program that crashes itself, or worse,
crashes the computer.</para>
- <para>Higher-level languages, on the other hand, take the job of
- memory management away from the developer completely.
- <footnote>
- <para>Or at least make it something you only toy with when
- doing extremely tight program optimization.</para>
- </footnote>
- Languages like Java and Python use <firstterm>garbage
- collection</firstterm>, allocating memory for
- objects when needed, and automatically freeing that memory
- when the object is no longer in use.</para>
-
- <para>APR provides a middle-ground approach called pool-based
- memory management. It allows the developer to control
- memory usage at a lower resolution—per chunk (or
- <quote>pool</quote>) of memory, instead of per allocated
- object. Rather than using <function>malloc()</function> and
- friends to allocate enough memory for a given object, you
- ask APR to allocate the memory from a memory pool. When
- you're finished using the objects you've created in the
- pool, you destroy the entire pool, effectively de-allocating the
- memory consumed by <emphasis>all</emphasis> the objects you allocated from it.
- Thus, rather than keeping track of individual objects which need
- to be de-allocated, your program simply considers the
- general lifetimes of those objects, and allocates the
- objects in a pool whose lifetime (the time between the
- pool's creation and its deletion) matches the object's
+ <para>Higher-level languages, on the other hand, either take
+ the job of memory management away from you completely or
+ make it something you toy with only when doing extremely
+ tight program optimization. Languages such as Java and
+ Python use <firstterm>garbage collection</firstterm>,
+ allocating memory for objects when needed, and automatically
+ freeing that memory when the object is no longer in
+ use.</para>
+
+ <para>APR provides a middle-ground approach called
+ <firstterm>pool-based memory management</firstterm>. It
+ allows the developer to control memory usage at a lower
+ resolution—per chunk (or <quote>pool</quote>) of
+ memory, instead of per allocated object. Rather than using
+ <function>malloc()</function> and friends to allocate enough
+ memory for a given object, you ask APR to allocate the
+ memory from a memory pool. When you're finished using the
+ objects you've created in the pool, you destroy the entire
+ pool, effectively de-allocating the memory consumed by
+ <emphasis>all</emphasis> the objects you allocated from it.
+ Thus, rather than keeping track of individual objects that
+ need to be de-allocated, your program simply considers the
+ general lifetimes of those objects and allocates the objects
+ in a pool whose lifetime (the time between the pool's
+ creation and its deletion) matches the object's
needs.</para>
</sidebar>
@@ -835,24 +860,27 @@
of Subversion's existence, it makes sense that some attention
has been paid to internationalization (i18n) support. After
all, while <quote>remote</quote> might mean <quote>across the
- office</quote>, it could just as well mean <quote>across the
+ office,</quote> it could just as well mean <quote>across the
globe.</quote> To facilitate this, all of Subversion's public
interfaces that accept path arguments expect those paths to be
- canonicalized, and encoded in UTF-8. This means, for example,
- that any new client binary that drives the libsvn_client
- interface needs to first convert paths from the
- locale-specific encoding to UTF-8 before passing those paths
- to the Subversion libraries, and then re-convert any resultant
- output paths from Subversion back into the locale's encoding
- before using those paths for non-Subversion purposes.
- Fortunately, Subversion provides a suite of functions (see
+ canonicalized—which is most easily accomplished by passing
+ them through the <function>svn_path_canonicalize()</function>
+ function—and encoded in UTF-8. This means, for example, that
+ any new client binary that drives the
+ <filename>libsvn_client</filename> interface needs to first
+ convert paths from the locale-specific encoding to UTF-8
+ before passing those paths to the Subversion libraries, and
+ then re-convert any resultant output paths from Subversion
+ back into the locale's encoding before using those paths for
+ non-Subversion purposes. Fortunately, Subversion provides a
+ suite of functions (see
<filename>subversion/include/svn_utf.h</filename>) that can be
used by any program to do these conversions.</para>
<para>Also, Subversion APIs require all URL parameters to be
properly URI-encoded. So, instead of passing
<uri>file:///home/username/My File.txt</uri> as the URL of a
- file named <literal>My File.txt</literal>, you need to pass
+ file named <filename>My File.txt</filename>, you need to pass
<uri>file:///home/username/My%20File.txt</uri>. Again,
Subversion supplies helper functions that your application can
use—<function>svn_path_uri_encode()</function> and
@@ -883,7 +911,7 @@
among others). However, some extra programming is required to
compensate for complex APIs that SWIG needs some help
translating between languages. For more information on SWIG
- itself, see the project's website at <ulink
+ itself, see the project's web site at <ulink
url="http://www.swig.org/"/>.</para>
<para>Subversion also has language bindings for Java. The
@@ -891,21 +919,21 @@
<filename>subversion/bindings/java</filename> in the
Subversion source tree) aren't SWIG-based, but are instead a
mixture of Java and hand-coded JNI. Javahl covers most
- Subversion client-side APIs, and is specifically targeted at
+ Subversion client-side APIs and is specifically targeted at
implementors of Java-based Subversion clients and IDE
integrations.</para>
<para>Subversion's language bindings tend to lack the level of
developer attention given to the core Subversion modules, but
can generally be trusted as production-ready. A number of
- scripts and applications, alternative Subversion GUI clients
+ scripts and applications, alternative Subversion GUI clients,
and other third-party tools are successfully using
Subversion's language bindings today to accomplish their
Subversion integrations.</para>
<para>It's worth noting here that there are other options for
interfacing with Subversion using other languages: alternative
- bindings for Subversion which aren't provided by the
+ bindings for Subversion that aren't provided by the
Subversion development community at all. You can find links
to these alternative bindings on the Subversion project's
links page (at <ulink
@@ -921,7 +949,7 @@
from the ground up in Java.</para>
<sidebar>
- <title>SVNKit vs. javahl</title>
+ <title>SVNKit versus javahl</title>
<para>In 2005, a small company called TMate announced the
1.0.0 release of JavaSVN—a pure Java implementation of
@@ -939,18 +967,17 @@
realize which of these libraries you are using, folks should
be aware that SVNKit differs from javahl in some significant
ways. First, SVNKit is not developed as open source
- software, and seems to have at any given time only a few
+ software and seems to have at any given time only a few
developers working on it. Also, SVNKit's license is more
restrictive than that of Subversion. Finally, by aiming to
be a pure Java Subversion library, SVNKit is limited in
which portions of Subversion can be reasonably cloned while
still keeping up with Subversion's releases. This has
- already happened once—SVNKit cannot access
- Berkeley-DB-backed Subversion repositories via the
- <literal>file://</literal> protocol because there's no pure
- Java implementation of Berkeley DB that is file format
- compatible with the native implementation of that
- library.</para>
+ already happened once—SVNKit cannot access BDB-backed
+ Subversion repositories via the <literal>file://</literal>
+ protocol because there's no pure Java implementation of
+ Berkeley DB that is file format-compatible with the native
+ implementation of that library.</para>
<para>That said, SVNKit has a well-established track record of
reliability. And a pure Java solution is much more robust
@@ -1097,11 +1124,12 @@
API knows nothing about the repository library's hook
mechanism. If you want your Subversion repository to
automatically perform some set of non-Subversion tasks every
- time you commit a transaction (like, for example, sending an
+ time you commit a transaction (for example, sending an
email that describes all the changes made in that transaction
to your developer mailing list), you need to use the
- libsvn_repos-wrapped version of that function, which adds the
- hook triggering functionality—in this case,
+ <filename>libsvn_repos</filename>-wrapped version of that
+ function, which adds the hook triggering
+ functionality—in this case,
<function>svn_repos_fs_commit_txn()</function>. (For more
information regarding Subversion's repository hooks, see <xref
linkend="svn.reposadmin.create.hooks" />.)</para>
@@ -1109,8 +1137,8 @@
<para>Now let's switch languages. <xref
linkend="svn.developer.usingapi.otherlangs.ex-1" /> is a
sample program that uses Subversion's SWIG Python bindings to
- recursively crawl the youngest repository revision, and print
- the various paths reached during the crawl.</para>
+ recursively crawl the youngest repository revision, and to
+ print the various paths reached during the crawl.</para>
<example id="svn.developer.usingapi.otherlangs.ex-1">
<title>Using the Repository Layer with Python</title>
@@ -1189,7 +1217,7 @@
(such as those provided by the APR library) for representing
the hash of entries and the list of paths, but Python has
hashes (called <quote>dictionaries</quote>) and lists as
- built-in datatypes, and provides a rich collection of
+ built-in datatypes, and it provides a rich collection of
functions for operating on those types. So SWIG (with the
help of some customizations in Subversion's language bindings
layer) takes care of mapping those custom datatypes into the
@@ -1199,7 +1227,7 @@
<para>The Subversion Python bindings can be used for working
copy operations, too. In the previous section of this
chapter, we mentioned the <filename>libsvn_client</filename>
- interface, and how it exists for the sole purpose of
+ interface and how it exists for the sole purpose of
simplifying the process of writing a Subversion client. <xref
linkend="svn.developer.usingapi.otherlangs.ex-2" /> is a brief
example of how that library can be accessed via the SWIG
@@ -1207,7 +1235,7 @@
<command>svn status</command> command.</para>
<example id="svn.developer.usingapi.otherlangs.ex-2">
- <title>A Python Status Crawler</title>
+ <title>A Python status crawler</title>
<programlisting>
#!/usr/bin/env python
@@ -1310,7 +1338,7 @@
<function>svn_path_canonicalize()</function>, because to
<emphasis>not</emphasis> do so runs the risk of triggering the
underlying Subversion C library's assertions about such
- things, which translate into rather immediate and
+ things, which translates into rather immediate and
unceremonious program abortion.</para>
</sect2>
Modified: trunk/src/de/book/styles.css
==============================================================================
--- trunk/src/de/book/styles.css (original)
+++ trunk/src/de/book/styles.css Mon Apr 7 15:06:30 2008
@@ -2,6 +2,17 @@
/* Custom style-sheet stuffs for the Subversion book in HTML form. */
/************************************************************************/
+/*
+ * Copyright (c) 2003-2008
+ * Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato.
+ *
+ * This work is licensed under the Creative Commons Attribution License.
+ * To view a copy of this license, visit
+ * http://creativecommons.org/licenses/by/2.0/ or send a letter to
+ * Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305,
+ * USA.
+ */
+
body
{
background: white;
@@ -223,3 +234,14 @@
{
display: none;
}
+
+#svn-footer
+{
+ font-size: 80%;
+ text-align: center;
+}
+
+#svn-footer hr
+{
+ display: none;
+}
More information about the svnbook-dev
mailing list