[svnbook commit] r3058 - trunk/src/de/book
khmarbaise
noreply at red-bean.com
Sun May 4 06:57:33 CDT 2008
Author: khmarbaise
Date: Sun May 4 06:57:32 2008
New Revision: 3058
Log:
src/de/book/ch00-preface.xml
src/de/book/ch02-basic-usage.xml
src/de/book/ch03-advanced-topics.xml
src/de/book/ch04-branching-and-merging.xml
src/de/book/ch06-server-configuration.xml
src/de/book/ch07-customizing-svn.xm
src/de/book/ch09-reference.xml
src/de/book/appa-quickstart.xml
src/de/book/appb-svn-for-cvs-users.xml
- merged the changes from the english book into
current translation area.
/trunk/src/en/book (r3029-3055).
Modified:
trunk/src/de/book/appa-quickstart.xml
trunk/src/de/book/appb-svn-for-cvs-users.xml
trunk/src/de/book/ch00-preface.xml
trunk/src/de/book/ch02-basic-usage.xml
trunk/src/de/book/ch03-advanced-topics.xml
trunk/src/de/book/ch04-branching-and-merging.xml
trunk/src/de/book/ch06-server-configuration.xml
trunk/src/de/book/ch07-customizing-svn.xml
trunk/src/de/book/ch09-reference.xml
Modified: trunk/src/de/book/appa-quickstart.xml
==============================================================================
--- trunk/src/de/book/appa-quickstart.xml (original)
+++ trunk/src/de/book/appa-quickstart.xml Sun May 4 06:57:32 2008
@@ -81,7 +81,8 @@
subdirectory thereof called <literal>trunk</literal>. See
our discussion of Subversion's branching and tagging model
for the reasoning behind this.</para>
- </footnote></para>
+ </footnote>
+ </para>
<screen>
$ svn checkout http://svn.collab.net/repos/svn/trunk subversion
Modified: trunk/src/de/book/appb-svn-for-cvs-users.xml
==============================================================================
--- trunk/src/de/book/appb-svn-for-cvs-users.xml (original)
+++ trunk/src/de/book/appb-svn-for-cvs-users.xml Sun May 4 06:57:32 2008
@@ -363,10 +363,12 @@
(<literal>http://svn.example.com/repos/calc/</literal>). If
you make the mistake of checking out the project itself,
you'll wind up with a working copy that contains a copy of
- your project for every branch and tag you
- have.<footnote><para>That is, providing you don't run out of
- disk space before your checkout
- finishes.</para></footnote></para>
+ your project for every branch and tag you have.
+ <footnote>
+ <para>That is, providing you don't run out of disk space
+ before your checkout finishes.</para>
+ </footnote>
+ </para>
</warning>
</sect1>
Modified: trunk/src/de/book/ch00-preface.xml
==============================================================================
--- trunk/src/de/book/ch00-preface.xml (original)
+++ trunk/src/de/book/ch00-preface.xml Sun May 4 06:57:32 2008
@@ -838,9 +838,12 @@
a risky and ambitious new Open Source project; Jim Blandy for
the original Subversion name and design—we love you, Jim;
Karl Fogel for being such a good friend and a great community
- leader, in that order.<footnote><para>Oh, and thanks, Karl, for
- being too overworked to write this book yourself.</para>
- </footnote></para>
+ leader, in that order.
+ <footnote>
+ <para>Oh, and thanks, Karl, for being too overworked to write
+ this book yourself.</para>
+ </footnote>
+ </para>
-->
<para>Dieses Buch wäre nicht möglich (und auch nicht sehr
@@ -1265,10 +1268,12 @@
packages. The problem is, this sort of data usually isn't
changing at all. The collection itself grows over time, but
the individual files within the collection aren't being
- changed. In this case, using Subversion is
- "overkill".<footnote><para>Or as a friend puts
- it, <quote>swatting a fly with a
- Buick.</quote></para></footnote> There are simpler tools that
+ changed. In this case, using Subversion is "overkill".
+ <footnote>
+ <para>Or as a friend puts it, <quote>swatting a fly with a
+ Buick.</quote></para>
+ </footnote>
+ There are simpler tools that
efficiently replicate data <emphasis>without</emphasis> the
overhead of tracking changes, such as <command>rsync</command>
or <command>unison</command>.</para>
Modified: trunk/src/de/book/ch02-basic-usage.xml
==============================================================================
--- trunk/src/de/book/ch02-basic-usage.xml (original)
+++ trunk/src/de/book/ch02-basic-usage.xml Sun May 4 06:57:32 2008
@@ -13,7 +13,7 @@
<para>Note that this chapter is not meant to be an exhaustive list
of all Subversion's commands—rather, it's a conversational
- introduction to the most common Subversion tasks you'll
+ introduction to the most common Subversion tasks that you'll
encounter. This chapter assumes that you've read and understood
<xref linkend="svn.basic"/> and are familiar with the general
model of Subversion. For a complete reference of all commands,
@@ -57,12 +57,12 @@
<sidebar>
<title>Options and Switches and Flags, Oh My!</title>
- <para>The Subversion command line client has numerous command
+ <para>The Subversion command-line client has numerous command
modifiers (which we call options), but there are two
- distinct kinds of options—<quote>short options</quote>
- that are a single hyphen followed by a single letter, and
- <quote>long options</quote> that consist of two hyphens
- followed by a number of letters (eg <literal>-s</literal>
+ distinct kinds of options: short options>
+ are a single hyphen followed by a single letter, and
+ long options consist of two hyphens
+ followed by a number of letters (e.g. <literal>-s</literal>
and <literal>--this-is-a-long-option</literal>
respectively). Every option has a long format, but only
certain options have an additional short format (these are
@@ -82,13 +82,13 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.tour.importing">
- <title>Getting Data into your Repository</title>
+ <title>Getting Data into Your Repository</title>
<para>There are two ways to get new files into your Subversion
repository: <command>svn import</command> and <command>svn
- add</command>. We'll discuss <command>svn import</command> here
- and <command>svn add</command> later in this chapter when we
- review a typical day with Subversion.</para>
+ add</command>. We'll discuss <command>svn import</command> now
+ and will discuss <command>svn add</command> later in this
+ chapter when we review a typical day with Subversion.</para>
<!-- =============================================================== -->
<sect2 id="svn.tour.importing.import">
@@ -134,15 +134,15 @@
<!-- =============================================================== -->
<sect2 id="svn.tour.importing.layout">
- <title>Recommended repository layout</title>
+ <title>Recommended Repository Layout</title>
- <para>While Subversion's flexibility allows you to layout your
+ <para>While Subversion's flexibility allows you to lay out your
repository in any way that you choose, we recommend that you
create a <filename>trunk</filename> directory to hold the
<quote>main line</quote> of development, a
<filename>branches</filename> directory to contain branch
copies, and a <filename>tags</filename> directory to contain tag
- copies, for example:</para>
+ copies—for example:</para>
<screen>
$ svn list file:///var/svn/repos
@@ -156,7 +156,7 @@
multiple projects, see <xref
linkend="svn.branchmerge.maint.layout"/> and <xref
linkend="svn.reposadmin.projects.chooselayout"/> to read more
- about <quote>project roots</quote>.</para>
+ about project roots.</para>
</sect2>
@@ -202,7 +202,7 @@
<para>Subversion internally handles certain bits of
data—for example, property names, path names, and log
- messages—as UTF-8 encoded Unicode. This is not to say
+ messages—as UTF-8-encoded Unicode. This is not to say
that all your interactions with Subversion must involve UTF-8,
though. As a general rule, Subversion clients will gracefully
and transparently handle conversions between UTF-8 and the
@@ -212,22 +212,22 @@
<para>In addition, path names are used as XML attribute values
in WebDAV exchanges, as well in as some of Subversion's
- housekeeping files. This means that path names can only
- contain legal XML (1.0) characters. Subversion also prohibits
+ housekeeping files. This means that path names can contain
+ only legal XML (1.0) characters. Subversion also prohibits
TAB, CR, and LF characters in path names to prevent paths from
- being broken up in diffs, or in the output of commands like
- <xref linkend="svn.ref.svn.c.log"/> or <xref
- linkend="svn.ref.svn.c.status"/>.</para>
+ being broken up in diffs or in the output of commands such as
+ <command>svn log</command> or <command>svn
+ status</command>.</para>
<para>While it may seem like a lot to remember, in practice
these limitations are rarely a problem. As long as your
- locale settings are compatible with UTF-8, and you don't use
+ locale settings are compatible with UTF-8 and you don't use
control characters in path names, you should have no trouble
communicating with Subversion. The command-line client adds
- an extra bit of help—it will automatically escape illegal
- path characters as needed in URLs you type to create
+ an extra bit of help—in order to create
<quote>legally correct</quote> versions for internal
- use.</para>
+ use it will automatically escape illegal
+ path characters as needed in URLs that you type.</para>
</sidebar>
@@ -249,17 +249,17 @@
</screen>
<para>Since Subversion uses a <quote>copy-modify-merge</quote>
- model instead of <quote>lock-modify-unlock</quote> (see <xref
- linkend="svn.basic.vsn-models"/>), you can start right in
+ model instead of <quote>lock-modify-unlock</quote> (see
+ <xref linkend="svn.basic.vsn-models"/>), you can start right in
making changes to the files and directories in your working
copy. Your working copy is just like any other collection of
files and directories on your system. You can edit and change
- them, move them around, you can even delete the entire working
- copy and forget about it.</para>
+ them, move them around, even delete the entire working copy and
+ forget about it.</para>
<warning>
<para>While your working copy is <quote>just like any other
- collection of files and directories on your system</quote>,
+ collection of files and directories on your system,</quote>
you can edit files at will, but you must tell Subversion
about <emphasis>everything else</emphasis> that you do. For
example, if you want to copy or move an item in a working
@@ -270,15 +270,15 @@
</warning>
<para>Unless you're ready to commit the addition of a new file or
- directory, or changes to existing ones, there's no need to
+ directory or changes to existing ones, there's no need to
further notify the Subversion server that you've done
anything.</para>
<sidebar>
- <title>What's with the <filename>.svn</filename> directory?</title>
+ <title>What's with the <filename>.svn</filename> Directory?</title>
<para>Every directory in a working copy contains an
- administrative area, a subdirectory named
+ administrative area—a subdirectory named
<filename>.svn</filename>. Usually, directory listing
commands won't show this subdirectory, but it is nevertheless
an important directory. Whatever you do, don't delete or
@@ -325,18 +325,21 @@
authentication credentials on disk. This is done for
convenience, so that you don't have to continually re-enter
your password for future operations. If you're concerned
- about caching your Subversion passwords,<footnote><para>Of
- course, you're not terribly worried—first because you
- know that you can't <emphasis>really</emphasis> delete
- anything from Subversion and, secondly, because your
- Subversion password isn't the same as any of the other three
- million passwords you have, right? Right?</para></footnote>
+ about caching your Subversion passwords,
+ <footnote>
+ <para>Of course, you're not terribly worried—first
+ because you know that you can't
+ <emphasis>really</emphasis> delete anything from
+ Subversion and, secondly, because your Subversion password
+ isn't the same as any of the other 3 million passwords
+ you have, right? Right?</para>
+ </footnote>
you can disable caching either permanently or on a
case-by-case basis.</para>
<para>To disable password caching for a particular one-time
command, pass the <option >--no-auth-cache</option > option on
- the commandline. To permanently disable caching, you can add
+ the command line. To permanently disable caching, you can add
the line <literal>store-passwords = no</literal> to your local
machine's Subversion configuration file. See <xref
linkend="svn.serverconfig.netmodel.credcache"/> for
@@ -351,10 +354,10 @@
username and password), it conveniently remembers who you were
acting as the last time you modified you working copy. But
sometimes that's not helpful—particularly if you're
- working in a shared working copy, like a system configuration
- directory or a webserver document root. In this case, just
- pass the <option>--username</option> option on the
- commandline and Subversion will attempt to authenticate as
+ working in a shared working copy such as a system
+ configuration directory or a webserver document root. In this
+ case, just pass the <option>--username</option> option on the
+ command line, and Subversion will attempt to authenticate as
that user, prompting you for a password if necessary.</para>
</sect2>
@@ -367,17 +370,17 @@
<sect1 id="svn.tour.cycle">
<title>Basic Work Cycle</title>
- <para>Subversion has numerous features, options, bells and
+ <para>Subversion has numerous features, options, bells, and
whistles, but on a day-to-day basis, odds are that you will only
- use a few of them. In this section we'll run through the most
+ use a few of them. In this section, we'll run through the most
common things that you might find yourself doing with Subversion
in the course of a day's work.</para>
<para>The typical work cycle looks like this:</para>
- <itemizedlist>
+ <orderedlist>
<listitem>
- <para>Update your working copy</para>
+ <para>Update your working copy.</para>
<itemizedlist>
<listitem>
<para><command>svn update</command></para>
@@ -387,7 +390,7 @@
</listitem>
<listitem>
- <para>Make changes</para>
+ <para>Make changes.</para>
<itemizedlist>
<listitem>
<para><command>svn add</command></para>
@@ -405,7 +408,7 @@
</listitem>
<listitem>
- <para>Examine your changes</para>
+ <para>Examine your changes.</para>
<itemizedlist>
<listitem>
<para><command>svn status</command></para>
@@ -417,7 +420,7 @@
</listitem>
<listitem>
- <para>Possibly undo some changes</para>
+ <para>Possibly undo some changes.</para>
<itemizedlist>
<listitem>
<para><command>svn revert</command></para>
@@ -427,7 +430,7 @@
<listitem>
- <para>Resolve Conflicts (Merge Others' Changes)</para>
+ <para>Resolve conflicts (merge others' changes).</para>
<itemizedlist>
<listitem>
<para><command>svn update</command></para>
@@ -439,14 +442,14 @@
</listitem>
<listitem>
- <para>Commit your changes</para>
+ <para>Commit your changes.</para>
<itemizedlist>
<listitem>
<para><command>svn commit</command></para>
</listitem>
</itemizedlist>
</listitem>
- </itemizedlist>
+ </orderedlist>
<!-- =============================================================== -->
<sect2 id="svn.tour.cycle.update">
@@ -456,7 +459,7 @@
update your working copy to receive any changes made since
your last update by other developers on the project. Use
<command>svn update</command> to bring your working copy into
- sync with the latest revision in the repository.</para>
+ sync with the latest revision in the repository:</para>
<screen>
$ svn update
@@ -474,8 +477,7 @@
<command>svn update</command>, a letter code is displayed next
to each item to let you know what actions Subversion performed
to bring your working copy up-to-date. To find out what these
- letters mean, see <xref linkend
- ="svn.ref.svn.c.update"/>.</para>
+ letters mean, see <command>svn update</command>.</para>
</sect2>
@@ -495,12 +497,13 @@
commit.</para>
<para>There are two kinds of changes you can make to your
- working copy: file changes and tree changes. You don't need
- to tell Subversion that you intend to change a file; just make
+ working copy: <firstterm>file changes</firstterm>
+ and <firstterm>tree changes</firstterm>. You don't need to
+ tell Subversion that you intend to change a file; just make
your changes using your text editor, word processor, graphics
program, or whatever tool you would normally use. Subversion
automatically detects which files have been changed, and in
- addition handles binary files just as easily as it handles
+ addition, handles binary files just as easily as it handles
text files—and just as efficiently too. For tree
changes, you can ask Subversion to <quote>mark</quote> files
and directories for scheduled removal, addition, copying, or
@@ -508,16 +511,13 @@
working copy, but no additions or removals will happen in the
repository until you commit them.</para>
- <para>Here is an overview of the five Subversion subcommands
- that you'll use most often to make tree changes.</para>
-
<sidebar>
- <title>Versioning symbolic links</title>
+ <title>Versioning Symbolic Links</title>
<para>On non-Windows platforms, Subversion is able to version
files of the special type <firstterm>symbolic
- link</firstterm> (or, <quote>symlink</quote>). A symlink is
- a file which acts as a sort of transparent reference to some
+ link</firstterm> (or <quote>symlink</quote>). A symlink is
+ a file that acts as a sort of transparent reference to some
other object in the filesystem, allowing programs to read
and write to those objects indirectly by way of performing
operations on the symlink itself.</para>
@@ -525,11 +525,11 @@
<para>When a symlink is committed into a Subversion
repository, Subversion remembers that the file was in fact a
symlink, as well as the object to which the symlink
- <quote>points</quote>. When that symlink is checked out to
+ <quote>points.</quote> When that symlink is checked out to
another working copy on a non-Windows system, Subversion
reconstructs a real filesystem-level symbolic link from the
versioned symlink. But that doesn't in any way limit the
- usability of working copies on systems such as Windows which
+ usability of working copies on systems such as Windows that
do not support symlinks. On such systems, Subversion simply
creates a regular text file whose contents are the path to
which to the original symlink pointed. While that file
@@ -537,6 +537,9 @@
won't prevent Windows users from performing their other
Subversion-related activities.</para> </sidebar>
+ <para>Here is an overview of the five Subversion subcommands
+ that you'll use most often to make tree changes.</para>
+
<variablelist>
<varlistentry>
@@ -548,7 +551,7 @@
become a child of its parent directory. Note that if
<filename>foo</filename> is a directory, everything
underneath <filename>foo</filename> will be scheduled
- for addition. If you only want to add
+ for addition. If you want only to add
<filename>foo</filename> itself, pass the
<option>--non-recursive</option> (<option>-N</option>)
option.</para>
@@ -567,14 +570,17 @@
you commit your changes, <filename>foo</filename> will
be entirely removed from your working copy and the
repository.
- <footnote><para>Of course, nothing is ever totally
- deleted from the repository—just from the
- <literal>HEAD</literal> of the repository. You can get
- back anything you delete by checking out (or updating
- your working copy to) a revision earlier than the one in
- which you deleted it. Also see
- <xref linkend="svn.branchmerge.advanced.resurrect"/>.
- </para></footnote></para>
+ <footnote>
+ <para>Of course, nothing is ever totally deleted from
+ the repository—just from the
+ <literal>HEAD</literal> of the repository. You can
+ get back anything you delete by checking out (or
+ updating your working copy to) a revision earlier
+ than the one in which you deleted it. Also see <xref
+ linkend="svn.branchmerge.advanced.resurrect"
+ />.</para>
+ </footnote>
+ </para>
</listitem>
</varlistentry>
@@ -624,11 +630,11 @@
<para>There <emphasis>are</emphasis> some use cases that
immediately commit tree changes to the repository. This
- only happens when a subcommand is operating directly on a
+ happens only when a subcommand is operating directly on a
URL, rather than on a working-copy path. In particular,
specific uses of <command>svn mkdir</command>, <command>svn
copy</command>, <command>svn move</command>, and
- <command>svn delete</command> can work with URLs (And don't
+ <command>svn delete</command> can work with URLs (and don't
forget that <command>svn import</command> always makes
changes to a URL).</para>
@@ -671,9 +677,12 @@
network. This makes it easy to manage your
changes-in-progress when you are somewhere without a network
connection, such as travelling on an airplane, riding a
- commuter train or hacking on the beach.<footnote><para>And
- also that you don't have a WAN card. Thought you got us,
- huh?</para></footnote></para>
+ commuter train, or hacking on the beach.
+ <footnote>
+ <para>And also that you don't have a WAN card. Thought
+ you got us, huh?</para>
+ </footnote>
+ </para>
<para>Subversion does this by keeping private caches of
pristine versions of each versioned file inside of the
@@ -693,12 +702,12 @@
</sidebar>
<para>Subversion has been optimized to help you with this task,
- and is able to do many things without communicating with the
- repository. In particular, your working copy contains a
+ and it is able to do many things without communicating with
+ the repository. In particular, your working copy contains a
hidden cached <quote>pristine</quote> copy of each version
controlled file within the <filename>.svn</filename> area.
Because of this, Subversion can quickly show you how your
- working files have changed, or even allow you to undo your
+ working files have changed or even allow you to undo your
changes without contacting the repository.</para>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
@@ -745,7 +754,7 @@
M bar.c # the content in bar.c has local modifications
</screen>
- <para>In this output format <command>svn status</command>
+ <para>In this output format, <command>svn status</command>
prints six columns of characters, followed by several
whitespace characters, followed by a file or directory name.
The first column tells the status of a file or directory
@@ -827,7 +836,7 @@
<para>This is the <quote>long form</quote> output of
<command>svn status</command>. The letters in the first
column mean the same as before, but the second column shows
- the working-revision of the item. The third and fourth
+ the working revision of the item. The third and fourth
columns show the revision in which the item last changed,
and who changed it.</para>
@@ -837,7 +846,7 @@
directory with the working copy. Finally, there is the
<option>--show-updates</option> (<option>-u</option>)
option, which contacts the repository and adds information
- about things that are out-of-date:</para>
+ about things that are out of date:</para>
<screen>
$ svn status -u -v
@@ -856,13 +865,13 @@
useful information—you'll need to update and get the
server changes on <filename>README</filename> before you
commit, or the repository will reject your commit for being
- out-of-date. (More on this subject later.)</para>
+ out of date. (more on this subject later).</para>
<para><command>svn status</command> can display much more
information about the files and directories in your
working copy than we've shown here—for an exhaustive
- description of svn status and its output, see <xref
- linkend="svn.ref.svn.c.status"/>.</para>
+ description of <command>svn status</command> and its
+ output, see <xref linkend="svn.ref.svn.c.status"/>.</para>
</sect3>
@@ -922,12 +931,12 @@
output by comparing your working files against the cached
<quote>pristine</quote> copies within the
<filename>.svn</filename> area. Files scheduled for
- addition are displayed as all added-text, and files
+ addition are displayed as all added text, and files
scheduled for deletion are displayed as all deleted
text.</para>
<para>Output is displayed in unified diff format. That is,
- removed lines are prefaced with <literal>-</literal> and
+ removed lines are prefaced with <literal>-</literal>, and
added lines are prefaced with
<literal>+</literal>. <command>svn diff</command> also
prints filename and offset information useful to the
@@ -977,7 +986,7 @@
Reverted 'README'
</screen>
- <para>Subversion reverts the file to its pre-modified state by
+ <para>Subversion reverts the file to its premodified state by
overwriting it with the cached <quote>pristine</quote> copy
from the <filename>.svn</filename> area. But also note that
<command>svn revert</command> can undo
@@ -1059,11 +1068,12 @@
changes.</para>
<para>But the next line is part of a feature new in Subversion
- 1.5 called interactive conflict resolution. This means that
- the changes from the server overlapped with your own, and you
- have the opportunity to resolve this conflict. The most
- commonly used options are displayed, but you can see all of
- the options by typing <replaceable>h</replaceable>: </para>
+ 1.5 called <firstterm>interactive conflict
+ resolution</firstterm>. This means that the changes from the
+ server overlapped with your own, and you have the opportunity
+ to resolve this conflict. The most commonly used options are
+ displayed, but you can see all of the options by
+ typing <replaceable>h</replaceable>:</para>
<screen>
...
@@ -1085,8 +1095,8 @@
<term><computeroutput>(p)ostpone</computeroutput></term>
<listitem>
- <para>Leaves the file in a conflicted state for you to
- resolve after your update is complete.</para>
+ <para>Leave the file in a conflicted state for you to
+ resolve after your update is complete.</para>
</listitem>
</varlistentry>
@@ -1098,7 +1108,7 @@
<listitem>
<para>Display the differences between the base revision
- and the conflicted file itself in unified diff format.</para>
+ and the conflicted file itself in unified diff format.</para>
</listitem>
</varlistentry>
@@ -1120,7 +1130,7 @@
<term><computeroutput>(r)esolved</computeroutput></term>
<listitem>
- <para>After editing a file, choosing this command tells
+ <para>After editing a file, tell
<command>svn</command> that you've resolved the
conflicts in the file and that it should accept the
current contents—basically that you've
@@ -1165,7 +1175,7 @@
<term><computeroutput>(h)elp</computeroutput></term>
<listitem>
- <para>Shows the list of all possible commands you can use
+ <para>Show the list of all possible commands you can use
in interactive conflict resolution.</para>
</listitem>
@@ -1180,12 +1190,12 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.cycle.resolve.diff">
- <title>Viewing Conflict Differences Interactively</title>
+ <title>Viewing conflict differences interactively</title>
<para>Before deciding how to attack a conflict interactively,
odds are that you'd like to see what exactly is in conflict,
- and the diff command (<command>d</command>) is what you'll
- use for this:</para>
+ and the <firstterm>diff</firstterm> command
+ (<command>d</command>) is what you'll use for this:</para>
<screen>
...
@@ -1195,7 +1205,7 @@
@@ -1 +1,5 @@
-Just buy a sandwich.
+<<<<<<< .mine
-+Go pickup a cheesesteak.
++Go pick up a cheesesteak.
+=======
+Bring me a taco!
+>>>>>>> .r32
@@ -1215,7 +1225,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.cycle.resolve.resolve">
- <title>Resolving Conflict Differences Interactively</title>
+ <title>Resolving conflict differences interactively</title>
<para>There are four different ways to resolve conflicts
interactively—two of which allow you to selectively
@@ -1234,7 +1244,7 @@
merge tools instead.</para>
<para>In order to use a merge tool, you need to either set the
- <literal>SVN_MERGE</literal> environment variable, or define
+ <literal>SVN_MERGE</literal> environment variable or define
the <literal>merge-tool-cmd</literal> option in your
Subversion configuration file (see <xref
linkend="svn.advanced.confarea.opts"/> for more details).
@@ -1266,7 +1276,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.cycle.resolve.pending">
- <title>Postponing Conflict Resolution</title>
+ <title>Postponing conflict resolution</title>
<para>This may sound like an appropriate section for avoiding
marital disagreements, but it's actually still about
@@ -1277,7 +1287,7 @@
<command>svn update</command>. If you're running an update
and don't want to resolve any conflicts, you can pass the
<option>--non-interactive</option> option to <command>svn
- update</command> and any file in conflict will be marked
+ update</command>, and any file in conflict will be marked
with a <computeroutput>C</computeroutput>
automatically.</para>
@@ -1294,14 +1304,14 @@
<listitem>
<para>Subversion prints a <computeroutput>C</computeroutput>
- during the update, and remembers that the file is in a
+ during the update and remembers that the file is in a
state of conflict.</para>
</listitem>
<listitem>
<para>If Subversion considers the file to be mergeable, it
places <firstterm>conflict
- markers</firstterm>—special strings of text which
+ markers</firstterm>—special strings of text that
delimit the <quote>sides</quote> of the
conflict—into the file to visibly demonstrate the
overlapping areas. (Subversion uses the
@@ -1355,7 +1365,7 @@
</variablelist>
<para>Here <literal>OLDREV</literal> is the revision number
- of the file in your <filename>.svn</filename> directory
+ of the file in your <filename>.svn</filename> directory,
and <literal>NEWREV</literal> is the revision number of
the repository <literal>HEAD</literal>.</para>
</listitem>
@@ -1409,7 +1419,7 @@
</listitem>
<listitem>
- <para>Run <command>svn revert <filename></command>
+ <para>Run <command>svn revert <FILENAME></command>
to throw away all of your local changes.</para>
</listitem>
@@ -1417,12 +1427,14 @@
<para>Once you've resolved the conflict, you need to let
Subversion know by running <command>svn resolved</command>.
- This removes the three temporary files and Subversion no
- longer considers the file to be in a state of
- conflict.<footnote><para>You can always remove the temporary
- files yourself, but would you really want to do that when
- Subversion can do it for you? We didn't think so.</para>
- </footnote></para>
+ This removes the three temporary files, and Subversion no
+ longer considers the file to be in a state of conflict.
+ <footnote>
+ <para>You can always remove the temporary files yourself,
+ but would you really want to do that when Subversion can
+ do it for you? We didn't think so.</para>
+ </footnote>
+ </para>
<screen>
$ svn resolved sandwich.txt
@@ -1433,7 +1445,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.cycle.resolve.byhand">
- <title>Merging Conflicts by Hand</title>
+ <title>Merging conflicts by hand</title>
<para>Merging conflicts by hand can be quite intimidating the
first time you attempt it, but with a little practice, it
@@ -1467,7 +1479,7 @@
</screen>
<para>The strings of less-than signs, equal signs, and
- greater-than signs are conflict markers, and are not part of
+ greater-than signs are conflict markers and are not part of
the actual data in conflict. You generally want to ensure
that those are removed from the file before your next
commit. The text between the first two sets of markers is
@@ -1497,11 +1509,13 @@
surprised when the sandwich arrives and it's not what she
wanted. So this is where you pick up the phone or walk
across the office and explain to Sally that you can't get
- sauerkraut from an Italian deli.<footnote><para>And if you
- ask them for it, they may very well ride you out of town on
- a rail.</para></footnote> Once you've agreed on the changes
- you will check in, edit your file and remove the conflict
- markers.</para>
+ sauerkraut from an Italian deli.
+ <footnote>
+ <para>And if you ask them for it, they may very well ride
+ you out of town on a rail.</para>
+ </footnote>
+ Once you've agreed on the changes you will check in, edit
+ your file and remove the conflict markers.</para>
<screen>
Top piece of bread
@@ -1526,8 +1540,8 @@
<para>Note that <command>svn resolved</command>, unlike most
of the other commands we deal with in this chapter, requires
- an argument. In any case, you want to be careful and only
- run <command>svn resolved</command> when you're certain that
+ an argument. In any case, you want to be careful and run
+ <command>svn resolved</command> only when you're certain that
you've fixed the conflict in your file—once the
temporary files are removed, Subversion will let you commit
the file even if it still contains conflict markers.</para>
@@ -1543,7 +1557,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.cycle.resolve.copyover">
- <title>Copying a File Onto Your Working File</title>
+ <title>Copying a file onto your working file</title>
<para>If you get a conflict and decide that you want to throw
out your changes, you can merely copy one of the temporary
@@ -1564,9 +1578,9 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.cycle.resolve.revert">
- <title>Punting: Using <command>svn revert</command></title>
+ <title>Punting: using <command>svn revert</command></title>
- <para>If you get a conflict, and upon examination decide that
+ <para>If you get a conflict and upon examination decide that
you want to throw out your changes and start your edits
again, just revert your changes:</para>
@@ -1627,7 +1641,6 @@
<xref linkend="svn.advanced.confarea.opts.config"/>) for composing a log
message.</para>
-
<tip>
<para>If you're in your editor writing a commit message and
decide that you want to cancel your commit, you can just
@@ -1647,17 +1660,17 @@
</tip>
<para>The repository doesn't know or care if your changes make
- any sense as a whole; it only checks to make sure that nobody
+ any sense as a whole; it checks only to make sure that nobody
else has changed any of the same files that you did when you
weren't looking. If somebody <emphasis>has</emphasis> done
that, the entire commit will fail with a message informing you
- that one or more of your files is out-of-date:</para>
+ that one or more of your files is out of date:</para>
<screen>
$ svn commit -m "Add another rule"
Sending rules.txt
svn: Commit failed (details follow):
-svn: Your file or directory 'sandwich.txt' is probably out-of-date
+svn: Your file or directory 'sandwich.txt' is probably out of date
…
</screen>
@@ -1688,14 +1701,14 @@
<title>Examining History</title>
<para>Your Subversion repository is like a time machine. It keeps
- a record of every change ever committed, and allows you to
+ a record of every change ever committed and allows you to
explore this history by examining previous versions of files and
directories as well as the metadata that accompanies them. With
a single Subversion command, you can check out the repository
(or restore an existing working copy) exactly as it was at any
date or revision number in the past. However, sometimes you
just want to <emphasis>peer into</emphasis> the past instead of
- <emphasis>going into</emphasis> the past.</para>
+ <emphasis>going into</emphasis> it.</para>
<para>There are several commands that can provide you with
historical data from the repository:</para>
@@ -1706,7 +1719,7 @@
<term><command>svn log</command></term>
<listitem>
<para>Shows you broad information: log messages with date
- and author information attached to revisions, and which
+ and author information attached to revisions and which
paths changed in each revision.</para>
</listitem>
</varlistentry>
@@ -1722,7 +1735,7 @@
<term><command>svn cat</command></term>
<listitem>
<para>Retrieves a file as it existed in a particular
- revision number and display it on your screen.</para>
+ revision number and displays it on your screen.</para>
</listitem>
</varlistentry>
@@ -1739,15 +1752,15 @@
<!-- =============================================================== -->
<sect2 id="svn.tour.history.log">
- <title>Generating a list of historical changes</title>
+ <title>Generating a List of Historical Changes</title>
<para>To find information about the history of a file or
directory, use the <command>svn log</command>
command. <command>svn log</command> will provide you with a
record of who made changes to a file or directory, at what
- revision it changed, the time and date of that revision, and,
- if it was provided, the log message that accompanied the
- commit.</para>
+ revision it changed, the time and date of that revision,
+ and—if it was provided—the log message that accompanied
+ the commit.</para>
<screen>
$ svn log
@@ -1769,7 +1782,7 @@
<para>Note that the log messages are printed in
<emphasis>reverse chronological order</emphasis> by default.
If you wish to see a different range of revisions in a
- particular order, or just a single revision, pass the
+ particular order or just a single revision, pass the
<option>--revision</option> (<option>-r</option>)
option:</para>
@@ -1806,16 +1819,16 @@
messages. This is due to a combination of the behavior of
<command>svn commit</command> and the default behavior of
<command>svn log</command>. First, when you commit changes
- to the repository, <command>svn</command> only bumps the
+ to the repository, <command>svn</command> bumps only the
revision of files (and directories) that it commits, so
usually the parent directory remains at the older revision
- (See <xref
- linkend="svn.basic.in-action.mixedrevs.update-commit"/> for
- why). <command>svn log</command> then defaults to fetching
- the history of the directory at its current revision, and
- thus you don't see the newly-committed changes. The
- solution here is to either update your working copy or
- explicitly provide a revision number to <command>svn
+ (See
+ <xref linkend="svn.basic.in-action.mixedrevs.update-commit"/>
+ for an explanation of why). <command>svn log</command> then
+ defaults to fetching the history of the directory at its
+ current revision, and thus you don't see the newly committed
+ changes. The solution here is to either update your working
+ copy or explicitly provide a revision number to <command>svn
log</command> by using the <option>--revision</option>
(<option>-r</option>) option.</para>
@@ -1826,7 +1839,7 @@
<option>--verbose</option> (<option>-v</option>) option.
Because Subversion allows you to move and copy files and
directories, it is important to be able to track path changes
- in the filesystem, so in verbose mode, <command>svn
+ in the filesystem. So, in verbose mode, <command>svn
log</command> will include a list of changed paths in a
revision in its output:</para>
@@ -1882,7 +1895,7 @@
<!-- =============================================================== -->
<sect2 id="svn.tour.history.diff">
- <title>Examining the details of historical changes</title>
+ <title>Examining the Details of Historical Changes</title>
<para>We've already seen <command>svn diff</command>
before—it displays file differences in unified diff
@@ -1896,7 +1909,7 @@
<itemizedlist>
<listitem>
- <para>Examining local changes</para>
+ <para>Examining Local Changes</para>
</listitem>
<listitem>
@@ -1911,7 +1924,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.history.diff.local">
- <title>Examining Local Changes</title>
+ <title>Examining local changes</title>
<para>As we've seen, invoking <command>svn diff</command> with
no options will compare your working files to the cached
@@ -1938,7 +1951,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.history.diff.wcrepos">
- <title>Comparing Working Copy to Repository</title>
+ <title>Comparing working copy to repository</title>
<para>If a single <option>--revision</option>
(<option>-r</option>) number is passed, then your
@@ -1965,12 +1978,12 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.history.diff.reposrepos">
- <title>Comparing Repository to Repository</title>
+ <title>Comparing repository to repository</title>
<para>If two revision numbers, separated by a colon, are
passed via <option>--revision</option>
(<option>-r</option>), then the two revisions are directly
- compared.</para>
+ compared:</para>
<screen>
$ svn diff -r 2:3 rules.txt
@@ -2022,7 +2035,7 @@
<!-- =============================================================== -->
<sect2 id="svn.tour.history.browsing">
- <title>Browsing the repository</title>
+ <title>Browsing the Repository</title>
<para>Using <command>svn cat</command> and <command>svn
list</command>, you can view various revisions of files and
@@ -2097,7 +2110,7 @@
<para>The <command>svn list</command> with no arguments
defaults to the <emphasis>repository URL</emphasis> of the
current working directory, <emphasis>not</emphasis> the
- local working copy directory. After all, if you wanted a
+ local working copy directory. After all, if you want a
listing of your local directory, you could use just plain
<command>ls</command> (or any reasonable non-Unixy
equivalent).</para>
@@ -2109,14 +2122,16 @@
<!-- =============================================================== -->
<sect2 id="svn.tour.history.snapshots">
- <title>Fetching older repository snapshots</title>
+ <title>Fetching Older Repository Snapshots</title>
- <para>In addition to all of the above commands, you can use
+ <para>In addition to all of the previous commands, you can use
<command>svn update</command> and <command>svn
checkout</command> with the <option>--revision</option> option
- to take an entire working copy <quote>back in time</quote>
- <footnote><para>See? We told you that Subversion was a time
- machine.</para></footnote>:</para>
+ to take an entire working copy <quote>back in time</quote>:
+ <footnote>
+ <para>See? We told you that Subversion was a time machine.</para>
+ </footnote>
+ </para>
<screen>
$ svn checkout -r 1729 # Checks out a new working copy at r1729
@@ -2126,7 +2141,7 @@
</screen>
<tip>
- <para>Many Subversion newcomers attempt to use the above
+ <para>Many Subversion newcomers attempt to use the preceding
<command>svn update</command> example to <quote>undo</quote>
committed changes, but this won't work as you can't commit
changes that you obtain from backdating a working copy if
@@ -2165,6 +2180,11 @@
<sect1 id="svn.tour.cleanup">
<title>Sometimes You Just Need to Clean Up</title>
+ <para>Now that we've covered the day-to-day tasks that you'll
+ frequently use Subversion for, we'll review a few administrative
+ tasks relating to your working copy.</para>
+
+
<sect2 id="svn.tour.cleanup.disposal">
<title>Disposing of a Working Copy</title>
@@ -2194,19 +2214,19 @@
<sect2 id="svn.tour.cleanup.interruption">
- <title>Recovering From an Interruption</title>
+ <title>Recovering from an Interruption</title>
<para>When Subversion modifies your working copy (or any
information within <filename>.svn</filename>), it tries to do
so as safely as possible. Before changing the working copy,
- Subversion writes its intentions to a log file. Next it
+ Subversion writes its intentions to a log file. Next, it
executes the commands in the log file to apply the requested
change, holding a lock on the relevant part of the working
copy while it works—to prevent other Subversion clients
- from accessing the working copy in mid-change. Finally,
+ from accessing the working copy mid-change. Finally,
Subversion removes the log file. Architecturally, this is
similar to a journaled filesystem. If a Subversion operation
- is interrupted (if the process is killed, or if the machine
+ is interrupted (if the process is killed or if the machine
crashes, for example), the log files remain on disk. By
re-executing the log files, Subversion can complete the
previously started operation, and your working copy can get
@@ -2216,7 +2236,7 @@
does: it searches your working copy and runs any leftover
logs, removing working copy locks in the process.
If Subversion ever tells you that some part of your working copy
- is <quote>locked</quote>, then this is the command that you
+ is <quote>locked,</quote> then this is the command that you
should run. Also, <command>svn status</command> will display
an <literal>L</literal> next to locked items:</para>
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 Sun May 4 06:57:32 2008
@@ -92,7 +92,7 @@
<para>The Subversion client understands a number of revision
keywords. These keywords can be used instead of integer
arguments to the <option>--revision</option>
- (<option>-r</option>) switch, and are resolved into specific
+ (<option>-r</option>) option, and are resolved into specific
revision numbers by Subversion:</para>
<variablelist>
@@ -475,7 +475,7 @@
<para>But we've been touting the flexibility that Subversion
offers for your property values. And if you are planning to
- have a multi-line textual, or even binary, property value, you
+ have a multiline textual, or even binary, property value, you
probably do not want to supply that value on the command line.
So the <command>propset</command> subcommand takes a
<option>--file</option> (<option>-F</option>) option for
@@ -1834,7 +1834,7 @@
</screen>
<para>Now, let's check out the same tree again, but this time,
- we'll ask Subversion to give us only the top-most direcectory
+ we'll ask Subversion to give us only the top-most directory
with none of its children at all:</para>
<screen>
@@ -3629,7 +3629,7 @@
<para>Subversion's changelist feature is a handy tool for
grouping working copy files, but it does have a few limitations.
Changelists are artifacts of a particular working copy, which
- means that changelist assignments cannot be propogated to the
+ means that changelist assignments cannot be propagated to the
repository or otherwise shared with other users. Changelists
can only be assigned to files—Subversion doesn't
currently support the use of changelists with directories.
Modified: trunk/src/de/book/ch04-branching-and-merging.xml
==============================================================================
--- trunk/src/de/book/ch04-branching-and-merging.xml (original)
+++ trunk/src/de/book/ch04-branching-and-merging.xml Sun May 4 06:57:32 2008
@@ -500,7 +500,7 @@
you use an issue tracker to manage bugs, you can use the
revision numbers to refer to particular patches that fix
bugs—for example,
- <quote>this issue was fixed by revision 9238.</quote> Somebody
+ <quote>this issue was fixed by r9238.</quote> Somebody
can then run <command>svn log -r 9238</command> to read about
the exact changeset that fixed the bug, and run
<command>svn diff -c 9238</command> to see the patch itself.
@@ -509,7 +509,7 @@
revision numbers. You can merge specific changesets from one
branch to another by naming them in the merge
arguments: <command>svn merge -c 9238</command> would merge
- changeset #9238 into your working copy.</para>
+ changeset r9238 into your working copy.</para>
</sect2>
@@ -525,8 +525,8 @@
project's <filename>/trunk</filename>. It's in your best
interest to replicate those changes to your own branch, just
to make sure they mesh well with your changes. In fact, this
- is a best practice: by frequently keeping your branch in sync
- with the main development line, it helps
+ is a best practice: frequently keeping your branch in sync
+ with the main development line helps
prevent <quote>surprise</quote> conflicts when it comes time
for you to fold your changes back into the trunk.</para>
@@ -571,7 +571,7 @@
changes by running <command>svn revert</command> and start a
long <quote>what's going on?</quote> discussion with your
collaborators. If things look good, however, then you can
- submit your changes into the repository:</para>
+ submit these changes into the repository:</para>
<screen>
$ svn commit -m "Merged latest trunk changes to my-calc-branch."
@@ -702,6 +702,9 @@
$ pwd
/home/user/calc-trunk
+$ svn update # (just to make sure the working copy is at latest everywhere)
+At revision 390.
+
$ svn merge --reintegrate http://svn.example.com/repos/calc/branches/my-calc-branch
--- Merging r341 through r390 into '.':
U button.c
@@ -725,8 +728,9 @@
back</quote> is a different sort of work than what you've been
doing up until now. Previously, we had been
asking <command>svn merge</command> to grab the <quote>next
- set</quote> of changes from one branch and duplicate them to
- another. This is fairly straightforward, and each time
+ set</quote> of changes from one line of development (the
+ trunk) and duplicate them to another (your branch). This is
+ fairly straightforward, and each time
Subversion knows how to pick up where it left off. In our
prior examples, you can see that first it merges the ranges
345:356 from trunk to branch; later on, it continues by
@@ -747,8 +751,7 @@
<para>Now that your branch is merged to trunk, you'll no longer
need your branch. You can destroy your working copy of the
- branch, and also do some basic housecleaning in the
- repository:</para>
+ branch, and also remove it from the repository:</para>
<screen>
$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch
@@ -800,7 +803,7 @@
its value indicates which changes have already been replicated
into a particular directory.</para>
- <para>As we saw earlier, there's also a subcommand <command>svn
+ <para>There's also a subcommand <command>svn
mergeinfo</command>, which can be helpful in seeing not only
which changesets a directory has absorbed, but also which
changesets it's still eligible to receive. This gives a sort
@@ -1012,21 +1015,24 @@
<warning>
<para>Did you notice how, in the last example, the merge
- invocation caused two distinct ranges of merges to be applied?
- The <command>svn merge</command> command applied two
- independent patches to your working copy in order to skip over
- changeset 355, which your branch already contained. There's
- nothing inherently wrong with this, except that it has the
- potential to make conflict resolution more tricky. If the
- first range of changes creates conflicts,
- you <emphasis>must</emphasis> resolve them interactively in
- order for the merge process to continue and apply the second
- range of changes. If you postpone a conflict from the first
- wave of changes, the whole merge command will bail out with an
- error message.<footnote><para>At least, this is true in
- Subversion 1.5 at the time of writing. This behavior may
- improve in future versions of
- Subversion.</para></footnote></para>
+ invocation caused two distinct ranges of merges to be
+ applied? The <command>svn merge</command> command applied
+ two independent patches to your working copy in order to
+ skip over changeset 355, which your branch already
+ contained. There's nothing inherently wrong with this,
+ except that it has the potential to make conflict resolution
+ more tricky. If the first range of changes creates
+ conflicts, you <emphasis>must</emphasis> resolve them
+ interactively in order for the merge process to continue and
+ apply the second range of changes. If you postpone a
+ conflict from the first wave of changes, the whole merge
+ command will bail out with an error message.
+ <footnote>
+ <para>At least, this is true in Subversion 1.5 at the time
+ of writing. This behavior may improve in future
+ versions of Subversion.</para>
+ </footnote>
+ </para>
</warning>
<para>A word of warning: while <command>svn diff</command> and
@@ -1931,7 +1937,8 @@
abandon an existing working copy. See <xref
linkend="svn.ref.svn.c.switch"/> for more information and an
example.</para>
- </footnote></para>
+ </footnote>
+ </para>
<sidebar>
<title>Switches and Updates</title>
@@ -1946,7 +1953,7 @@
and then sends a description of the differences back to the
client. The only difference between <command>svn
switch</command> and <command>svn update</command> is that the
- latter command always compares two identical repositoryx
+ latter command always compares two identical repository
paths.</para>
<para>That is, if your working copy is a mirror of
Modified: trunk/src/de/book/ch06-server-configuration.xml
==============================================================================
--- trunk/src/de/book/ch06-server-configuration.xml (original)
+++ trunk/src/de/book/ch06-server-configuration.xml Sun May 4 06:57:32 2008
@@ -442,7 +442,7 @@
<!-- ================================================================= -->
<sect1 id="svn.serverconfig.svnserve">
- <title>svnserve, a custom server</title>
+ <title><command>svnserve</command>, a Custom Server</title>
<para>The <command>svnserve</command> program is a lightweight
server, capable of speaking to clients over TCP/IP using a
@@ -734,9 +734,12 @@
</itemizedlist>
- <para>The <command>svnserve</command> server, by default, only
- knows how to send a CRAM-MD5 <footnote><para>See RFC
- 2195.</para></footnote> authentication challenge. In essence,
+ <para>The <command>svnserve</command> server, by default, knows
+ only how to send a CRAM-MD5
+ <footnote>
+ <para>See RFC 2195.</para>
+ </footnote>
+ authentication challenge. In essence,
the server sends a small amount of data to the client. The
client uses the MD5 hash algorithm to create a fingerprint of
the data and password combined, then sends the fingerprint as
@@ -907,18 +910,18 @@
options available to you.</para>
<sidebar>
- <title>What is SASL?</title>
+ <title>What Is SASL?</title>
<para>The Cyrus Simple Authentication and Security Layer is
- open-source software written by Carnegie Mellon University.
+ open source software written by Carnegie Mellon University.
It adds generic authentication and encryption capabilities
to any network protocol, and as of Subversion 1.5 and later,
both the <command>svnserve</command> server
and <command>svn</command> client know how to make use of
this library. It may or may not be available to you: if
you're building Subversion yourself, you'll need to have at
- least version 2.1 of SASL installed on your system and
+ least version 2.1 of SASL installed on your system, and
you'll need to make sure that it's detected during
- Subversion's build process. If you're using a pre-built
+ Subversion's build process. If you're using a prebuilt
Subversion binary package, you'll have to check with the
package maintainer as to whether SASL support was compiled
in. SASL comes with a number of pluggable modules that
@@ -933,22 +936,22 @@
<ulink url="http://asg.web.cmu.edu/sasl/sasl-library.html"/>.</para>
</sidebar>
- <para>Normally, when a subversion client connects
- to <command>svnserve</command>, the server sends a greeting
- which advertises a list of capabilities it supports, and the
+ <para>Normally, when a subversion client connects to
+ <command>svnserve</command>, the server sends a greeting that
+ advertises a list of the capabilities it supports, and the
client responds with a similar list of capabilities. If the
server is configured to require authentication, it then sends
- a challenge which lists the authentication mechanisms
+ a challenge that lists the authentication mechanisms
available; the client responds by choosing one of the
mechanisms, and then authentication is carried out in some
number of roundtrip messages. Even when SASL capabilities
aren't present, the client and server inherently know how to
- use the CRAM-MD5 and ANONYMOUS mechanisms (see
- <xref linkend="svn.serverconfig.svnserve.auth"/>). If server
- and client were linked against SASL, then a number of other
- authentication mechanisms may also be available. However,
- you'll need to explicitly configure SASL on the server-side to
- advertise them.</para>
+ use the CRAM-MD5 and ANONYMOUS mechanisms (see the earlier
+ section <xref linkend="svn.serverconfig.svnserve.auth"/>). If
+ server and client were linked against SASL, then a number of
+ other authentication mechanisms may also be available.
+ However, you'll need to explicitly configure SASL on the
+ server side to advertise them.</para>
<sect3 id="svn.serverconfig.svnserve.sasl.authn">
<title>Authenticating with SASL</title>
@@ -959,15 +962,15 @@
repository's <filename>svnserve.conf</filename> file, with
this key-value pair:</para>
- <screen>
+ <programlisting>
use-sasl = true
-</screen>
+</programlisting>
<para>Second, create a file
called <filename>subversion.conf</filename> in a place where
the SASL library can find it—typically in the
- directory where SASL plugins are located. You'll have to
- locate the plugin directory on your particular system, such
+ directory where SASL plug-ins are located. You'll have to
+ locate the plug-in directory on your particular system, such
as <filename>/usr/lib/sasl2/</filename>
or <filename>/etc/sasl2/</filename>. (Note that this
is <emphasis>not</emphasis>
@@ -975,29 +978,29 @@
within a repository!)</para>
<para>On a Windows server, you'll have to also edit the
- registry (using a tool like <command>regedit</command>) to
- tell SASL where to find things. Create a registry key
+ registry (using a tool such as <command>regedit</command>)
+ to tell SASL where to find things. Create a registry key
named <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\Carnegie
Mellon\Project Cyrus\SASL Library]</literal>, and place two
keys inside it: a key called <literal>SearchPath</literal>
- (whose value is a path containing the
- SASL <filename>.dll</filename> plugins), and a key
- called <literal>ConfFile</literal> (whose value is a path
+ (whose value is a path containing the SASL
+ <filename>.dll</filename> plug-ins), and a key called
+ <literal>ConfFile</literal> (whose value is a path
containing the <filename>subversion.conf</filename>
- file.)</para>
+ file).</para>
<para>Because SASL provides so many different kinds of
authentication mechanisms, it would be foolish (and far
beyond the scope of this book) to try and describe every
possible server-side configuration. Instead, we recommend
- that you read the documentation supplied in
- the <filename>doc/</filename> subdirectory of the SASL
- source code. It goes into great detail about each mechanism
- and how to configure the server appropriately for each. For
- the purposes of this discussion, we'll just demonstrate a
- simple example of configuring the DIGEST-MD5 mechanism. For
+ that you read the documentation supplied in the
+ <filename>doc/</filename> subdirectory of the SASL source
+ code. It goes into great detail about every mechanism and
+ how to configure the server appropriately for each. For the
+ purposes of this discussion, we'll just demonstrate a simple
+ example of configuring the DIGEST-MD5 mechanism. For
example, if your <filename>subversion.conf</filename>
- contains:</para>
+ contains the following:</para>
<screen>
pwcheck_method: auxprop
@@ -1005,13 +1008,13 @@
mech_list: DIGEST-MD5
</screen>
- <para>...then you've told SASL to advertise the DIGEST-MD5
- mechanism to clients, and to check user passwords against a
- private password database (typically stored
- in <filename>/etc/sasldb2</filename>). A system
- administrator can then use
- the <command>saslpasswd2</command> program to add or modify
- usernames and passwords in the database:</para>
+ <para>then you've told SASL to advertise the DIGEST-MD5
+ mechanism to clients and to check user passwords against a
+ private password database (typically stored in
+ <filename>/etc/sasldb2</filename>). A system administrator
+ can then use the <command>saslpasswd2</command> program to
+ add or modify usernames and passwords in the
+ database:</para>
<screen>
$ saslpasswd2 -c -u realm username
@@ -1027,16 +1030,17 @@
standard SASL password database, make sure that
the <command>svnserve</command> program has read access to
the file (and possibly write access as well, if you're using
- a mechanism such as OTP.)</para>
+ a mechanism such as OTP).</para>
<para>This is just one simple way of configuring SASL. Many
- other authentication mechanisms available, and passwords can
- be stored in other places such as in LDAP or a SQL database.
- Consult the full SASL documentation for details.</para>
+ other authentication mechanisms are available, and passwords
+ can be stored in other places such as in LDAP or a SQL
+ database. Consult the full SASL documentation for
+ details.</para>
<para>Remember that if you configure your server to only allow
- certain SASL authentication mechanisms, this can also have
- the effect of forcing all of connecting clients to have SASL
+ certain SASL authentication mechanisms, this can have the
+ effect of forcing all of connecting clients to have SASL
support as well. Any Subversion client built without SASL
support (which includes all pre-1.5 clients) will be unable
to authenticate. On the one hand, this sort of restriction
@@ -1049,15 +1053,15 @@
</sect3>
<sect3 id="svn.serverconfig.svnserve.sasl.encryption">
- <title>SASL Encryption</title>
+ <title>SASL encryption</title>
- <para>SASL is also able to perform data-encryption if a
+ <para>SASL is also able to perform data encryption if a
particular mechanism supports it. The built-in CRAM-MD5
mechanism doesn't support encryption, but DIGEST-MD5 does,
- and mechanisms like SRP actually require use of the OpenSSL
- library . To enable or disable different levels of
- encryption, you can set two values in your
- repository's <filename>svnserve.conf</filename> file:</para>
+ and mechanisms such as SRP actually require use of the
+ OpenSSL library. To enable or disable different levels of
+ encryption, you can set two values in your repository's
+ <filename>svnserve.conf</filename> file:</para>
<screen>
[sasl]
@@ -1066,17 +1070,17 @@
max-encryption = 256
</screen>
- <para>The <literal>min-encryption</literal>
- and <literal>max-encryption</literal> variables control the
+ <para>The <literal>min-encryption</literal> and
+ <literal>max-encryption</literal> variables control the
level of encryption demanded by the server. To disable
encryption completely, set both values to 0. To enable
- simple checksumming of data (i.e. prevent tampering and
+ simple checksumming of data (i.e., prevent tampering and
guarantee data integrity without encryption), set both
values to 1. If you wish to allow—but not
require—encryption, set the minimum value to 0, and
the maximum value to some bit-length. To require encryption
unconditionally, set both values to numbers greater than 1.
- In our example above, we require clients to do at least
+ In our previous example, we require clients to do at least
128-bit encryption, but no more than 256-bit
encryption.</para>
@@ -1120,13 +1124,13 @@
<command>svnserve</command> process on the remote machine
running as the user <literal>harry</literal>. The
<command>svnserve</command> command is being invoked in tunnel
- mode (<option>-t</option>) and its network protocol is being
+ mode (<option>-t</option>), and its network protocol is being
<quote>tunneled</quote> over the encrypted connection by
- <command>ssh</command>, the tunnel-agent.
+ <command>ssh</command>, the tunnel agent.
<command>svnserve</command> is aware that it's running as the
user <literal>harry</literal>, and if the client performs a
- commit, the authenticated username will be used as the
- author of the new revision.</para>
+ commit, the authenticated username will be used as the author
+ of the new revision.</para>
<para>The important thing to understand here is that the
Subversion client is <emphasis>not</emphasis> connecting to a
@@ -1141,7 +1145,7 @@
repository, remember that it's the <command>ssh</command>
program prompting for authentication, and
<emphasis>not</emphasis> the <command>svn</command> client
- program. That means there's no automatic password caching
+ program. That means there's no automatic password-caching
going on (see <xref linkend="svn.serverconfig.netmodel.credcache"/>). The
Subversion client often makes multiple connections to the
repository, though users don't normally notice this due to the
@@ -1149,7 +1153,7 @@
<literal>svn+ssh://</literal> URLs, however, users may be
annoyed by <command>ssh</command> repeatedly asking for a
password for every outbound connection. The solution is to
- use a separate SSH password-caching tool like
+ use a separate SSH password-caching tool such as
<command>ssh-agent</command> on a Unix-like system, or
<command>pageant</command> on Windows.</para>
@@ -1160,27 +1164,24 @@
<literal>file://</literal> URL. If multiple system users are
going to be accessing the repository directly, you may want to
place them into a common group, and you'll need to be careful
- about umasks. (Be sure to read <xref
- linkend="svn.serverconfig.multimethod"/>.) But even in the case of
- tunneling, the <filename>svnserve.conf</filename> file can
- still be used to block access, by simply setting
- <literal>auth-access = read</literal> or <literal>auth-access
- = none</literal>.
- <footnote>
- <para>Note that using any sort
- of <command>svnserve</command>-enforced access control at
- all is a bit pointless; the user already has direct access to
- the repository database.</para>
- </footnote>
- </para>
+ about umasks (be sure to read <xref
+ linkend="svn.serverconfig.multimethod"/> later in this
+ chapter). But even in the case of tunneling, the
+ <filename>svnserve.conf</filename> file can still be used to
+ block access, by simply setting <literal>auth-access =
+ read</literal> or <literal>auth-access = none</literal>.
+ <footnote> <para>Note that using any sort of
+ <command>svnserve</command>-enforced access control at all is
+ a bit pointless; the user already has direct access to the
+ repository database.</para> </footnote> </para>
<para>You'd think that the story of SSH tunneling would end
here, but it doesn't. Subversion allows you to create custom
- tunnel behaviors in your run-time <filename>config</filename>
- file (see <xref linkend="svn.advanced.confarea"/>). For example,
- suppose you want to use RSH instead of SSH<footnote><para>We
- don't actually recommend this, since RSH is notably less
- secure than SSH.</para></footnote>. In the
+ tunnel behaviors in your runtime <filename>config</filename>
+ file (see <xref linkend="svn.advanced.confarea"/>.) For
+ example, suppose you want to use RSH instead of SSH.
+ <footnote> <para>We don't actually recommend this, since RSH
+ is notably less secure than SSH.</para> </footnote> In the
<literal>[tunnels]</literal> section of your
<filename>config</filename> file, simply define it like
this:</para>
@@ -1196,7 +1197,7 @@
URL scheme, the Subversion client will actually be running the
command <command>rsh host svnserve -t</command> behind the
scenes. If you include a username in the URL (for example,
- <literal>svn+rsh://username@host/path</literal>) the client
+ <literal>svn+rsh://username@host/path</literal>), the client
will also include that in its command (<command>rsh
username at host svnserve -t</command>). But you can define new
tunneling schemes to be much more clever than that:</para>
@@ -1214,7 +1215,7 @@
<literal>svn+joessh://</literal> URL would invoke the
particular SSH binary with <option>-p 29934</option> as
arguments—useful if you want the tunnel program to
- connect to a non-standard port.</para>
+ connect to a nonstandard port.</para>
<para>Second, it shows how to define a custom environment
variable that can override the name of the tunneling program.
@@ -1305,9 +1306,9 @@
<para>In this example, <filename>/path/to/svnserve</filename>
might be a custom wrapper script
around <command>svnserve</command> which sets the umask (see
- <xref linkend="svn.serverconfig.multimethod"/>). It also shows how to
- anchor <command>svnserve</command> in a virtual root
- directory, just as one often does when
+ <xref linkend="svn.serverconfig.multimethod"/>.) It also
+ shows how to anchor <command>svnserve</command> in a virtual
+ root directory, just as one often does when
running <command>svnserve</command> as a daemon process.
This might be done either to restrict access to parts of the
system, or simply to relieve the user of having to type an
@@ -1316,7 +1317,7 @@
<para>It's also possible to have multiple users share a single
account. Instead of creating a separate system account for
- each user, generate a public/private keypair for each
+ each user, generate a public/private key-pair for each
person. Then place each public key into
the <filename>authorized_users</filename> file, one per
line, and use the <option>--tunnel-user</option>
@@ -1342,7 +1343,7 @@
other forms of SSH access, even if you've set
the <literal>command</literal> value
in <filename>authorized_keys</filename>. For example, the
- user may still get shell access through SSH, or be able to
+ user may still get shell access through SSH or be able to
perform X11 or general port-forwarding through your server.
To give the user as little permission as possible, you may
want to specify a number of restrictive options immediately
@@ -1374,7 +1375,7 @@
<!-- ================================================================= -->
<sect1 id="svn.serverconfig.httpd">
- <title>httpd, the Apache HTTP server</title>
+ <title>httpd, the Apache HTTP Server</title>
<para>The Apache HTTP Server is a <quote>heavy duty</quote>
network server that Subversion can leverage. Via a custom
@@ -1386,13 +1387,11 @@
writing—specifically, versioned
writing—capabilities. The result is a standardized,
robust system that is conveniently packaged as part of the
- Apache 2.0 software, is supported by numerous operating systems
+ Apache 2.0 software, supported by numerous operating systems
and third-party products, and doesn't require network
- administrators to open up yet another custom port.
- <footnote>
- <para>They really hate doing that.</para>
- </footnote>
- While an Apache-Subversion server has more features than
+ administrators to open up yet another custom port.<footnote>
+ <para>They really hate doing that.</para></footnote> While an
+ Apache-Subversion server has more features than
<command>svnserve</command>, it's also a bit more difficult
to set up. With flexibility often comes more complexity.</para>
@@ -1400,9 +1399,10 @@
Apache configuration directives. While some examples are given
of the use of these directives, describing them in full is
outside the scope of this chapter. The Apache team maintains
- excellent documentation, publicly available on their website at
+ excellent documentation, publicly available on their web site at
<ulink url="http://httpd.apache.org"/>. For example, a general
- reference for the configuration directives is located at <ulink url="
+ reference for the configuration directives is located at
+ <ulink url="
http://httpd.apache.org/docs-2.0/mod/directives.html"/>.</para>
<para>Also, as you make changes to your Apache setup, it is likely
@@ -1412,11 +1412,11 @@
file are directives that specify the on-disk locations of the
access and error logs generated by Apache (the
<literal>CustomLog</literal> and <literal>ErrorLog</literal>
- directives, respectively). Subversion's mod_dav_svn uses
- Apache's error logging interface as well. You can always browse
- the contents of those files for information that might reveal
- the source of a problem that is not clearly noticeable
- otherwise.</para>
+ directives, respectively).
+ Subversion's <command>mod_dav_svn</command> uses Apache's error
+ logging interface as well. You can always browse the contents
+ of those files for information that might reveal the source of a
+ problem that is not clearly noticeable otherwise.</para>
<sidebar>
<title>Why Apache 2?</title>
@@ -1428,21 +1428,21 @@
been somewhat slow to upgrade to the Apache 2.X series for
various reasons: some people fear change, especially changing
something as critical as a web server. Other people depend on
- plug-in modules that only work against the Apache 1.3 API, and
- are waiting for a 2.X port. Whatever the reason, many people
- begin to worry when they first discover that Subversion's
- Apache module is written specifically for the Apache 2 API.</para>
+ plug-in modules that work only against the Apache 1.3 API, and
+ they are waiting for a 2.X port. Whatever the reason, many
+ people begin to worry when they first discover that
+ Subversion's Apache module is written specifically for the
+ Apache 2 API.</para>
<para>The proper response to this problem is: don't worry about
- it. It's easy to run Apache 1.3 and Apache 2 side-by-side;
- simply install them to separate places, and use Apache 2 as a
+ it. It's easy to run Apache 1.3 and Apache 2 side by side;
+ simply install them to separate places and use Apache 2 as a
dedicated Subversion server that runs on a port other than 80.
Clients can access the repository by placing the port number
into the URL:</para>
<screen>
$ svn checkout http://host.example.com:7382/repos/project
-…
</screen>
</sidebar>
@@ -1462,23 +1462,23 @@
<itemizedlist>
<listitem>
- <para>getting httpd 2.0 up and running with the mod_dav
- module,</para>
+ <para>Getting httpd 2.0 up and running with
+ the <command>mod_dav</command> module</para>
</listitem>
<listitem>
- <para>installing the mod_dav_svn plugin to mod_dav, which
- uses Subversion's libraries to access the repository,
- and</para>
+ <para>Installing the <command>mod_dav_svn</command> back end
+ to <command>mod_dav</command>, which uses Subversion's
+ libraries to access the repository</para>
</listitem>
<listitem>
- <para>configuring your <filename>httpd.conf</filename>
- file to export (or expose) the repository.</para>
+ <para>Configuring your <filename>httpd.conf</filename>
+ file to export (or expose) the repository</para>
</listitem>
</itemizedlist>
<para>You can accomplish the first two items either by
compiling <command>httpd</command> and Subversion from
- source code, or by installing pre-built binary packages of
+ source code or by installing prebuilt binary packages of
them on your system. For the most up-to-date information on
how to compile Subversion for use with the Apache HTTP Server,
as well as how to compile and configure Apache itself for
@@ -1494,7 +1494,7 @@
<para>Once you have all the necessary components installed on
your system, all that remains is the configuration of Apache
via its <filename>httpd.conf</filename> file. Instruct Apache
- to load the mod_dav_svn module using the
+ to load the <command>mod_dav_svn</command> module using the
<literal>LoadModule</literal> directive. This directive must
precede any other Subversion-related configuration items. If
your Apache was installed using the default layout, your
@@ -1525,7 +1525,7 @@
<para>At a later location in your configuration file, you now
need to tell Apache where you keep your Subversion repository
(or repositories). The <literal>Location</literal> directive
- has an XML-like notation, starting with an opening tag, and
+ has an XML-like notation, starting with an opening tag and
ending with a closing tag, with various other configuration
directives in the middle. The purpose of the
<literal>Location</literal> directive is to instruct Apache to
@@ -1550,12 +1550,13 @@
<para>If you plan to support multiple Subversion repositories
that will reside in the same parent directory on your local
- disk, you can use an alternative directive, the
- <literal>SVNParentPath</literal> directive, to indicate that
- common parent directory. For example, if you know you will be
- creating multiple Subversion repositories in a directory
+ disk, you can use an alternative directive
+ —<literal>SVNParentPath</literal>— to indicate
+ that common parent directory. For example, if you know you
+ will be creating multiple Subversion repositories in a
+ directory
<filename>/var/svn</filename> that would be accessed via
- URLs like <uri>http://my.server.com/svn/repos1</uri>,
+ URLs such as <uri>http://my.server.com/svn/repos1</uri>,
<uri>http://my.server.com/svn/repos2</uri>, and
so on, you could use the <filename>httpd.conf</filename>
configuration syntax in the following example:</para>
@@ -1582,7 +1583,7 @@
<para>Be sure that when you define your new
<literal>Location</literal>, it doesn't overlap with other
- exported Locations. For example, if your main
+ exported locations. For example, if your main
<literal>DocumentRoot</literal> is exported to
<filename>/www</filename>, do not export a Subversion
repository in <literal><Location /www/repos></literal>.
@@ -1603,9 +1604,10 @@
directories. As part of the sanity checking done by the
Apache modules, the source of the copy is expected to be
located on the same machine as the destination of the copy.
- To satisfy this requirement, you might need to tell mod_dav
- the name you use as the hostname of your server. Generally,
- you can use the <literal>ServerName</literal> directive in
+ To satisfy this requirement, you might need to
+ tell <command>mod_dav</command> the name you use as the
+ hostname of your server. Generally, you can use
+ the <literal>ServerName</literal> directive in
<filename>httpd.conf</filename> to accomplish this.</para>
<screen>
@@ -1623,7 +1625,7 @@
<para>At this stage, you should strongly consider the question
of permissions. If you've been running Apache for some time
now as your regular web server, you probably already have a
- collection of content—web pages, scripts and such.
+ collection of content—web pages, scripts, and such.
These items have already been configured with a set of
permissions that allows them to work with Apache, or more
appropriately, that allows Apache to work with those files.
@@ -1654,7 +1656,8 @@
<title>Authentication Options</title>
<para>At this point, if you configured
- <filename>httpd.conf</filename> to contain something like</para>
+ <filename>httpd.conf</filename> to contain something like the
+ following:</para>
<screen>
<Location /svn>
@@ -1663,26 +1666,26 @@
</Location>
</screen>
- <para>…then your repository is <quote>anonymously</quote>
+ <para>then your repository is <quote>anonymously</quote>
accessible to the world. Until you configure some
authentication and authorization policies, the Subversion
- repositories you make available via the
+ repositories that you make available via the
<literal>Location</literal> directive will be generally
- accessible to everyone. In other words,</para>
+ accessible to everyone. In other words:</para>
<itemizedlist>
<listitem>
- <para>anyone can use their Subversion client to check out a
+ <para>Anyone can use a Subversion client to check out a
working copy of a repository URL (or any of its
- subdirectories),</para>
+ subdirectories).</para>
</listitem>
<listitem>
- <para>anyone can interactively browse the repository's
- latest revision simply by pointing their web browser to
- the repository URL, and</para>
+ <para>Anyone can interactively browse the repository's
+ latest revision simply by pointing a web browser to
+ the repository URL.</para>
</listitem>
<listitem>
- <para>anyone can commit to the repository.</para>
+ <para>Anyone can commit to the repository.</para>
</listitem>
</itemizedlist>
@@ -1695,7 +1698,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.httpd.authn.basic">
- <title>Setting Up HTTP Authentication</title>
+ <title>Setting up HTTP authentication</title>
<para>The easiest way to authenticate a client is via the
HTTP Basic authentication mechanism, which simply uses a
@@ -1704,7 +1707,7 @@
utility for managing the list of acceptable usernames and
passwords. Let's grant commit access to
Sally and Harry. First, we need to add them to the password
- file.</para>
+ file:</para>
<screen>
$ ### First time: use -c to create the file
@@ -1750,17 +1753,16 @@
</screen>
<para>This <literal><Location></literal> block is not
- yet complete, and will not do anything useful. It's merely
- telling Apache that whenever authorization is required,
- Apache should harvest a username and password from the
- Subversion client. What's missing here, however, are
+ yet complete, and it will not do anything useful. It's
+ merely telling Apache that whenever authorization is
+ required, Apache should harvest a username and password from
+ the Subversion client. What's missing here, however, are
directives that tell Apache <emphasis>which</emphasis> sorts
of client requests require authorization. Wherever
- authorization is required, Apache will demand
- authentication as well. The simplest thing to do is protect
- all requests. Adding <literal>Require valid-user</literal>
- tells Apache that all requests require an authenticated
- user:</para>
+ authorization is required, Apache will demand authentication
+ as well. The simplest thing to do is protect all requests.
+ Adding <literal>Require valid-user</literal> tells Apache
+ that all requests require an authenticated user:</para>
<screen>
<Location /svn>
@@ -1782,10 +1784,10 @@
very nearly plain-text over the network, and thus are
extremely insecure.</para>
- <para>Another option is to not use Basic authentication
- but <quote>Digest</quote> authentication instead. Digest
- authentication allows the server to verify the client's
- identity <emphasis>without</emphasis> passing the plaintext
+ <para>Another option is to not use Basic authentication but to
+ use Digest authentication instead. Digest authentication
+ allows the server to verify the client's
+ identity <emphasis>without</emphasis> passing the plain-text
password over the network. Assuming that the client and
server both know the user's password, they can verify that
the password is the same by using it to apply a hashing
@@ -1819,7 +1821,7 @@
configure Apache to use a self-signed server certificate.
<footnote>
<para>While self-signed server certificates are still
- vulnerable to a <quote>man in the middle</quote> attack,
+ vulnerable to a <quote>man-in-the-middle</quote> attack,
such an attack is much more difficult for a casual
observer to pull off, compared to sniffing unprotected
passwords.</para>
@@ -1832,7 +1834,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.httpd.authn.sslcerts">
- <title>SSL Certificate Management</title>
+ <title>SSL certificate management</title>
<para>Businesses that need to expose their repositories for access
outside the company firewall should be conscious of the
@@ -1851,7 +1853,7 @@
further communication is encrypted via a session key.</para>
<para>It's beyond the scope of this book to describe how to
- generate client and server certificates, and how to
+ generate client and server certificates and how to
configure Apache to use them. Many other books, including
Apache's own documentation, describe this task. But what
<emphasis>can</emphasis> be covered here is how to manage
@@ -1863,8 +1865,8 @@
information:</para>
<itemizedlist>
- <listitem><para>a server certificate</para></listitem>
- <listitem><para>a demand for a client certificate</para></listitem>
+ <listitem><para>A server certificate</para></listitem>
+ <listitem><para>A demand for a client certificate</para></listitem>
</itemizedlist>
<para>If the client receives a server certificate, it needs to
@@ -1897,14 +1899,14 @@
same question you've probably seen coming from your web
browser (which is just another HTTP client like Subversion).
If you choose the (p)ermanent option, the server certificate
- will be cached in your private run-time
+ will be cached in your private runtime
<filename>auth/</filename> area in just the same way your
username and password are cached (see <xref
linkend="svn.serverconfig.netmodel.credcache"/>). If cached,
Subversion will automatically trust this certificate
in future negotiations.</para>
- <para>Your run-time <filename>servers</filename> file also gives
+ <para>Your runtime <filename>servers</filename> file also gives
you the ability to make your Subversion client automatically
trust specific CAs, either globally or on a per-host basis.
Simply set the <literal>ssl-authority-files</literal>
@@ -1916,7 +1918,7 @@
ssl-authority-files = /path/to/CAcert1.pem;/path/to/CAcert2.pem
</screen>
- <para>Many OpenSSL installations also have a pre-defined set
+ <para>Many OpenSSL installations also have a predefined set
of <quote>default</quote> CAs that are nearly universally
trusted. To make the Subversion client automatically trust
these standard authorities, set the
@@ -1931,7 +1933,7 @@
Apache trusts. A client certificate is usually stored on
disk in encrypted format, protected by a local password.
When Subversion receives this challenge, it will ask you for
- both a path to the certificate and the password which
+ both a path to the certificate and for the password that
protects it:</para>
<screen>
@@ -1994,19 +1996,19 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.httpd.authz.blanket">
- <title>Blanket Access Control</title>
+ <title>Blanket access control</title>
<para>The simplest form of access control is to authorize
- certain users for either read-only access to a repository,
- or read/write access to a repository.</para>
+ certain users for either read-only access to a repository or
+ read/write access to a repository.</para>
<para>You can restrict access on all repository operations by
adding the <literal>Require valid-user</literal> directive
to your <literal><Location></literal> block. Using
our previous example, this would mean that only clients that
claimed to be either <literal>harry</literal> or
- <literal>sally</literal>, and provided the correct
- password for their respective username, would be allowed to
+ <literal>sally</literal> and that provided the correct
+ password for their respective username would be allowed to
do anything with the Subversion repository:</para>
<screen>
@@ -2027,7 +2029,7 @@
<para>Sometimes you don't need to run such a tight ship. For
example, Subversion's own source code repository at
<ulink url="http://svn.collab.net/repos/svn"/> allows anyone
- in the world to perform read-only repository tasks (like
+ in the world to perform read-only repository tasks (such as
checking out working copies and browsing the repository with
a web browser), but restricts all write operations to
authenticated users. To do this type of selective
@@ -2081,7 +2083,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.httpd.authz.perdir">
- <title>Per-Directory Access Control</title>
+ <title>Per-directory access control</title>
<para>It's possible to set up finer-grained permissions using
a second Apache httpd module,
@@ -2116,14 +2118,15 @@
<para>Apache is flexible, so you have the option to configure
your block in one of three general patterns. To begin,
choose one of these basic configuration patterns. (The
- examples below are very simple; look at Apache's own
+ following examples are very simple; look at Apache's own
documentation for much more detail on Apache authentication
and authorization options.)</para>
<para>The simplest block is to allow open access to everyone.
In this scenario, Apache never sends authentication
challenges, so all users are treated as
- <quote>anonymous</quote>.</para>
+ <quote>anonymous.</quote> (See
+ <xref linkend="svn.serverconfig.httpd.authz.perdir.ex-1"/>.)</para>
<example id="svn.serverconfig.httpd.authz.perdir.ex-1">
<title>A sample configuration for anonymous access.</title>
@@ -2142,8 +2145,9 @@
configure your block to demand authentication from everyone.
All clients must supply credentials to identify themselves.
Your block unconditionally requires authentication via the
- <literal>Require valid-user</literal> directive, and defines
- a means to authenticate.</para>
+ <literal>Require valid-user</literal> directive, and it
+ defines a means to authenticate. (See
+ <xref linkend="svn.serverconfig.httpd.authz.perdir.ex-2"/>.)</para>
<example id="svn.serverconfig.httpd.authz.perdir.ex-2">
<title>A sample configuration for authenticated access.</title>
@@ -2174,13 +2178,14 @@
users start out accessing the repository anonymously. If
your access control policy demands a real username at any
point, Apache will demand authentication from the client.
- To do this, you use both the <literal>Satisfy Any</literal>
+ To do this, use both the <literal>Satisfy Any</literal>
and <literal>Require valid-user</literal> directives
- together.</para>
+ together. (See
+ <xref linkend="svn.serverconfig.httpd.authz.perdir.ex-3"/>.)</para>
<example id="svn.serverconfig.httpd.authz.perdir.ex-3">
<title>A sample configuration for mixed
- authenticated/anonymous access.</title>
+ authenticated/anonymous access</title>
<programlisting>
<Location /repos>
DAV svn
@@ -2205,41 +2210,43 @@
<para>Once you've settled on one of these three
basic <filename>httpd.conf</filename> templates, you need to
create your file containing access rules for particular
- paths within the repository. This is described in
+ paths within the repository. This is described later in
+ this chapter in
<xref linkend="svn.serverconfig.pathbasedauthz"/>.</para>
</sect3>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.httpd.authz.pathauthzoff">
- <title>Disabling Path-based Checks</title>
+ <title>Disabling path-based checks</title>
<para>The <command>mod_dav_svn</command> module goes through a
lot of work to make sure that data you've marked
<quote>unreadable</quote> doesn't get accidentally leaked.
This means that it needs to closely monitor all of the paths
- and file-contents returned by commands like <command>svn
+ and file-contents returned by commands such as <command>svn
checkout</command> or <command>svn update</command>
commands. If these commands encounter a path that isn't
readable according to some authorization policy, then the
path is typically omitted altogether. In the case of
- history or rename tracing—e.g. running a command like
- <command>svn cat -r OLD foo.c</command> on a file that was
- renamed long ago—the rename tracking will simply halt
- if one of the object's former names is determined to be
+ history or rename tracing—e.g., running a command such
+ as <command>svn cat -r OLD foo.c</command> on a file that
+ was renamed long ago—the rename tracking will simply
+ halt if one of the object's former names is determined to be
read-restricted.</para>
- <para>All of this path-checking can sometimes be quite
+ <para>All of this path checking can sometimes be quite
expensive, especially in the case of <command>svn
- log</command>. When retrieving a list of revisions, the server
- looks at every changed path in each revision and checks it
- for readability. If an unreadable path is discovered, then
- it's omitted from the list of the revision's changed paths
- (normally seen with the <option>--verbose</option> option),
- and the whole log message is suppressed. Needless to say,
- this can be time-consuming on revisions that affect a large
- number of files. This is the cost of security: even if you
- haven't configured a module like
+ log</command>. When retrieving a list of revisions, the
+ server looks at every changed path in each revision and
+ checks it for readability. If an unreadable path is
+ discovered, then it's omitted from the list of the
+ revision's changed paths (normally seen with
+ the <option>--verbose</option> option), and the whole log
+ message is suppressed. Needless to say, this can be
+ time-consuming on revisions that affect a large number of
+ files. This is the cost of security: even if you haven't
+ configured a module such as
<command>mod_authz_svn</command> at all, the
<command>mod_dav_svn</command> module is still asking Apache
<command>httpd</command> to run authorization checks on
@@ -2248,14 +2255,16 @@
all it can do is ask Apache to invoke whatever might be
present.</para>
- <para>On the other hand, there's also an escape-hatch of
- sorts, one which allows you to trade security features for
+ <para>On the other hand, there's also an escape hatch of
+ sorts, which allows you to trade security features for
speed. If you're not enforcing any sort of per-directory
- authorization (i.e. not using
+ authorization (i.e., not using
<command>mod_authz_svn</command> or similar module), then
- you can disable all of this path-checking. In your
+ you can disable all of this path checking. In your
<filename>httpd.conf</filename> file, use the
- <literal>SVNPathAuthz</literal> directive:</para>
+ <literal>SVNPathAuthz</literal> directive as shown in
+ <xref linkend="svn.serverconfig.httpd.authz.pathauthzoff.ex-1"/>.
+ </para>
<example id="svn.serverconfig.httpd.authz.pathauthzoff.ex-1">
<title>Disabling path checks altogether</title>
@@ -2269,9 +2278,10 @@
</programlisting>
</example>
- <para>The <literal>SVNPathAuthz</literal> directive is <quote>on</quote> by
- default. When set <quote>off</quote>, all path-based
- authorization checking is disabled;
+ <para>The <literal>SVNPathAuthz</literal> directive
+ is <quote>on</quote> by default. When
+ set <quote>off,</quote> all path-based authorization
+ checking is disabled;
<command>mod_dav_svn</command> stops invoking authorization
checks on every path it discovers.</para>
@@ -2284,12 +2294,13 @@
<title>Extra Goodies</title>
<para>We've covered most of the authentication and authorization
- options for Apache and mod_dav_svn. But there are a few other
- nice features that Apache provides.</para>
+ options for Apache and <command>mod_dav_svn</command>. But
+ there are a few other nice features that Apache
+ provides.</para>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.httpd.extra.browsing">
- <title>Repository Browsing</title>
+ <title>Repository browsing</title>
<para>One of the most useful benefits of an Apache/WebDAV
configuration for your Subversion repository is that the
@@ -2297,30 +2308,31 @@
are immediately available for viewing via a regular web
browser. Since Subversion uses URLs to identify versioned
resources, those URLs used for HTTP-based repository access
- can be typed directly into a Web browser. Your browser will
- issue an HTTP <literal>GET</literal> request for that URL, and
+ can be typed directly into a web browser. Your browser will
+ issue an HTTP <literal>GET</literal> request for that URL;
based on whether that URL represents a versioned directory
- or file, mod_dav_svn will respond with a directory listing
- or with file contents.</para>
+ or file, <command>mod_dav_svn</command> will respond with a
+ directory listing or with file contents.</para>
<para>Since the URLs do not contain any information about
- which version of the resource you wish to see, mod_dav_svn
- will always answer with the youngest version. This
- functionality has the wonderful side-effect that you can
- pass around Subversion URLs to your peers as references to
- documents, and those URLs will always point at the latest
- manifestation of that document. Of course, you can even use
- the URLs as hyperlinks from other web sites, too.</para>
+ which version of the resource you wish to
+ see, <command>mod_dav_svn</command> will always answer with
+ the youngest version. This functionality has the wonderful
+ side effect that you can pass around Subversion URLs to your
+ peers as references to documents, and those URLs will always
+ point at the latest manifestation of that document. Of
+ course, you can even use the URLs as hyperlinks from other
+ web sites, too.</para>
<sidebar>
- <title>Can I view older revisions?</title>
+ <title>Can I View Older Revisions?</title>
<para>With an ordinary web browser? In one word: nope. At
least, not with <command>mod_dav_svn</command> as your
only tool.</para>
- <para>Your web browser only speaks ordinary HTTP. That
- means it only knows how to GET public URLs, which
+ <para>Your web browser speaks ordinary HTTP only. That
+ means it knows only how to GET public URLs, which
represent the latest versions of files and directories.
According to the WebDAV/DeltaV specification, each server
defines a private URL syntax for older versions of
@@ -2339,7 +2351,7 @@
web browser, however, you can use third-party software. A
good example of this is ViewVC (<ulink
url="http://viewvc.tigris.org/"/>). ViewVC was originally
- written to display CVS repositories through the web,
+ written to display CVS repositories through the Web,
<footnote>
<para>Back then, it was called <quote>ViewCVS</quote>.</para>
</footnote>
@@ -2348,7 +2360,7 @@
</sidebar>
<sect4 id="svn.serverconfig.httpd.extra.browsing.mimetype">
- <title>Proper MIME Type</title>
+ <title>Proper MIME type</title>
<para>When browsing a Subversion repository, the web browser
gets a clue about how to render a file's contents by
@@ -2365,33 +2377,32 @@
in the repository actually render as HTML when
browsing.</para>
- <para>To make this happen, you only need to make sure that
+ <para>To make this happen, you need only to make sure that
your files have the
proper <literal>svn:mime-type</literal> set. This is
discussed in more detail in
<xref linkend="svn.advanced.props.special.mime-type"/>,
and you can even configure your client to automatically
attach proper <literal>svn:mime-type</literal> properties
- to files entering the repository for the first time; see
+ to files entering the repository for the first time; see
<xref linkend="svn.advanced.props.auto"/>.</para>
<para>So in our example, if one were to set
the <literal>svn:mime-type</literal> property
to <literal>text/html</literal> on
file <filename>foo.html</filename>, then Apache would
- properly tell your web browser to render the file as
- HTML. One could also attach
- proper <literal>image/*</literal> mime-type properties to
- images, and by doing this, ultimately get an entire web
- site to be viewable directly from a repository! There's
- generally no problem with doing this, as long as the
- website doesn't contain any dynamically-generated
+ properly tell your web browser to render the file as HTML.
+ One could also attach proper <literal>image/*</literal>
+ mime-type properties to image files and ultimately get an
+ entire web site to be viewable directly from a repository!
+ There's generally no problem with this, as long as the web
+ site doesn't contain any dynamically generated
content.</para>
</sect4>
<sect4 id="svn.serverconfig.httpd.extra.browsing.xslt">
- <title>Customizing the Look</title>
+ <title>Customizing the look</title>
<para>You generally will get more use out of URLs to
versioned files—after all, that's where the
@@ -2404,10 +2415,10 @@
displays, Subversion provides an XML index feature. A
single <literal>SVNIndexXSLT</literal> directive in your
repository's <literal>Location</literal> block of
- <filename>httpd.conf</filename> will instruct mod_dav_svn
- to generate XML output when displaying a directory
- listing, and to reference the XSLT stylesheet of your
- choice:</para>
+ <filename>httpd.conf</filename> will
+ instruct <command>mod_dav_svn</command> to generate XML
+ outp