[svnbook commit] r3268 - trunk/src/de/book
jmfelderhoff
noreply at red-bean.com
Tue Aug 12 11:40:39 CDT 2008
Author: jmfelderhoff
Date: Tue Aug 12 11:40:38 2008
New Revision: 3268
Log:
foreword.xml:
ch00-preface.xml:
ch01-fundamental-concepts.xml:
ch02-basic-usage.xml:
ch03-advanced-topics.xml:
ch04-branching-and-merging.xml:
ch05-repository-admin.xml:
ch06-server-configuration.xml:
ch07-customizing-svn.xml:
ch08-embedding-svn.xml:
ch09-reference.xml:
appa-quickstart.xml:
appb-svn-for-cvs-users.xml:
appc-webdav.xml:
styles.css:
Merge changes of English version since r3206.
Modified:
trunk/src/de/book/appa-quickstart.xml
trunk/src/de/book/appb-svn-for-cvs-users.xml
trunk/src/de/book/appc-webdav.xml
trunk/src/de/book/ch00-preface.xml
trunk/src/de/book/ch01-fundamental-concepts.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/ch05-repository-admin.xml
trunk/src/de/book/ch06-server-configuration.xml
trunk/src/de/book/ch07-customizing-svn.xml
trunk/src/de/book/ch08-embedding-svn.xml
trunk/src/de/book/ch09-reference.xml
trunk/src/de/book/foreword.xml
trunk/src/de/book/styles.css
Modified: trunk/src/de/book/appa-quickstart.xml
==============================================================================
--- trunk/src/de/book/appa-quickstart.xml (original)
+++ trunk/src/de/book/appa-quickstart.xml Tue Aug 12 11:40:38 2008
@@ -4,7 +4,7 @@
<para>If you're eager to get Subversion up and running (and you
- enjoy learning by experimentation), this chapter will show you how
+ enjoy learning by experimentation), this appendix will show you how
to create a repository, import code, and then check it back out
again as a working copy. Along the way, we give links to the
relevant chapters of this book.</para>
@@ -12,7 +12,7 @@
<warning>
<para>If you're new to the entire concept of version control or to
the <quote>copy-modify-merge</quote> model used by both CVS and
- Subversion, then you should read <xref linkend="svn.basic"/>
+ Subversion, you should read <xref linkend="svn.basic"/>
before going any further.</para>
</warning>
@@ -31,11 +31,11 @@
management, and so on. While Subversion is able to use Apache
as one of its network server programs, its dependence on APR
<emphasis>does not</emphasis> mean that Apache is a required
- component. APR is a standalone library useable by any
+ component. APR is a standalone library usable by any
application. It does mean, however, that like Apache,
Subversion clients and servers run on any operating system that
- the Apache httpd server runs on: Windows, Linux, all flavors of
- BSD, Mac OS X, Netware, and others.</para>
+ the Apache <command>httpd</command> server runs on: Windows,
+ Linux, all flavors of BSD, Mac OS X, NetWare, and others.</para>
<para>The easiest way to get Subversion is to download a binary
package built for your operating system. Subversion's web site
@@ -47,11 +47,11 @@
system (RPMs, DEBs, the ports tree, etc.) to get
Subversion.</para>
- <para>Alternately, you can build Subversion directly from source
+ <para>Alternatively, you can build Subversion directly from source
code, though it's not always an easy task. (If you're not
experienced at building open source software packages, you're
probably better off downloading a binary distribution instead!)
- From the Subversion web site, download the latest source-code
+ From the Subversion web site, download the latest source code
release. After unpacking it, follow the instructions in
the <filename>INSTALL</filename> file to build it. Note that a
released source package may not contain everything you need to
@@ -65,8 +65,8 @@
directory where you unpacked the main Subversion source.
Regardless, it's possible that you may want to fetch other
optional dependencies such as Berkeley DB and possibly Apache
- httpd. If you want to do a complete build, make sure you have
- all of the packages documented in
+ <command>httpd</command>. If you want to do a complete build,
+ make sure you have all of the packages documented in
the <filename>INSTALL</filename> file.</para>
<para>If you're one of those folks that likes to use bleeding-edge
@@ -112,7 +112,7 @@
<!-- ================================================================= -->
<sect1 id="svn.intro.quickstart">
- <title>High-speed Tutorial</title>
+ <title>High-Speed Tutorial</title>
<blockquote>
<para><quote>Please make sure your seat backs are in their full,
@@ -122,7 +122,7 @@
<para>What follows is a quick tutorial that walks you through some
basic Subversion configuration and operation. When you finish
- it, you should have a basic understanding of Subversion's
+ it, you should have a general understanding of Subversion's
typical usage.</para>
<note>
@@ -130,9 +130,9 @@
<command>svn</command>, the Subversion command-line client,
and <command>svnadmin</command>, the administrative tool,
ready to go on a Unix-like operating system. (This tutorial
- also works at the Windows commandline prompt, assuming you
+ also works at the Windows command-line prompt, assuming you
make some obvious tweaks.) We also assume you are using
- Subversion 1.2 or later (run <command>svn --version</command>
+ Subversion 1.2 or later (run <userinput>svn --version</userinput>
to check.)</para>
</note>
@@ -158,16 +158,16 @@
that can hold anything you wish. Some administrators prefer to
store only one project in a repository, and others prefer to
store multiple projects in a repository by placing them into
- separate directories. The merits of each approach are discussed
+ separate directories. We discuss the merits of each approach
in <xref linkend="svn.reposadmin.projects.chooselayout"/>.
Either way, the repository manages only files and directories,
so it's up to humans to interpret particular directories as
- <quote>projects</quote>. So while you might see references to
+ <quote>projects.</quote> So while you might see references to
projects throughout this book, keep in mind that we're only ever
talking about some directory (or collection of directories) in
the repository.</para>
- <para>In this example, we assume that you already have some sort
+ <para>In this example, we assume you already have some sort
of project (a collection of files and directories) that you wish
to import into your newly created Subversion repository. Begin
by organizing your data into a single directory called
@@ -177,8 +177,8 @@
directories named <filename>branches</filename>,
<filename>tags</filename>, and <filename>trunk</filename>. The
<filename>trunk</filename> directory should contain all of your
- data, while the <filename>branches</filename> and
- <filename>tags</filename> directories are empty:</para>
+ data, and the <filename>branches</filename> and
+ <filename>tags</filename> directories should be empty:</para>
<screen>
/tmp/myproject/branches/
@@ -221,7 +221,7 @@
<para>Note that the original <filename>/tmp/myproject</filename>
directory is unchanged; Subversion is unaware of it. (In fact,
- you can even delete that directory if you wish.) In order to
+ you can even delete that directory if you wish.) To
start manipulating repository data, you need to create a new
<quote>working copy</quote> of the data, a sort of private
workspace. Ask Subversion to <quote>check out</quote> a working
@@ -248,15 +248,15 @@
contents.</para>
</listitem>
<listitem>
- <para>Run <command>svn diff</command> to see unified diff
+ <para>Run <userinput>svn diff</userinput> to see unified diff
output of your changes.</para>
</listitem>
<listitem>
- <para>Run <command>svn commit</command> to commit the new
+ <para>Run <userinput>svn commit</userinput> to commit the new
version of your file to the repository.</para>
</listitem>
<listitem>
- <para>Run <command>svn update</command> to bring your working
+ <para>Run <userinput>svn update</userinput> to bring your working
copy <quote>up to date</quote> with the repository.</para>
</listitem>
</itemizedlist>
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 Tue Aug 12 11:40:38 2008
@@ -4,7 +4,7 @@
<para>This appendix is a guide for CVS users new to Subversion.
It's essentially a list of differences between the two systems
as <quote>viewed from 10,000 feet.</quote> For each section, we
- provide backreferences to relevant chapters when
+ provide references to relevant chapters when
possible.</para>
<para>Although the goal of Subversion is to take over the current
@@ -30,7 +30,7 @@
filesystem. Each commit results in an entirely new filesystem
tree; in essence, the repository is an array of trees. Each of
these trees is labeled with a single revision number. When
- someone talks about <quote>revision 54</quote>, they're talking
+ someone talks about <quote>revision 54</quote>, he's talking
about a particular tree (and indirectly, the way the filesystem
looked after the 54th commit).</para>
@@ -84,8 +84,8 @@
<emphasis>not</emphasis> cause any kind of immediate change
in the repository. Instead, the working items are simply
<quote>scheduled</quote> for addition or deletion. No
- repository changes happen until you run <command>svn
- commit</command>.</para>
+ repository changes happen until you run <userinput>svn
+ commit</userinput>.</para>
</listitem>
<listitem>
<para>Directories aren't dumb containers anymore; they have
@@ -114,7 +114,7 @@
<para>Subversion deals with this problem by quietly tracking
committed adds and deletes in the <filename>.svn</filename>
- area. When you eventually run <command>svn update</command>,
+ area. When you eventually run <userinput>svn update</userinput>,
all accounts are settled with the repository, and the
directory's new revision number is set correctly.
<emphasis>Therefore, only after an update is it truly safe to
@@ -152,7 +152,7 @@
serves the same purpose as the <filename>CVS</filename>
directory, except that it also stores read-only,
<quote>pristine</quote> copies of your files. This allows you
- to do much things offline:</para>
+ to do many things offline:</para>
<variablelist>
@@ -187,9 +187,9 @@
<para>The last subcommand in the list—<command>svn
revert</command>—is new. It will not only remove local
- changes, but it will also unschedule operations such as adds and
- deletes. While deleting the file and then running <command>svn
- update</command> will still work, doing so distorts the true
+ changes, but also unschedule operations such as adds and
+ deletes. Although deleting the file and then running <userinput>svn
+ update</userinput> will still work, doing so distorts the true
purpose of updating. And, while we're on this subject…
</para>
@@ -211,8 +211,8 @@
copy, and second, to show the user which files are out of date.
Unfortunately, because of CVS's hard-to-read status output, many
CVS users don't take advantage of this command at all. Instead,
- they've developed a habit of running <command>cvs
- update</command> or <command>cvs -n update</command> to quickly
+ they've developed a habit of running <userinput>cvs
+ update</userinput> or <userinput>cvs -n update</userinput> to quickly
see their changes. If users forget to use
the <option>-n</option> option, this has the side effect of
merging repository changes they may not be ready to deal
@@ -258,7 +258,7 @@
</varlistentry>
</variablelist>
- <para>The <command>status</command> command has two output
+ <para>The <command>svn status</command> command has two output
formats. In the default <quote>short</quote> format, local
modifications look like this:</para>
@@ -313,7 +313,7 @@
X Resource is eXternal to this working copy (may come from another
repository). See <xref linkend="svn.advanced.externals" />
? Resource is not under version control
-! Resource is missing or incomplete (removed by another tool than
+! Resource is missing or incomplete (removed by a tool other than
Subversion)
</screen>
@@ -402,7 +402,7 @@
<title>Conflict Resolution</title>
<para>CVS marks conflicts with inline <quote>conflict
- markers</quote>, and then prints a <literal>C</literal> during
+ markers,</quote> and then prints a <literal>C</literal> during
an update or merge operation. Historically, this has caused
problems, because CVS isn't doing enough. Many users forget
about (or don't see) the <literal>C</literal> after it whizzes
@@ -414,7 +414,7 @@
when a conflict occurs in a file, Subversion records the fact
that the file is in a state of conflict, and won't allow you to
commit changes to that file until you explicitly resolve the
- conflict. Secondly, Subversion 1.5 provides interactive
+ conflict. Second, Subversion 1.5 provides interactive
conflict resolution, which allows you to resolve conflicts as
they happen instead of having to go back and do so after the
update or merge operation completes. See <xref
@@ -434,17 +434,17 @@
only store successive full copies of a changing binary file.
Subversion, however, expresses differences between files using a
binary differencing algorithm, regardless of whether they
- contain textual or binary data. That means that all files are
+ contain textual or binary data. That means all files are
stored differentially (compressed) in the repository.</para>
<para>CVS users have to mark binary files with
- <option>-kb</option> flags in order to prevent data from being
+ <option>-kb</option> flags to prevent data from being
garbled (due to keyword expansion and line-ending translations).
They sometimes forget to do this.</para>
- <para>Subversion takes the more paranoid route—first, it never
+ <para>Subversion takes the more paranoid route. First, it never
performs any kind of keyword or line-ending translation unless
- you explicitly ask it do so (see <xref
+ you explicitly ask it to do so (see <xref
linkend="svn.advanced.props.special.keywords"/> and <xref
linkend="svn.advanced.props.special.eol-style"/> for more details). By default,
Subversion treats all file data as literal byte strings, and
@@ -461,7 +461,7 @@
<para>To determine whether a contextual merge is possible,
Subversion examines the <literal>svn:mime-type</literal>
property. If the file has no <literal>svn:mime-type</literal>
- property, or has a mime-type that is textual (e.g.,
+ property, or has a MIME type that is textual (e.g.,
<literal>text/*</literal>),
Subversion assumes it is text. Otherwise, Subversion assumes
the file is binary. Subversion also helps users by running a
@@ -482,8 +482,8 @@
<title>Versioned Modules</title>
<para>Unlike CVS, a Subversion working copy is aware that it has
- checked out a module. That means that if somebody changes the
- definition of a module (e.g., adds or removes components), then a
+ checked out a module. That means if somebody changes the
+ definition of a module (e.g., adds or removes components), a
call to <command>svn update</command> will update the working
copy appropriately, adding and removing components.</para>
@@ -542,18 +542,18 @@
is an extremely difficult problem to solve; it involves
deducing changesets in the absence of atomicity and translating
between the systems' completely orthogonal branching policies,
- among other complications. Still, there are a handful of tools
- claiming to at least partially support the ability to convert
+ among other complications. Still, a handful of tools claim
+ to at least partially support the ability to convert
existing CVS repositories into Subversion ones.</para>
- <para>The most popular (and most mature) conversion tool is
+ <para>The most popular (and mature) conversion tool is
cvs2svn (<ulink url="http://cvs2svn.tigris.org/"/>), a Python
script originally created by members of Subversion's own
development community. This tool is meant to run exactly once:
it scans your CVS repository multiple times and attempts to
deduce commits, branches, and tags as best it can. When it
- finishes, the result is a either a Subversion repository or a
- portable Subversion dumpfile representing your code's history.
+ finishes, the result is either a Subversion repository or a
+ portable Subversion dump file representing your code's history.
See the web site for detailed instructions and caveats.</para>
</sect1>
Modified: trunk/src/de/book/appc-webdav.xml
==============================================================================
--- trunk/src/de/book/appc-webdav.xml (original)
+++ trunk/src/de/book/appc-webdav.xml Tue Aug 12 11:40:38 2008
@@ -3,11 +3,11 @@
<para>WebDAV is an extension to HTTP, and it is growing more and more
popular as a standard for file sharing. Today's operating systems
- are becoming extremely Web-aware, and many now have built-in
+ are becoming extremely web-aware, and many now have built-in
support for mounting <quote>shares</quote> exported by WebDAV
servers.</para>
- <para>If you use Apache as your Subversion network server, then to
+ <para>If you use Apache as your Subversion network server, to
some extent you are also running a WebDAV server. This appendix
gives some background on the nature of this protocol, how
Subversion uses it, and how well Subversion interoperates with
@@ -23,7 +23,7 @@
<para><firstterm>DAV</firstterm> stands for <quote>Distributed
Authoring and Versioning.</quote> RFC 2518 defines a set of
concepts and accompanying extension methods to HTTP 1.1 that
- make the Web into a more universal read/write medium. The basic
+ make the Web a more universal read/write medium. The basic
idea is that a WebDAV-compliant web server can act like a
generic file server; clients can <quote>mount</quote> shared
folders over HTTP that behave much like other network
@@ -48,11 +48,11 @@
Every modern computer operating system has a general WebDAV
client built in (details to follow), and a number of popular
standalone applications are also able to speak
- WebDAV—Microsoft Office, Dreamweaver, and Photoshop to
+ WebDAV—Microsoft Office, Dreamweaver, and Photoshop, to
name a few. On the server end, Apache HTTP Server has been
able to provide WebDAV services since 1998 and is considered the
- de-facto open source standard. There are several other
- commercial WebDAV servers available, including Microsoft's own
+ de facto open source standard. Several other
+ commercial WebDAV servers are available, including Microsoft's own
IIS.</para>
<para>DeltaV, unfortunately, has not been so successful. It's
@@ -62,7 +62,7 @@
entirely clear as to why DeltaV has remained stagnant. Some
opine that the specification is just too complex. Others argue
that while WebDAV's features have mass appeal (even the least
- technical users appreciate network file sharing), version
+ technical users appreciate network file sharing), its version
control features just aren't interesting or necessary for most
users. Finally, some believe that DeltaV remains unpopular
because there's still no open source server product that
@@ -89,7 +89,7 @@
<para>Second, <command>mod_dav_svn</command> is not a
fully realized DeltaV server. Many portions of the DeltaV
- specification were irrelevant to Subversion, and thus left
+ specification were irrelevant to Subversion, and thus were left
unimplemented.</para>
<para>There is still some debate in the developer community as to
@@ -111,8 +111,8 @@
<sect1 id="svn.webdav.autoversioning">
<title>Autoversioning</title>
- <para>While the Subversion client is not a full DeltaV client, nor
- the Subversion server a full DeltaV server, there's still a
+ <para>While the Subversion client is not a full DeltaV client, and
+ the Subversion server is not a full DeltaV server, there's still a
glimmer of WebDAV interoperability to be happy about:
<firstterm>autoversioning</firstterm>.</para>
@@ -124,8 +124,8 @@
versioning requests: something like
<literal>MKACTIVITY</literal>, <literal>CHECKOUT</literal>,
<literal>PUT</literal>, <literal>CHECKIN</literal>. But if the
- DeltaV server supports autoversioning, then write requests from
- basic WebDAV clients are accepted. The server behaves as if the
+ DeltaV server supports autoversioning, write requests from
+ basic WebDAV clients are accepted. The server behaves as though the
client <emphasis>had</emphasis> issued the proper series of
versioning requests, performing a commit under the hood. In
other words, it allows a DeltaV server to interoperate with
@@ -137,8 +137,8 @@
Imagine an office of ordinary users running Microsoft Windows or
Mac OS. Each user <quote>mounts</quote> the Subversion
repository, which appears to be an ordinary network folder.
- They use the shared folder as they always do: open files, edit
- them, save them. Meanwhile, the server is automatically
+ They use the shared folder as they always do: open files, edit
+ them, and save them. Meanwhile, the server is automatically
versioning everything. Any administrator (or knowledgeable
user) can still use a Subversion client to search history and
retrieve older versions of data.</para>
@@ -171,7 +171,7 @@
0-byte file (as a way of reserving a name) followed by another
<literal>PUT</literal> with the real file data. The single
file-write results in two separate commits. Also consider that
- many applications autosave every few minutes, resulting in even
+ many applications auto-save every few minutes, resulting in even
more commits.</para>
<para>If you have a post-commit hook program that sends email, you
@@ -180,7 +180,7 @@
think the influx of emails will still prove to be valuable
notifications or not. Also, a smart post-commit hook program
can distinguish between a transaction created via autoversioning
- and one created through a normal <command>svn commit</command>.
+ and one created through a normal Subversion commit operation.
The trick is to look for a revision property
named <literal>svn:autoversioned</literal>. If present, the
commit was made by a generic WebDAV client.</para>
@@ -190,7 +190,7 @@
<literal>mod_mime</literal> module. If a WebDAV client adds a
new file to the repository, there's no opportunity for the user
to set the the <literal>svn:mime-type</literal> property. This
- might cause the file to appear as generic icon when viewed
+ might cause the file to appear as a generic icon when viewed
within a WebDAV shared folder, not having an association with
any application. One remedy is to have a sysadmin (or other
Subversion-knowledgeable person) check out a working copy and
@@ -212,10 +212,10 @@
</screen>
<para>This directive allows <literal>mod_mime</literal> to attempt
- automatic deduction of the mime-type on new files that enter the
+ automatic deduction of the MIME type on new files that enter the
repository via autoversioning. The module looks at the file's
named extension and possibly the contents as well; if the file
- matches some common patterns, then the the
+ matches some common patterns, the
file's <literal>svn:mime-type</literal> property will be set
automatically.</para>
@@ -233,8 +233,8 @@
broadly define the types of WebDAV functionality available to
users. <xref linkend="svn.webdav.clients.tbl-1"/> gives our
categorization as well as a quick description of some common pieces of
- WebDAV-enabled software. More details about these software
- offerings, as well as their general category, can be found in
+ WebDAV-enabled software. You can find more details about these software
+ offerings, as well as their general category, in
the sections that follow.</para>
<table id="svn.webdav.clients.tbl-1">
@@ -258,16 +258,16 @@
<entry></entry>
<entry></entry>
<entry>Image editing software, allowing direct opening
- from, and writing to, WebDAV URLs.</entry>
+ from, and writing to, WebDAV URLs</entry>
</row>
<row>
- <entry>Cadaver</entry>
+ <entry>cadaver</entry>
<entry>Standalone WebDAV application</entry>
<entry></entry>
<entry>X</entry>
<entry>X</entry>
<entry>Command-line WebDAV client supporting file
- transfer, tree, and locking operations.</entry>
+ transfer, tree, and locking operations</entry>
</row>
<row>
<entry>DAV Explorer</entry>
@@ -275,7 +275,7 @@
<entry>X</entry>
<entry>X</entry>
<entry>X</entry>
- <entry>Java GUI tool for exploring WebDAV shares.</entry>
+ <entry>Java GUI tool for exploring WebDAV shares</entry>
</row>
<row>
<entry>Macromedia Dreamweaver</entry>
@@ -284,7 +284,7 @@
<entry></entry>
<entry></entry>
<entry>Web production software able to directly read from
- and write to WebDAV URLs.</entry>
+ and write to WebDAV URLs</entry>
</row>
<row>
<entry>Microsoft Office</entry>
@@ -294,7 +294,7 @@
<entry></entry>
<entry>Office productivity suite with several components
able to directly read from and write to WebDAV
- URLs.</entry>
+ URLs</entry>
</row>
<row>
<entry>Microsoft Web Folders</entry>
@@ -303,7 +303,7 @@
<entry></entry>
<entry></entry>
<entry>GUI file explorer program able to perform tree
- operations on a WebDAV share.</entry>
+ operations on a WebDAV share</entry>
</row>
<row>
<entry>GNOME Nautilus</entry>
@@ -312,7 +312,7 @@
<entry></entry>
<entry>X</entry>
<entry>GUI file explorer able to perform tree
- operations on a WebDAV share.</entry>
+ operations on a WebDAV share</entry>
</row>
<row>
<entry>KDE Konqueror</entry>
@@ -321,7 +321,7 @@
<entry></entry>
<entry>X</entry>
<entry>GUI file explorer able to perform tree
- operations on a WebDAV share.</entry>
+ operations on a WebDAV share</entry>
</row>
<row>
<entry>Mac OS X</entry>
@@ -329,8 +329,8 @@
<entry></entry>
<entry>X</entry>
<entry></entry>
- <entry>Operating system has built-in support for mounting
- WebDAV shares..</entry>
+ <entry>Operating system that has built-in support for mounting
+ WebDAV shares.</entry>
</row>
<row>
<entry>Novell NetDrive</entry>
@@ -339,7 +339,7 @@
<entry></entry>
<entry></entry>
<entry>Drive-mapping program for assigning Windows drive
- letters to a mounted remote WebDAV share.</entry>
+ letters to a mounted remote WebDAV share</entry>
</row>
<row>
<entry>SRT WebDrive</entry>
@@ -349,7 +349,7 @@
<entry></entry>
<entry>File transfer software, which, among other things,
allows the assignment of Windows drive letters to a
- mounted remote WebDAV share.</entry>
+ mounted remote WebDAV share</entry>
</row>
<row>
<entry>davfs2</entry>
@@ -357,8 +357,8 @@
<entry></entry>
<entry></entry>
<entry>X</entry>
- <entry>Linux file system driver that allows you to mount a
- WebDAV share.</entry>
+ <entry>Linux filesystem driver that allows you to mount a
+ WebDAV share</entry>
</row>
</tbody>
@@ -377,12 +377,12 @@
<sect3 id="svn.webdav.clients.standalone.windows">
<title>Microsoft Office, Dreamweaver, Photoshop</title>
- <para>On Windows, there are several well-known applications
- that contain integrated WebDAV client functionality, such as
+ <para>On Windows, several well-known applications
+ contain integrated WebDAV client functionality, such as
Microsoft's Office,
<footnote>
<para>WebDAV support was removed from Microsoft Access for
- some reason, but exists in the rest of the Office
+ some reason, but it exists in the rest of the Office
suite.</para>
</footnote>
Adobe's Photoshop, and Macromedia's Dreamweaver programs.
@@ -390,7 +390,7 @@
make heavy use of WebDAV locks when editing a file.</para>
<para>Note that while many of these programs also exist for
- the Mac OS X, they do not appear to support WebDAV directly
+ Mac OS X, they do not appear to support WebDAV directly
on that platform. In fact, on Mac OS X, the
<guimenu>File→Open</guimenu> dialog box doesn't allow
one to type a path or URL at all. It's likely that the
@@ -415,8 +415,8 @@
<para>Using cadaver is similar to using a command-line FTP
program, and thus it's extremely useful for basic WebDAV
debugging. It can be used to upload or download files in a
- pinch, and also to examine properties, and to copy, move,
- lock or unlock files:</para>
+ pinch, to examine properties, and to copy, move,
+ lock, or unlock files:</para>
<screen>
$ cadaver http://host/repos
@@ -461,14 +461,14 @@
<title>File-Explorer WebDAV Extensions</title>
<para>Some popular file explorer GUI programs support WebDAV
- extensions that allow a user to browse a DAV share as if it
+ extensions that allow a user to browse a DAV share as though it
was just another directory on the local computer, and to
perform basic tree editing operations on the items in that
share. For example, Windows Explorer is able to browse a
WebDAV server as a <quote>network place.</quote> Users can
drag files to and from the desktop, or can rename, copy, or
delete files in the usual way. But because it's only a
- feature of the file-explorer, the DAV share isn't visible to
+ feature of the file explorer, the DAV share isn't visible to
ordinary applications. All DAV interaction must happen
through the explorer interface.</para>
@@ -479,14 +479,14 @@
<para>Microsoft was one of the original backers of the WebDAV
specification, and first started shipping a client in
Windows 98, which was known as Web Folders. This client was
- also shipped in Windows NT4 and 2000.</para>
+ also shipped in Windows NT 4.0 and Windows 2000.</para>
<para>The original Web Folders client was an extension to
Explorer, the main GUI program used to browse filesystems. It
works well enough. In Windows 98, the feature might need to
be explicitly installed if Web Folders aren't already visible
inside My Computer. In Windows 2000, simply
- add a new <quote>network place</quote>, enter the URL, and the
+ add a new <quote>network place,</quote> enter the URL, and the
WebDAV share will pop up for browsing.</para>
<para>With the release of Windows XP, Microsoft started shipping
@@ -494,21 +494,22 @@
Mini-Redirector. The new implementation is a
filesystem-level client, allowing WebDAV shares to be mounted
as drive letters. Unfortunately, this implementation is
- incredibly buggy. The client usually tries to convert http
+ incredibly buggy. The client usually tries to convert HTTP
URLs (<literal>http://host/repos</literal>) into UNC share
notation (<literal>\\host\repos</literal>); it also often
tries to use Windows Domain authentication to respond to
basic-auth HTTP challenges, sending usernames as
<literal>HOST\username</literal>. These interoperability
- problems are severe and documented in numerous places around
+ problems are severe and are documented in numerous places around
the Web, to the frustration of many users. Even Greg Stein,
the original author of Apache's WebDAV module, bluntly
states that XP Web Folders simply can't operate against an Apache
server.</para>
- <para>Windows Vista's implementation of Web Folders seems to
+ <para>Windows Vista's initial implementation of Web Folders seems to
be almost the same as XP's, so it has the same sort of
- problems (at the time of writing).</para>
+ problems. With luck, Microsoft will remedy these issues in
+ a Vista Service Pack.</para>
<para>However, there seem to be workarounds for both XP and
Vista that allow Web Folders to work against Apache. Users
@@ -524,8 +525,8 @@
Places and adding a new network place. When prompted,
enter the URL of the repository, but <emphasis>include a
port number</emphasis> in the URL. For
- example, <uri>http://host/repos</uri> should be
- entered as <uri>http://host:80/repos</uri> instead.
+ example, you should enter <userinput>http://host/repos</userinput>
+ as <userinput>http://host:80/repos</userinput> instead.
Respond to any authentication prompts with your Subversion
credentials.</para>
@@ -537,9 +538,9 @@
unless the connection happens
over <literal>https://</literal>. If you're unable to connect
to the Subversion repository via SSL, you can tweak the
- system registry to turn off this behavior. Just set the
- key <literal>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters\BasicAuthLevel</literal>
- from 1 to 2. A final warning: be sure to set up the Web
+ system registry to turn off this behavior. Just change the
+ value of the <literal>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters\BasicAuthLevel</literal>
+ key from <userinput>1</userinput> to <userinput>2</userinput>. A final warning: be sure to set up the Web
Folder to point to the repository's root directory
(<filename>/</filename>), rather than some subdirectory
such as <filename>/trunk</filename>. Vista Web Folders
@@ -573,9 +574,9 @@
an <literal>http://</literal> URL, Konqueror will behave
like an ordinary web browser. You'll likely see the generic
HTML directory listing produced
- by <command>mod_dav_svn</command>. By entering
- <literal>webdav://host/repos</literal> instead of
- <literal>http://host/repos</literal>, Konqueror becomes a
+ by <command>mod_dav_svn</command>. When you enter
+ <userinput>webdav://host/repos</userinput> instead of
+ <userinput>http://host/repos</userinput>, Konqueror becomes a
WebDAV client and displays the repository as a
filesystem.</para>
@@ -590,7 +591,7 @@
filesystem module, typically within the operating system's
kernel. This means that the DAV share is mounted like any
other network filesystem, similar to mounting an NFS share on
- Unix or attaching an SMB share as drive letter in Windows.
+ Unix or attaching an SMB share as a drive letter in Windows.
As a result, this sort of client provides completely
transparent read/write WebDAV access to all programs.
Applications aren't even aware that WebDAV requests are
@@ -603,12 +604,12 @@
<para>Both WebDrive and NetDrive are excellent commercial
products that allow a WebDAV share to be attached as drive
letters in Windows. As a result, you can operate on the
- contents of these WebDAV-backed pseudo-drives as easily as
+ contents of these WebDAV-backed pseudodrives as easily as
you can against real local hard drives, and in the same
- ways. WebDrive can be purchased from South River
+ ways. You can purchase WebDrive from South River
Technologies (<ulink url="http://www.southrivertech.com"/>).
Novell's NetDrive is freely available online, but requires
- users to have a Netware license.</para>
+ users to have a NetWare license.</para>
</sect3>
@@ -632,14 +633,14 @@
<para>Note that if your <command>mod_dav_svn</command> is
older than version 1.2, OS X will refuse to mount the share
- as read-write; it will appear as read-only. This is because
- OS X insists on locking support for read-write shares, and
+ as read/write; it will appear as read-only. This is because
+ OS X insists on locking support for read/write shares, and
the ability to lock files first appeared in Subversion
1.2.</para>
<para>Also, OS X's WebDAV client can sometimes be overly
sensitive to HTTP redirects. If OS X is unable to mount the
- repository at all, you may need to enable the BrowserMatch
+ repository at all, you may need to enable the <literal>BrowserMatch</literal>
directive in the Apache server's
<filename>httpd.conf</filename>:</para>
@@ -654,9 +655,9 @@
<title>Linux davfs2</title>
<para>Linux davfs2 is a filesystem module for the Linux kernel,
- whose development is located at <ulink
- url="http://dav.sourceforge.net/"/>. Once installed, a WebDAV
- network share can be mounted with the usual Linux mount
+ whose development is organized at <ulink
+ url="http://dav.sourceforge.net/"/>. Once you install
+ davfs2, you can mount a WebDAV network share using the usual Linux mount
command:</para>
<screen>
Modified: trunk/src/de/book/ch00-preface.xml
==============================================================================
--- trunk/src/de/book/ch00-preface.xml (original)
+++ trunk/src/de/book/ch00-preface.xml Tue Aug 12 11:40:38 2008
@@ -38,7 +38,7 @@
its nonrestrictive modus operandi and support for networked
operation allowed dozens of geographically dispersed programmers
to share their work. It fit the collaborative nature of the
- opensource world very well. CVS and its semi-chaotic development
+ open source world very well. CVS and its semi-chaotic development
model have since become cornerstones of open source
culture.</para>
-->
@@ -59,7 +59,7 @@
<!--
<para>But CVS was not without its flaws, and simply fixing those
flaws promised to be an enormous effort. Enter Subversion.
- Designed to be a successor to CVS, Subversion's originators set
+ Subversion was designed to be a successor to CVS, and its originators set
out to win the hearts of CVS users in two ways—by creating
an open source system with a design (and <quote>look and
feel</quote>) similar to CVS, and by attempting to avoid most of
@@ -72,8 +72,8 @@
<para>Jedoch war CVS nicht makellos, und diese Makel einfach zu
beseitigen, versprach einen enormen Aufwand. Bühne frei für
- Subversion. Als Nachfolger für CVS entworfen, zogen die Schöpfer
- von Subversion los, um auf zwei Wegen die Herzen der CVS-Benutzer
+ Subversion. Subversion wurde als Nachfolger für CVS entworfen, und seine Schöpfer
+ zogen los, um auf zwei Wegen die Herzen der CVS-Benutzer
zu gewinnen—indem ein Open-Source-System erschaffen wurde,
dessen Design (und <quote>look and feel</quote>) ähnlich wie CVS
war, und indem versucht wurde, die auffälligsten Makel von CVS zu
@@ -86,8 +86,8 @@
<para>This book is written to document the 1.5 series of the
Subversion version control system. We have made every attempt to
be thorough in our coverage. However, Subversion has a thriving
- and energetic development community, so there are already a number
- of features and improvements planned for future versions that may
+ and energetic development community, so already a number
+ of features and improvements are planned for future versions that may
change some of the commands and specific notes in this
book.</para>
-->
@@ -187,7 +187,7 @@
<para>Note also that the source code examples used throughout the
book are only examples. While they will compile with the proper
compiler incantations, they are intended to illustrate a
- particular scenario and not necessarily serve as examples of good
+ particular scenario and not necessarily to serve as examples of good
programming style or practices.</para>
-->
<para>Es sei angemerkt, dass es sich bei den Quelltexten in diesem
@@ -213,12 +213,12 @@
or to <firstterm>bottom-up</firstterm> learners. A top-down
learner prefers to read or skim documentation, getting a large
overview of how the system works; only then does she actually
- start using the software. A bottom-learner is a <quote>learn by
+ start using the software. A bottom-up learner is a <quote>learn by
doing</quote> person—someone who just wants to dive into the
software and figure it out as she goes, referring to book
sections when necessary. Most books tend to be written for one
type of person or the other, and this book is undoubtedly biased
- towards top-down learners. (And if you're actually reading this
+ toward top-down learners. (And if you're actually reading this
section, you're probably already a top-down learner yourself!)
However, if you're a bottom-up person, don't despair. While the
book may be laid out as a broad survey of Subversion topics, the
@@ -270,7 +270,7 @@
<variablelist>
<varlistentry>
<!--
- <term>Experienced System Administrators</term>
+ <term>Experienced system administrators</term>
<listitem>
<para>The assumption here is that you've probably used
version control before and are dying to get a
@@ -380,7 +380,7 @@
<!--
<para>The book ends with reference material—<xref
linkend="svn.ref"/> is a reference guide for all Subversion
- commands, and the appendices cover a number of useful topics.
+ commands, and the appendixes cover a number of useful topics.
These are the chapters you're mostly likely to come back to
after you've finished the book.</para>
</variablelist>
@@ -401,112 +401,111 @@
<sect1 id="svn.preface.conventions">
<!--
<title>Conventions Used in This Book</title>
-
- <para>This section covers the various conventions used in this
- book.</para>
-->
<title>Konventionen in diesem Buch</title>
- <para>Dieser Abschnitt behandelt die in diesem Buch gebräuchlichen
- Konventionen.</para>
- <!-- =============================================================== -->
- <sect2 id="svn.preface.conventions.typo">
<!--
- <title>Typographic Conventions</title>
+ <para>The following typographic conventions are used in this
+ book</para>:
-->
- <title>Typografische Konventionen</title>
+ <para>Die folgenden typografischen Konventionen weden in diesem
+ Buch verwendet:</para>
-<!--
- <para>The following typographic conventions are used in this
- book:</para>
--->
- <para>Die folgenden typographischen Konventionen werden in
- diesem Buch verwendet:</para>
-
- <variablelist>
-
- <varlistentry>
+ <variablelist>
+
+ <varlistentry>
<!--
- <term><command>Constant width</command></term>
--->
- <term><command>Festbreitenschrift</command></term>
- <listitem>
+ <term>
+ <userinput>Constant width</userinput>
+ </term>
+-->
+ <term>
+ <userinput>Festbreitenschrift</userinput>
+ </term>
+ <listitem>
<!--
- <para>Used for commands, command output, and options</para>
+ <para>Used for literal user input, command output, and
+ command-line options</para>
-->
- <para>Verwendet für Befehle, Befehlsausgaben und
- Optionen</para>
- </listitem>
- </varlistentry>
+ <para>Verwendet für Benutzereingaben, Befehlsausgaben und
+ Kommandozeilenoptionen</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
+ <varlistentry>
<!--
- <term><replaceable>Constant width italic</replaceable></term>
+ <term>
+ <filename>Italic</filename>
+ </term>
-->
- <term><replaceable>Kursive
- Festbreitenschrift</replaceable></term>
- <listitem>
+ <term><filename>Kursiv</filename></term>
+ <listitem>
<!--
- <para>Used for replaceable items in code and text</para>
+ <para>Used for program and Subversion tool subcommand
+ names, file and directory names, and new terms</para>
-->
- <para>Verwendet für zu ersetzende Objekte in Sourcecode
- und Text</para>
- </listitem>
- </varlistentry>
+ <para>Verwendet für Programm- und
+ Subversion-Unterbefehlsnamen, Datei und Verzeichnisnamen
+ und für neue Begriffe</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
+ <varlistentry>
<!--
- <term><filename>Italic</filename></term>
--->
- <term><filename>Kursivschrift</filename></term>
- <listitem>
+ <term>
+ <replaceable>Constant width italic</replaceable>
+ </term>
+-->
+ <term>
+ <replaceable>Kursive Festbreitenschrift</replaceable>
+ </term>
+ <listitem>
<!--
- <para>Used for file and directory names as well as for new
- terms</para>
+ <para>Used for replaceable items in code and text</para>
-->
- <para>Verwendet für Datei- und Verzeichnisnamen und neue Begriffe</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
+ <para>Verwendet für zu ersetzende Objekte in Code und Text</para>
+ </listitem>
+ </varlistentry>
- </sect2>
+ </variablelist>
- <!-- =============================================================== -->
- <sect2 id="svn.preface.conventions.icons">
<!--
- <title>Tips and Warnings</title>
+ <para>Also, we sprinkled especially helpful or important bits of
+ information throughout the book (in contextually relevant
+ locations), set off visually so they're easy to find. Look for
+ the following icons as you read:</para>
-->
- <title>Bilder</title>
+ <para>Desweiteren haben wir besonders hilfreiche oder wichtige
+ Informationshäppchen, der besseren Auffindbarkeit wegen optisch
+ hervorgehoben, über das gesamte Buch verteilt (dort, wo es
+ für den Zusammenhang bedeutsam ist). Achten Sie beim Lesen auf
+ die folgenden Icons:</para>
- <note>
+ <note>
<!--
- <para>This icon designates a note relating to the surrounding
- text.</para>
+ <para>This icon designates a special point of interest.</para>
-->
- <para>Dieses Bild markiert eine Anmerkung zum umgebenden
- Text.</para>
- </note>
+ <para>Dieses Bild markiert einen besonders wichtigen
+ Punkt.</para>
+ </note>
- <tip>
+ <tip>
<!--
- <para>This icon designates a helpful tip relating to the surrounding
- text.</para>
+ <para>This icon designates a helpful tip or recommended best
+ practice.</para>
-->
- <para>Dieses Bild markiert einen nützlichen Tipp zum
- umgebenden Text.</para>
- </tip>
+ <para>Dieses Bild markiert einen nützlichen Tipp oder eine
+ empfohlene Vorgehensweise.</para>
+ </tip>
- <warning>
+ <warning>
<!--
- <para>This icon designates a warning relating to the surrounding
- text.</para>
+ <para>This icon designates a warning. Pay close attention to
+ these to avoid running into problems.</para>
-->
- <para>Dieses Bild markiert eine Warnung zum umgebenden
- Text.</para>
- </warning>
-
- </sect2>
+ <para>Dieses Bild markiert eine Warnung. Beachten Sie diese
+ besonders, um Probleme zu vermeiden!</para>
+ </warning>
</sect1>
@@ -530,18 +529,6 @@
<variablelist>
<varlistentry>
- <term><xref linkend="svn.preface"/></term>
- <listitem>
-<!--
- <para>Covers the history of Subversion as well as its
- features, architecture, and components.</para>
--->
- <para>Behandelt die Geschichte von Subversion sowie seine
- Merkmale, Architektur und Bestandteile.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><xref linkend="svn.basic"/></term>
<listitem>
<!--
@@ -663,14 +650,14 @@
<para>Describes the internals of Subversion, the
Subversion filesystem, and the working copy
administrative areas from a programmer's point of view.
- Demonstrates how to use the public APIs to write a
+ It also demonstrates how to use the public APIs to write a
program that uses Subversion, and most importantly, how
to contribute to the development of Subversion.</para>
-->
<para>Beschreibt die Interna von Subversion, das
Subversion Dateisystem und die Verwaltungsbereiche der
Arbeitskopie aus der Sicht eines Programmierers.
- Hier wird gezeigt, wie die veröffentlichten APIs in
+ Hier wird auch gezeigt, wie die veröffentlichten APIs in
eines Programms das Subversion benutzt verwendet werden
und, was am wichtigsten ist, wie man zur
Weiterentwicklung von Subversion beitragen kann.</para>
@@ -750,8 +737,12 @@
<varlistentry>
<term><xref linkend="svn.copyright"/></term>
<listitem>
- <para>A copy of the Creative Commons Attribution License.,
+<!--
+ <para>A copy of the Creative Commons Attribution License,
under which this book is licensed.</para>
+-->
+ <para>Eine Kopie der Creative Commons Attribution License,
+ unter der dieses Buch lizensiert ist.</para>
</listitem>
</varlistentry>
@@ -774,8 +765,8 @@
Subversion project developers, which were then coalesced into a
single work and rewritten. As such, it has always been under a
free license (see <xref linkend="svn.copyright"/>). In fact,
- the book was written in the public eye, originally as a part of
- Subversion project itself. This means two things:</para>
+ the book was written in the public eye, originally as part of
+ the Subversion project itself. This means two things:</para>
-->
<para>Dieses Buch startete aus Dokumentationsschnipseln von
Entwicklern des Subversion Projektes, die in einem Werk
@@ -800,36 +791,36 @@
<para>You can make changes to this book and redistribute it
however you wish—it's under a free license. Your only
obligation is to maintain proper attribution to the original
- authors. Of course, rather than distribute your own private
- version of this book, we'd much rather you send feedback and
- patches to the Subversion developer community.</para>
+ authors. Of course, we'd much rather you send feedback and
+ patches to the Subversion developer community, instead of
+ distributing your private version of this book.</para>
-->
<para>Sie können an diesem Buch Änderungen vornehmen und es
wie auch immer weiterverteilen—es unterliegt einer
freien Lizenz. Ihre einzige Verpflichtung besteht darin, den
Hinweis auf die ursprünglichen Autoren beizubehalten.
- Natürlich würden wir es bevorzugen, wenn Sie statt eine
- eigene Version dieses Buches herauszugeben, Rückmeldungen
+ Natürlich würden wir es bevorzugen, wenn Sie Rückmeldungen
und Verbesserungen der Subversion Entwicklergemeinde
- zukommen ließen.</para>
+ zukommen ließen, anstatt Ihre Privatversion zu
+ verteilen.</para>
</listitem>
</itemizedlist>
<!-- O'REILLY SHOULD TWEAK THIS PARAGRAPH -->
<!--
<para>The online home of this book's development and most of the
- volunteer-driven translation efforts around it is
- <ulink url="http://svnbook.red-bean.com"/>. There, you can find
+ volunteer-driven translation efforts regarding it is
+ <ulink url="http://svnbook.red-bean.com"/>. There you can find
links to the latest releases and tagged versions of the book in
various formats, as well as instructions for accessing the
- book's Subversion repository (where lives its DocBook XML source
- code). Feedback is welcome—encouraged, even. Please
+ book's Subversion repository (where its DocBook XML source
+ code lives). Feedback is welcome—encouraged, even. Please
submit all comments, complaints, and patches against the book
sources to <email>svnbook-dev at red-bean.com</email>.</para>
-->
<para>Die Homepage der Entwicklungs- und Übersetzungsaktivitäten
auf freiwilliger Basis ist
- <ulink url="http://svnbook.red-bean.com"/>. dort finden Sie
+ <ulink url="http://svnbook.red-bean.com"/>. Dort finden Sie
Links auf die neuesten Releases und getagten Versionen des Buchs
in verschiedenen Formaten ebenso wie eine Anleitung, auf das
Subversion Repository des Buchs zuzugreifen (dort lebt sein
@@ -876,13 +867,13 @@
selbst zu schreiben.</para></footnote></para>
<!--
- <para>Thanks to O'Reilly and our editors: Chuck Toporek, Linda
- Mui, Tatiana Apandi, and Mary Brady. Their patience and support
+ <para>Thanks to O'Reilly and our various editors: Chuck Toporek, Linda
+ Mui, Tatiana Apandi, Mary Brady, and Mary Treseler. Their patience and support
has been tremendous.</para>
-->
- <para>Dank an O'Reilly und unsere Redakteure: Chuck Toporek, Linda
- Mui, Tatiana Apandi und Mary Brady für ihre Geduld und
- Unterstützung.</para>
+ <para>Dank an O'Reilly und unsere verschiedenen Redakteure: Chuck Toporek, Linda
+ Mui, Tatiana Apandi, Mary Brady und Mary Treseler. Ihre Geduld und
+ Unterstützung waren enorm.</para>
<!--
<para>Finally, we thank the countless people who contributed to
@@ -1042,7 +1033,7 @@
John Szakmeister,
Arfrever Frehtes Taifersar Arahesis,
Robert Tasarz,
- Michael W Thelen,
+ Michael W. Thelen,
Mason Thomas,
Erik van der Kolk,
Joshua Varner,
@@ -1219,7 +1210,7 @@
John Szakmeister,
Arfrever Frehtes Taifersar Arahesis,
Robert Tasarz,
- Michael W Thelen,
+ Michael W. Thelen,
Mason Thomas,
Erik van der Kolk,
Joshua Varner,
@@ -1246,8 +1237,8 @@
<!--
<para>Thanks to my wife Frances, who, for many months, got to
- hear, <quote>But honey, I'm still working on the book,</quote>
- rather than the usual, <quote>But honey, I'm still doing
+ hear <quote>But honey, I'm still working on the book,</quote>
+ rather than the usual <quote>But honey, I'm still doing
email.</quote> I don't know where she gets all that patience!
She's my perfect counterbalance.</para>
-->
@@ -1263,14 +1254,14 @@
<para>Thanks to my extended family and friends for their sincere
encouragement, despite having no actual interest in the
subject. (You know, the ones who say, <quote>Ooh, you wrote a
- book?</quote>, and then when you tell them it's a computer
+ book?</quote> and then when you tell them it's a computer
book, sort of glaze over.)</para>
-->
<para>Dank an meine Verwandtschaft und Freunde für ihre
aufrichtige Ermutigung, obwohl sie kein tatsächliches
Interesse an der Materie hatten. (Sie wissen schon,
- diejenigen, die sagen, <quote>Oh, du hast ein Buch
+ diejenigen, die sagen <quote>Oh, du hast ein Buch
geschrieben?</quote>, und wenn man ihnen erzählt, es sei ein
Computerbuch, die Nase rümpfen.</para>
@@ -1322,7 +1313,7 @@
Buch zu arbeiten.</para>
<!--
- <para>To Mike and Ben: It was a pleasure working with you on the
+ <para>To Mike and Ben: it was a pleasure working with you on the
book. Heck, it's a pleasure working with you at work!</para>
-->
<para>An Mike und Ben: Es war ein Vergnügen, mit euch am Buch zu
@@ -1341,7 +1332,7 @@
mindestens einem von euch lerne.</para>
<!--
- <para>Lastly, thanks to my Grandfather who always told me that
+ <para>Lastly, thanks to my grandfather, who always told me that
<quote>freedom equals responsibility.</quote> I couldn't agree
more.</para>
-->
@@ -1359,15 +1350,15 @@
<title>Von C. Michael Pilato</title>
<!--
- <para>Special thanks to Amy, my best friend and wife of nearly
+ <para>Special thanks to Amy, my best friend and wife of more than
ten incredible years, for her love and patient support, for
putting up with the late nights, and for graciously enduring
the version control processes I've imposed on her. Don't
- worry, Sweetheart—you'll be a TortoiseSVN wizard in no
+ worry, sweetheart—you'll be a TortoiseSVN wizard in no
time!</para>
-->
<para>Besonderen Dank an Amy, meiner besten Freundin und Ehefrau
- für fast zehn unglaubliche Jahre für ihre Liebe und geduldige
+ für mehr als zehn unglaubliche Jahre für ihre Liebe und geduldige
Unterstützung, dafür dass sie die langen Nächte und gnädig die
Versionskontrollprozesse ertrug, die ich ihr aufbürdete. Keine
Sorge, Liebling—binnen kurzer Zeit wirst du eine
@@ -1399,9 +1390,9 @@
<!--
<para>Hats off to Shep Kendall, through whom the world of
computers was first opened to me; Ben Collins-Sussman, my
- tour-guide through the open source world; Karl Fogel, you
+ tour guide through the open source world; Karl Fogel, you
<emphasis>are</emphasis> my <filename>.emacs</filename>; Greg
- Stein, for oozing practical programming know-how; Brian
+ Stein, for oozing practical programming know-how; and Brian
Fitzpatrick, for sharing this writing experience with me.
To the many folks from whom I am constantly picking up new
knowledge—keep dropping it!</para>
@@ -1410,7 +1401,7 @@
Computer eröffnete; Ben Collins-Sussman, mein Reiseführer
durch die Open-Source-Welt; Karl Fogel—du
<emphasis>bist</emphasis> mein <filename>.emacs</filename>; Greg
- Stein, für überquellendes praktisches Programmierwissen; Brian
+ Stein, für überquellendes praktisches Programmierwissen; und Brian
Fitzpatrick—dafür, dass du diese Schreiberfahrung mit
mir teilst. Vor all den vielen Leuten, von denen ich ständig
etwas neues aufnehme—lasst weiter etwas fallen!</para>
@@ -1671,7 +1662,7 @@
day at their jobs. Their frustration with CVS had led Jim to
think carefully about better ways to manage versioned data, and
he'd already come up with not only the name
- <quote>Subversion,</quote> but also with the basic design of
+ <quote>Subversion,</quote> but also the basic design of
the Subversion data store. When CollabNet called, Karl
immediately agreed to work on the project, and Jim got his
employer, Red Hat Software, to essentially donate him to the
@@ -1832,15 +1823,15 @@
<para>Subversion, once installed, has a number of different
pieces. The following is a quick overview of what you get.
Don't be alarmed if the brief descriptions leave you scratching
- your head—there are <emphasis>plenty</emphasis> more pages
- in this book devoted to alleviating that confusion.</para>
+ your head—<emphasis>plenty</emphasis> more pages
+ in this book are devoted to alleviating that confusion.</para>
-->
<para>Sobald es installiert ist, hat Subversion eine Anzahl
verschiedener Teile. Was folgt, ist ein schneller Überblick
was Sie bekommen. Lassen sie sich nicht beunruhigen, falls die
kurzen Beschreibungen sie dazu veranlassen, sich am Kopf zu
kratzen—es gibt in diesem Buch <emphasis>jede
- menge</emphasis> weiterer Seiten, die dem Ziel gewidmet
+ Menge</emphasis> weiterer Seiten, die dem Ziel gewidmet
sind, diese Verwirrung zu lindern.</para>
<variablelist>
@@ -1848,7 +1839,7 @@
<term>svn</term>
<listitem>
<!--
- <para>The command-line client program.</para>
+ <para>The command-line client program</para>
-->
<para>Das Kommandozeilenprogramm</para>
</listitem>
@@ -1859,11 +1850,11 @@
<listitem>
<!--
<para>A program for reporting the state (in terms of
- revisions of the items present) of a working copy.</para>
+ revisions of the items present) of a working copy</para>
-->
<para>Ein Programm, das den Zustand einer Arbeitskopie
(durch Revisionen der vorliegenden Objekte)
- berichtet.</para>
+ berichtet</para>
</listitem>
</varlistentry>
@@ -1871,10 +1862,10 @@
<term>svnlook</term>
<listitem>
<!--
- <para>A tool for directly inspecting a Subversion repository.</para>
+ <para>A tool for directly inspecting a Subversion repository</para>
-->
<para>Ein Werkzeug zur direkten Untersuchung eines
- Subversion Repositorys.</para>
+ Subversion Repositorys</para>
</listitem>
</varlistentry>
@@ -1883,10 +1874,10 @@
<listitem>
<!--
<para>A tool for creating, tweaking, or repairing a Subversion
- repository.</para>
+ repository</para>
-->
<para>Ein Werkzeug zum Erstellen, Verändern oder
- Reparieren eines Repositorys.</para>
+ Reparieren eines Repositorys</para>
</listitem>
</varlistentry>
@@ -1896,11 +1887,11 @@
<!--
<para>A plug-in module for the Apache HTTP Server, used to
make your repository available to others over a
- network.</para>
+ network</para>
-->
<para>Ein Plug-In-Modul für den Apache HTTP-Server, wird
benötigt, um das Repository über ein Netzwerk verfügbar
- zu machen.</para>
+ zu machen</para>
</listitem>
</varlistentry>
@@ -1924,10 +1915,10 @@
<listitem>
<!--
<para>A program for filtering Subversion repository dump
- streams.</para>
+ streams</para>
-->
<para>Ein Programm zum Filtern von Subversion Repository
- Dump Streams.</para>
+ Dump Streams</para>
</listitem>
</varlistentry>
@@ -1936,10 +1927,10 @@
<listitem>
<!--
<para>A program for incrementally mirroring one
- repository to another over a network.</para>
+ repository to another over a network</para>
-->
<para>Ein Programm zum inkrementellen Spiegeln eines
- Repositorys über ein Netzwerk.</para>
+ Repositorys über ein Netzwerk</para>
</listitem>
</varlistentry>
@@ -1990,9 +1981,9 @@
<!--
<para>Release 1.1 introduced FSFS, a flat-file repository
storage option for the repository. While the BerkeleyDB
- back-end is still widely used and supported, FSFS has
+ backend is still widely used and supported, FSFS has
since become the default choice for
- newly-created repositories due to its low barrier to
+ newly created repositories due to its low barrier to
entry and minimal maintenance requirements. Also in
this release came the ability to put symbolic links
under version control, auto-escaping of URLs, and a
@@ -2023,8 +2014,8 @@
server-side <quote>locks</quote> on files, thus
serializing commit access to certain resources. While
Subversion is still a fundamentally concurrent version
- control system, certain types of binary files (art
- assets, for example) cannot be merged together. The
+ control system, certain types of binary files (e.g. art
+ assets) cannot be merged together. The
locking feature fulfills the need to version and protect
such resources. With locking also came a
complete <quote>auto-versioning</quote> implementation,
@@ -2085,8 +2076,8 @@
tool—<command>svnsync</command>— for doing
one-way repository replication over a network. Major
parts of the working copy metadata were revamped to
- longer use XML (resulting in client side speed gains),
- while the BerkeleyDB repository back-end gained the
+ longer use XML (resulting in client-side speed gains),
+ while the BerkeleyDB repository backend gained the
ability to automatically <quote>recover</quote> itself
after a server crash.</para>
-->
@@ -2118,7 +2109,7 @@
commercial competitors such as Perforce and Clearcase.
Subversion 1.5 also introduced a bevy of other
user-focused features, such as interactive resolution of
- file conflicts, partial checkouts, client side
+ file conflicts, partial checkouts, client-side
management of changelists, powerful new syntax for
externals definitions, and SASL authentication support for
the <command>svnserve</command> server.</para>
Modified: trunk/src/de/book/ch01-fundamental-concepts.xml
==============================================================================
--- trunk/src/de/book/ch01-fundamental-concepts.xml (original)
+++ trunk/src/de/book/ch01-fundamental-concepts.xml Tue Aug 12 11:40:38 2008
@@ -84,7 +84,7 @@
<emphasis>previous</emphasis> states of the filesystem. For
example, a client can ask historical questions such
as <quote>What did this directory contain last
- Wednesday?</quote> or <quote>Who was the last person to change
+ Wednesday?</quote> and <quote>Who was the last person to change
this file, and what changes did he make?</quote> These are the
sorts of questions that are at the heart of
any <firstterm>version control system</firstterm>: systems that
@@ -95,7 +95,7 @@
Der Client hat aber auch die Möglichkeit, <emphasis>vorherige</emphasis>
Zustände des Dateibaumes anzuschauen.
Zum Beispiel kann ein Client somit die Frage stellen:
- <quote>Was beinhaltete das Verzeichnis am letzten Mittwoch?</quote> oder
+ <quote>Was beinhaltete das Verzeichnis am letzten Mittwoch?</quote> und
<quote>Wer war die Person, die als letztes die Datei geändert hat und welche
Änderungen hat sie gemacht?</quote>. Diese Art von Fragen sind
die Grundlage eines
@@ -118,7 +118,7 @@
<para>The core mission of a version control system is to enable
collaborative editing and sharing of data. But different
systems use different strategies to achieve this. It's
- important to understand these different strategies for a couple
+ important to understand these different strategies, for a couple
of reasons. First, it will help you compare and contrast
existing version control systems, in case you encounter other
systems similar to Subversion. Beyond that, it will also help
@@ -161,7 +161,7 @@
linkend="svn.basic.vsn-models.problem-sharing.dia-1"/>.
Suppose we have two coworkers, Harry and Sally. They each
decide to edit the same repository file at the same time. If
- Harry saves his changes to the repository first, then it's
+ Harry saves his changes to the repository first, it's
possible that (a few moments later) Sally could accidentally
overwrite them with her own new version of the file. While
Harry's version of the file won't be lost forever (because the
@@ -177,7 +177,7 @@
Nehmen wir an wir haben zwei Kollegen, Harry und Sally.
Sie haben sich beide entschieden die gleiche Datei zur gleichen
Zeit zu bearbeiten. Wenn Harry seine Änderungen im Repository
- zuerst speichert dann ist es möglich, dass einige Augenblicke
+ zuerst speichert ist es möglich, dass einige Augenblicke
später, Sally unbeabsichtigt mit Ihrer eigenen Version der
Datei überschreibt. Während Harry's Version der Datei nicht
für immer verloren ist (weil das System jegliche Änderung
@@ -210,7 +210,7 @@
model, the repository allows only one person to change a file
at a time. This exclusivity policy is managed using locks.
Harry must <quote>lock</quote> a file before he can begin
- making changes to it. If Harry has locked a file, then Sally
+ making changes to it. If Harry has locked a file, Sally
cannot also lock it, and therefore cannot make any changes to
that file. All she can do is read the file and wait for
Harry to finish his changes and release his lock. After Harry
@@ -296,7 +296,7 @@
same file A within their copies. Sally saves her changes to
the repository first. When Harry attempts to save his changes
later, the repository informs him that his file A is
- <firstterm>out-of-date</firstterm>. In other words, that file
+ <firstterm>out of date</firstterm>. In other words, that file
A in the repository has somehow changed since he last copied
it. So Harry asks his client to <firstterm>merge</firstterm>
any new changes from the repository into his working copy of
@@ -352,8 +352,8 @@
<title>When Locking Is Necessary</title>
<para>While the lock-modify-unlock model is considered
- generally harmful to collaboration, there are still times
- when locking is appropriate.</para>
+ generally harmful to collaboration, sometimes
+ locking is appropriate.</para>
<para>The copy-modify-merge model is based on the assumption
that files are contextually mergeable—that is, that the
@@ -361,16 +361,15 @@
files (such as program source code). But for files with
binary formats, such as artwork or sound, it's often
impossible to merge conflicting changes. In these
- situations, it really is necessary to users to take strict
+ situations, it really is necessary for users to take strict
turns when changing the file. Without serialized access,
somebody ends up wasting time on changes that are ultimately
discarded.</para>
<para>While Subversion is primarily a copy-modify-merge
system, it still recognizes the need to lock an occasional
- file, and thus provides mechanisms for this. This feature is
- discussed later in this book in
- <xref linkend="svn.advanced.locking"/>.</para>
+ file, and thus provides mechanisms for this. We discuss
+ this feature in <xref linkend="svn.advanced.locking"/>.</para>
</sidebar>
@@ -479,8 +478,8 @@
<note>
<!--
- <para>Subversion's <literal>file://</literal> URLs cannot be
- used in a regular web browser the way typical
+ <para>You cannot use Subversion's <literal>file://</literal> URLs
+ in a regular web browser the way typical
<literal>file://</literal> URLs can. When you attempt to view
a <literal>file://</literal> URL in a regular web browser, it
reads and displays the contents of the file at that location
@@ -490,9 +489,9 @@
will not understand how to interact with that
filesystem.</para>
-->
- <para>Die <literal>file://</literal> URLs von Subversion
- können in einem normalen Web-Browser nicht auf die Art und
- Weise verwendet werden wie andere <literal>file://</literal>
+ <para>Sie können die <literal>file://</literal> URLs von Subversion
+ nicht in einem normalen Web-Browser auf die Art und
+ Weise verwenden wie andere <literal>file://</literal>
URLs. Falls Sie versuchen, einen <literal>file://</literal>
URL in einem gewöhnlichen Web-Browser anzusehen, wird der
Inhalt der Datei von der angegebenen Stelle direkt aus dem
@@ -520,7 +519,7 @@
<!--
<para>then Subversion will escape the unsafe characters
- and behave as if you had typed:</para>
+ and behave as though you had typed:</para>
-->
<para>wird Subversion die unsicheren Zeichen umwandeln, als ob
Sie</para>
@@ -532,8 +531,8 @@
<para>geschrieben hätten.</para>
<!--
- <para>If the URL contains spaces, be sure to place it within quote
- marks, so that your shell treats the whole thing as a single
+ <para>If the URL contains spaces, be sure to place it within quotation
+ marks so that your shell treats the whole thing as a single
argument to the <command>svn</command> program.</para>
-->
<para>Falls ein URL Leerzeichen beinhalten sollte, stellen Sie
@@ -545,7 +544,7 @@
<title>Repository URLs</title>
<!--
- <para>Subversion repositories can be accessed through many
+ <para>You can access Subversion repositories through many
different methods—on local disk or through various
network protocols, depending on how your administrator has
set things up for you. A repository location, however, is
@@ -554,8 +553,8 @@
different URL schemes map to the available access
methods.</para>
-->
- <para>Auf Subversion Repositorys kann durch viele
- unterschiedliche Methoden zugegriffen werden—auf der
+ <para>Sie können auf Subversion Repositorys über viele
+ unterschiedliche Methoden zugreifen—auf der
lokalen Festplatte oder über verschiedene Protokolle, je
nachdem, wie Ihr Administrator es eingerichtet hat. Ein Ort
im Repository ist jedenfalls immer ein URL.
@@ -829,11 +828,11 @@
<!--
<para>To publish your changes to others, you can use
- Subversion's <command>commit</command> command.</para>
+ Subversion's <command>svn commit</command> command:</para>
-->
<para>Um Ihre Änderungen anderen gegenüber zu veröffentlichen,
- können Sie den Subversion Befehl <command>commit</command>
- verwenden.</para>
+ können Sie den Subversion Befehl <command>svn commit</command>
+ verwenden:</para>
<screen>
$ svn commit button.c -m "Fixed a typo in button.c."
@@ -846,15 +845,15 @@
<para>Now your changes to <filename>button.c</filename> have
been committed to the repository, with a note describing your
change (namely, that you fixed a typo). If another user
- checks out a working copy of <filename>/calc</filename>, they
+ checks out a working copy of <filename>/calc</filename>, she
will see your changes in the latest version of the
file.</para>
-->
<para>Nun sind Ihre Änderungen an <filename>button.c</filename> dem
Repository überstellt mitsamt einer Notiz, die Ihre Änderung
beschreibt (nämlich, dass Sie einen Tippfehler beseitigt
- haben). Wenn ein anderer Benutzer eine Arbeitskopie von
- <filename>button.c</filename> auscheckt, wird er Ihre
+ haben). Wenn eine andere Benutzerin eine Arbeitskopie von
+ <filename>/calc</filename> auscheckt, wird sie Ihre
Änderungen in der letzten Version der Datei sehen
können.</para>
@@ -876,13 +875,13 @@
<!--
<para>To bring her project up to date, Sally can ask Subversion
to <firstterm>update</firstterm> her working copy, by using
- the <command>update</command> command. This will incorporate
+ the <command>svn update</command> command. This will incorporate
your changes into her working copy, as well as any others that
have been committed since she checked it out.</para>
-->
<para>Um ihr Projekt auf den neuesten Stand zu bringen, kann
Sally Subversion dazu auffordern, ihre Arbeitskopie zu
- aktualisieren, indem sie den Befehl <command>update</command>
+ aktualisieren, indem sie den Befehl <command>svn update</command>
verwendet. Das bringt sowohl Ihre als auch alle anderen
Änderungen die committet wurden seit sie ausgecheckt hatte in
ihre Arbeitskopie.</para>
@@ -933,7 +932,7 @@
changes to any number of files and directories as a single
atomic transaction. In your working copy, you can change
files' contents; create, delete, rename, and copy files and
- directories; then commit a complete set of changes as an
+ directories; and then commit a complete set of changes as an
atomic transaction.</para>
-->
<para>Ein <command>svn commit</command> veröffentlicht
@@ -947,7 +946,7 @@
<!--
<para>By atomic transaction, we mean simply this: either all of
- the changes happen in the repository, or none of them happen.
+ the changes happen in the repository, or none of them happens.
Subversion tries to retain this atomicity in the face of
program crashes, system crashes, network problems, and other
users' actions.</para>
@@ -1015,7 +1014,7 @@
revision N represents the state of the repository filesystem
after the Nth commit. When Subversion users talk
about <quote>revision 5 of
- <filename>foo.c</filename></quote>, they really mean
+ <filename>foo.c</filename>,</quote> they really mean
<quote><filename>foo.c</filename> as it appears in revision
5.</quote> Notice that in general, revisions N and M of a
file do <emphasis>not</emphasis> necessarily differ! Many
@@ -1091,7 +1090,7 @@
<para>Suppose that, at this point, Sally commits a change to
<filename>integer.c</filename>, creating revision 6. If you
use <command>svn update</command> to bring your working copy
- up to date, then it will look like this:</para>
+ up to date, it will look like this:</para>
-->
<para>Angenommen, zu diesem Zeitpunkt macht Sally einen Commit
für eine Änderung an <filename>integer.c</filename> und
@@ -1152,11 +1151,11 @@
<!--
<para>What revision your working file is based on (this is
called the file's <firstterm>working
- revision</firstterm>) and</para>
+ revision</firstterm>)</para>
-->
<para>Auf welcher Revision Ihre Arbeitsdatei aufbaut (das
wird die <firstterm>Arbeitsrevision</firstterm> der Datei
- genannt) und</para>
+ genannt)</para>
</listitem>
<listitem>
@@ -1215,7 +1214,7 @@
<para>The file has been changed in the working directory,
and no changes to that file have been committed to the
repository since you last updated. There are local
- changes that have not been committed to the repository,
+ changes that have not been committed to the repository;
thus an <command>svn commit</command> of the file will
succeed in publishing your changes, and an <command>svn
update</command> of the file will do nothing.</para>
@@ -1233,7 +1232,7 @@
<varlistentry>
<!--
- <term>Unchanged, and out-of-date</term>
+ <term>Unchanged, and out of date</term>
-->
<term>Unverändert und veraltet</term>
@@ -1261,7 +1260,7 @@
<varlistentry>
<!--
- <term>Locally changed, and out-of-date</term>
+ <term>Locally changed, and out of date</term>
-->
<term>Lokal geändert und veraltet</term>
@@ -1321,7 +1320,7 @@
mix of different working revision numbers. Unfortunately,
this flexibility tends to confuse a number of new users. If
the earlier example showing mixed revisions perplexed you,
- here's a primer on both why the feature exists and how to make
+ here's a primer on why the feature exists and how to make
use of it.</para>
-->
<para>Als allgemeingültiges Prinzip versucht Subversion, so
@@ -1345,7 +1344,7 @@
<!--
<para>One of the fundamental rules of Subversion is that
a <quote>push</quote> action does not cause
- a <quote>pull,</quote> nor the other way around. Just
+ a <quote>pull,</quote> nor vice versa. Just
because you're ready to submit new changes to the repository
doesn't mean you're ready to receive changes from other
people. And if you have new changes still in progress,
@@ -1392,7 +1391,7 @@
update</command>, and <command>svn commit</command> doesn't
pull down new changes. If, on the other hand,
<command>svn commit</command> were to automatically download
- the newest changes, then it would be possible to set the
+ the newest changes, it would be possible to set the
entire working copy to revision 15—but then we'd be
breaking the fundamental rule of <quote>push</quote>
and <quote>pull</quote> remaining separate actions.
@@ -1441,17 +1440,17 @@
<!--
<para>The fact is, <emphasis>every time</emphasis> you run
- <command>svn commit</command>, your working copy ends up
+ <command>svn commit</command> your working copy ends up
with some mixture of revisions. The things you just
committed are marked as having larger working revisions than
everything else. After several commits (with no updates
in between), your working copy will contain a whole mixture
of revisions. Even if you're the only person using the
repository, you will still see this phenomenon. To examine
- your mixture of working revisions, use the
- <command>svn status --verbose</command> command (see
- <xref linkend="svn.tour.cycle.examine.status"/> for more
- information.)</para>
+ your mixture of working revisions, use the <command>svn
+ status</command> command with the <option>- -verbose</option> option (see <xref
+ linkend="svn.tour.cycle.examine.status"/> for more
+ information).</para>
-->
<para>Tatsache ist, dass <emphasis>jedesmal</emphasis> wenn
Sie <command>svn commit</command> aufgerufen haben, die
@@ -1463,10 +1462,10 @@
Riesenmischung von Revisionen. Selbst wenn Sie die einzige
Person sind, die das Repository benutzt, werden sie dieses
Phänomen bemerken. Um Ihre Mischung aus Arbeitsrevisionen zu
- untersuchen zu können, verwenden Sie den <command>svn status
- --verbose</command> Befehl (siehe <xref
- linkend="svn.tour.cycle.examine.status"/> für weitergehende
- Informationen).</para>
+ untersuchen zu können, verwenden Sie den Befehl <command>svn
+ status</command> mit der <option>--verbose</option> Option
+ (siehe <xref linkend="svn.tour.cycle.examine.status"/> für
+ weitergehende Informationen).</para>
<!--
<para>Often, new users are completely unaware that their
@@ -1476,11 +1475,11 @@
example, the <command>svn log</command> command is used to
display the history of changes to a file or directory (see
<xref linkend="svn.tour.history.log"/>). When the user
- invokes this command on a working copy object, they expect
+ invokes this command on a working copy object, he expects
to see the entire history of the object. But if the
object's working revision is quite old (often because
<command>svn update</command> hasn't been run in a long
- time), then the history of the <emphasis>older</emphasis>
+ time), the history of the <emphasis>older</emphasis>
version of the object is shown.</para>
-->
<para>Oft ist neuen Benutzern überhaupt nicht bewusst, das
@@ -1511,7 +1510,7 @@
<!--
<para>If your project is sufficiently complex, you'll discover
that it's sometimes nice to
- forcibly <firstterm>backdate</firstterm> (or, update to a
+ forcibly <firstterm>backdate</firstterm> (or update to a
revision older than the one you already have) portions of
your working copy to an earlier revision; you'll learn how
to do that in <xref linkend="svn.tour"/>. Perhaps you'd
@@ -1558,7 +1557,7 @@
<para>First, you cannot commit the deletion of a file or
directory that isn't fully up to date. If a newer version
of the item exists in the repository, your attempt to delete
- will be rejected in order to prevent you from accidentally
+ will be rejected to prevent you from accidentally
destroying changes you've not yet seen.</para>
-->
<para>Erstens kann die Löschung einer Datei oder eines
@@ -1604,7 +1603,7 @@
<title>Zusammenfassung</title>
<!--
- <para>We've covered a number of fundamental Subversion concepts in
+ <para>We covered a number of fundamental Subversion concepts in
this chapter:</para>
-->
<para>In diesem Kapitel haben wir eine Anzahl fundamentaler
@@ -1613,7 +1612,7 @@
<itemizedlist>
<listitem>
<!--
- <para>We've introduced the notions of the central repository,
+ <para>We introduced the notions of the central repository,
the client working copy, and the array of repository
revision trees.</para>
-->
@@ -1624,7 +1623,7 @@
<listitem>
<!--
- <para>We've seen some simple examples of how two collaborators
+ <para>We saw some simple examples of how two collaborators
can use Subversion to publish and receive changes from one
another, using the <quote>copy-modify-merge</quote>
model.</para>
@@ -1638,7 +1637,7 @@
<listitem>
<!--
- <para>We've talked a bit about the way Subversion tracks and
+ <para>We talked a bit about the way Subversion tracks and
manages information in a working copy.</para>
-->
<para>Wir haben ein wenig darüber geredet, wie Subversion
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 Tue Aug 12 11:40:38 2008
@@ -28,7 +28,7 @@
<!--
<para>Note that this chapter is not meant to be an exhaustive list
- of all Subversion's commands—rather, it's a conversational
+ of all of Subversion's commands—rather, it's a conversational
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
@@ -58,16 +58,16 @@
<para>Before reading on, here is the most important command you'll
ever need when using Subversion: <command>svn help</command>.
The Subversion command-line client is self-documenting—at
- any time, a quick <command>svn help
- <replaceable>SUBCOMMAND</replaceable></command> will describe
+ any time, a quick <userinput>svn help
+ <replaceable>subcommand</replaceable></userinput> will describe
the syntax, options, and behavior of the subcommand.</para>
-->
<para>Bevor Sie weiterlesen: hier ist der wichtigste Befehl den
Sie benötigen, wenn Sie Subversion verwenden: <command>svn
help</command>. Der Subversion Kommandozeilen-Client ist
selbstdokumentierend—jederzeit erklärt Ihnen ein schnelles
- <command>svn help
- <replaceable>UNTERBEFEHL</replaceable></command> die Syntax,
+ <userinput>svn help
+ <replaceable>Unterbefehl</replaceable></userinput> die Syntax,
die Optionen und das Verhalten des Unterbefehls.</para>
<screen>
@@ -103,15 +103,15 @@
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>
+ 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
- typically options that are frequently used). In order to
+ typically options that are frequently used). To
maintain clarity, we <emphasis>usually</emphasis> use the
long form in code examples, but when describing options, if
there's a short form, we'll provide the long form (to
- improve clarity), and the short form (to make it easier to
+ improve clarity) and the short form (to make it easier to
remember). You should use whichever one you're more
comfortable with, but don't try to use both.</para>
-->
@@ -148,14 +148,14 @@
<title>Wie Sie Daten in Ihr Repository bekommen</title>
<!--
- <para>There are two ways to get new files into your Subversion
- repository: <command>svn import</command> and <command>svn
+ <para>You can get new files into your Subversion
+ repository in two ways: <command>svn import</command> and <command>svn
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>
-->
- <para>Es gibt zwei Möglichkeiten, neue Dateien in das Subversion
- Repository zu bekommen: <command>svn import</command> und
+ <para>Sie können neue Dateien auf zweierlei Weisen in das Subversion
+ Repository bekommen: <command>svn import</command> und
<command>svn add</command>. Wir werden <command>svn
import</command> jetzt und <command>svn add</command> später
in diesem Kapitel besprechen, wenn wir einen typischen Tag mit
@@ -173,8 +173,8 @@
copy an unversioned tree of files into a repository, creating
intermediate directories as necessary. <command>svn
import</command> doesn't require a working copy, and your files
- are immediately committed to the repository. This is typically
- used when you have an existing tree of files that you want to
+ are immediately committed to the repository. You typically
+ use this when you have an existing tree of files that you want to
begin tracking in your Subversion repository. For example:</para>
-->
<para>Mit dem <command>svn import</command> Befehl kann ein
@@ -182,9 +182,9 @@
kopiert werden, wobei benötigte Zwischenverzeichnisse nach
Bedarf angelegt werden. <command>svn import</command>
erfordert keine Arbeitskopie und pflegt Ihre Dateien sofort in
- das Repository ein. Typischerweise wird dieser Befehl
- verwendet, wenn bereits ein Verzeichnisbaum besteht, den man
- aber in einem Subversion Repository pflegen möchte. Zum
+ das Repository ein. Typischerweise verwenden Sie diesen Befehl
+ wenn bereits ein Verzeichnisbaum besteht, den Sie
+ aber in einem Subversion Repository pflegen möchten. Zum
Beispiel:</para>
<screen>
@@ -244,7 +244,7 @@
<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>
-->
<para>Obwohl die Flexibilität von Subversion es Ihnen erlaubt,
Ihr Repository nach Belieben aufzuteilen, empfehlen wir, ein
@@ -252,7 +252,7 @@
<quote>Hauptlinie</quote> der Entwicklung, ein
<filename>branches</filename> Verzeichnis für Branch-Kopien und
ein <filename>tags</filename> Verzeichnis für
- Tag-Kopien—zum Beispiel:</para>
+ Tag-Kopien. Zum Beispiel:</para>
<screen>
$ svn list file:///var/svn/repos
@@ -348,7 +348,7 @@
<!--
<para>Subversion internally handles certain bits of
- data—for example, property names, path names, and log
+ data—for example, property names, pathnames, and log
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
@@ -372,7 +372,7 @@
<para>In WebDAV exchanges and older versions of some of
Subversion's administrative files, paths are used as XML
attribute values, and property names in XML tag names. This
- means that path names can contain only legal XML (1.0)
+ means that pathnames can contain only legal XML (1.0)
characters, and properties are further limited to ASCII
characters. Subversion also prohibits TAB, CR, and LF
characters in path names to prevent paths from being broken up
@@ -394,7 +394,7 @@
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—in order to create
+ an extra bit of help—to create
<quote>legally correct</quote> versions for internal
use it will automatically escape illegal
path characters as needed in URLs that you type.</para>
@@ -412,12 +412,12 @@
</sidebar>
<!--
- <para>Although the above example checks out the trunk directory,
+ <para>Although the preceding example checks out the trunk directory,
you can just as easily check out any deep subdirectory of a
repository by specifying the subdirectory in the checkout
URL:</para>
-->
- <para>Obwohl im obigen Beispiel das trunk-Verzeichnis ausgecheckt
+ <para>Obwohl im vorangehenden Beispiel das trunk-Verzeichnis ausgecheckt
wird, können Sie genauso leicht irgend ein tiefliegendes
Unterverzeichnis aus einem Repository auschecken, indem Sie das
Unterverzeichnis im URL beim Checkout angeben:</para>
@@ -435,18 +435,18 @@
</screen>
<!--
- <para>Since Subversion uses a <quote>copy-modify-merge</quote>
- model instead of <quote>lock-modify-unlock</quote> (see
+ <para>Since Subversion uses a copy-modify-merge
+ model instead of lock-modify-unlock (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, even delete the entire working copy and
+ it, move it around, even delete the entire working copy and
forget about it.</para>
-->
- <para>Da Subversion ein <quote>copy-modify-merge</quote>
+ <para>Da Subversion ein <emphasis>copy-modify-merge</emphasis>
(kopieren-ändern-zusammenführen) Modell statt eines
- <quote>lock-modify-unlock</quote> (sperren-ändern-freigeben)
+ <emphasis>lock-modify-unlock</emphasis> (sperren-ändern-freigeben)
Modells verwendet (siehe <xref
linkend="svn.basic.vsn-models"/>), können Sie sofort damit
beginnen, Änderungen an den Dateien und Verzeichnissen Ihrer
@@ -495,9 +495,9 @@
<sidebar>
<!--
- <title>What's with the <filename>.svn</filename> Directory?</title>
+ <title>What's with the .svn Directory?</title>
-->
- <title>Was hat es mit dem <filename>.svn</filename> Verzeichnis
+ <title>Was hat es mit dem .svn Verzeichnis
auf sich?</title>
<!--
@@ -522,20 +522,21 @@
<para>If you accidentally remove the <filename>.svn</filename>
subdirectory, the easiest way to fix the problem is to remove
the entire containing directory (a normal system deletion,
- not <command>svn delete</command>), then run <command>svn
- update</command> from a parent directory. The Subversion
- client will re-download the directory you've deleted, with a
+ not <command>svn delete</command>), then run <userinput>svn
+ update</userinput> from a parent directory. The Subversion
+ client will download the directory you've deleted, with a
new <filename>.svn</filename> area as well.</para>
-->
<para>Sollten Sie versehentlich das <filename>.svn</filename>
Verzeichnis löschen, besteht die einfachste Lösung des
Problems darin, das komplette darüberliegende Verzeichnis zu
löschen (mit dem Betriebssystem-Löschbefehl, nicht mit
- <command>svn delete</command>) und dann wiederum <command>svn
- update</command> von einem darüberliegenden Verzeichnis aus
- aufzurufen. Der Subversion-Client wird das von Ihnen gelöschte
- Verzeichnis erneut herunterladen und dabei auch einen neuen
- <filename>.svn</filename>-Bereich anlegen.</para>
+ <command>svn delete</command>) und dann wiederum
+ <userinput>svn update</userinput> von einem darüberliegenden
+ Verzeichnis aus aufzurufen. Der Subversion-Client wird das von
+ Ihnen gelöschte Verzeichnis herunterladen und dabei
+ auch einen neuen <filename>.svn</filename>-Bereich
+ anlegen.</para>
</sidebar>
<!--
@@ -585,14 +586,14 @@
<para>When you perform a Subversion operation that requires you
to authenticate, by default Subversion caches your
authentication credentials on disk. This is done for
- convenience, so that you don't have to continually re-enter
+ convenience so that you don't have to continually reenter
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
+ Subversion, and second because your Subversion password
isn't the same as any of the other 3 million passwords
you have, right? Right?</para>
</footnote>
@@ -638,17 +639,17 @@
<sect2 id="svn.tour.initial.different-user">
<!--
- <title>Authenticating as a Different User</title>
+ <title>Authenticating As a Different User</title>
-->
<title>Authentifizierung als ein anderer Anwender</title>
<!--
<para>Since Subversion caches auth credentials by default (both
username and password), it conveniently remembers who you were
- acting as the last time you modified you working copy. But
+ acting as the last time you modified your working copy. But
sometimes that's not helpful—particularly if you're
working in a shared working copy such as a system
- configuration directory or a webserver document root. In this
+ configuration directory or a web server 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>
@@ -681,8 +682,8 @@
<!--
<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
+ whistles, but on a day-to-day basis, odds are that you will use
+ only 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>
-->
@@ -798,14 +799,14 @@
<!--
<para>When working on a project with a team, you'll want to
- update your working copy to receive any changes made since
- your last update by other developers on the project. Use
+ update your working copy to receive any changes other developers
+ on the project have made since your last update. Use
<command>svn update</command> to bring your working copy into
sync with the latest revision in the repository:</para>
-->
<para>Wenn Sie in einem Projekt im Team zusammenarbeiten,
- sollten Sie Ihre Arbeitskopie aktualisieren, um die Änderungen
- anderer Entwickler zu bekommen, die sie seit Ihrer letzten
+ sollten Sie Ihre Arbeitskopie aktualisieren, um die Änderungen zu bekommen,
+ die die anderen Entwickler im Projekt seit Ihrer letzten
Aktualisierung vorgenommen haben. Benutzen Sie <command>svn
update</command> um Ihre Arbeitskopie synchron mit der
letzten Revision im Repository zu bekommen:</para>
@@ -834,15 +835,16 @@
<para>When the server sends changes to your working copy via
<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, run <command>svn help update</command>.</para>
+ to bring your working copy up to date. To find out what these
+ letters mean, run <userinput>svn help update</userinput>.</para>
-->
<para>Wenn der Server über <command>svn update</command>
Änderungen an Ihre Arbeitskopie schickt, wird ein
Buchstabencode neben jedem Objekt angezeigt, um Ihnen
anzuzeigen, was Subversion gemacht hat, um die Arbeitskopie
auf den neuesten Stand zu bringen. Zur Bedeutung der
- Buchstaben, siehe <command>svn help update</command>.</para>
+ Buchstaben, rufen Sie <userinput>svn help update</userinput>
+ auf.</para>
</sect2>
<!-- =============================================================== -->
@@ -856,7 +858,7 @@
<para>Now you can get to work and make changes in your working
copy. It's usually most convenient to decide on a discrete
change (or set of changes) to make, such as writing a new
- feature, fixing a bug, etc. The Subversion commands that you
+ feature, fixing a bug, and so on. The Subversion commands that you
will use here are <command>svn add</command>, <command>svn
delete</command>, <command>svn copy</command>, <command>svn
move</command>, and <command>svn mkdir</command>. However, if
@@ -868,7 +870,7 @@
Arbeitskopie vornehmen. Normalerweise ist es am einfachsten,
sich für eine bestimmte Änderung (oder eine Menge von
Änderungen) zu entscheiden, etwa ein neues Feature zu
- implementieren oder einen Fehler zu beseitigen. Die
+ implementieren oder einen Fehler zu beseitigen usw. Die
Subversion-Befehle, die Sie hierfür verwenden werden sind
<command>svn add</command>, <command>svn delete</command>,
<command>svn copy</command>, <command>svn move</command> und
@@ -878,23 +880,23 @@
Änderungen committen.</para>
<!--
- <para>There are two kinds of changes you can make to your
+ <para>You can make two kinds of changes to your
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
- text files—and just as efficiently too. For tree
+ addition, it 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
moving. These changes may take place immediately in your
working copy, but no additions or removals will happen in the
repository until you commit them.</para>
-->
- <para>Es gibt zwei Arten von Änderungen, die Sie an Ihrer
- Arbeitskopie vornehmen können:
+ <para>Sie können zwei Arten von Änderungen an Ihrer
+ Arbeitskopie vornehmen:
<firstterm>Dateiänderungen</firstterm> und
<firstterm>Verzeichnisbaumänderungen</firstterm>. Sie brauchen
Subversion nicht mitzuteilen, dass sie beabsichtigen, eine
@@ -969,16 +971,16 @@
<!--
<para>Here is an overview of the five Subversion subcommands
- that you'll use most often to make tree changes.</para>
+ that you'll use most often to make tree changes:</para>
-->
<para>Hier ist ein Überblick der fünf Subversion Unterbefehle,
die Sie am häufigsten benutzen werden, um Änderungen am
- Verzeichnisbaum vorzunehmen.</para>
+ Verzeichnisbaum vorzunehmen:</para>
<variablelist>
<varlistentry>
- <term><command>svn add foo</command></term>
+ <term><userinput>svn add foo</userinput></term>
<listitem>
<!--
<para>Schedule file, directory, or symbolic link
@@ -1005,7 +1007,7 @@
</varlistentry>
<varlistentry>
- <term><command>svn delete foo</command></term>
+ <term><userinput>svn delete foo</userinput></term>
<listitem>
<!--
<para>Schedule file, directory, or symbolic link
@@ -1055,7 +1057,7 @@
</varlistentry>
<varlistentry>
- <term><command>svn copy foo bar</command></term>
+ <term><userinput>svn copy foo bar</userinput></term>
<listitem>
<!--
<para>Create a new item <filename>bar</filename> as a
@@ -1082,11 +1084,11 @@
</varlistentry>
<varlistentry>
- <term><command>svn move foo bar</command></term>
+ <term><userinput>svn move foo bar</userinput></term>
<listitem>
<!--
<para>This command is exactly the same as running
- <command>svn copy foo bar; svn delete foo</command>.
+ <userinput>svn copy foo bar; svn delete foo</userinput>.
That is, <filename>bar</filename> is scheduled for
addition as a copy of <filename>foo</filename>, and
<filename>foo</filename> is scheduled for removal.
@@ -1095,7 +1097,7 @@
<option>- -parents</option> option.</para>
-->
<para>Dieser Befehl macht genau das gleiche wie
- <command>svn copy foo bar; svn delete foo</command>.
+ <userinput>svn copy foo bar; svn delete foo</userinput>.
D.h., <filename>bar</filename> wird zum Hinzufügen als
Kopie von <filename>foo</filename> and
<filename>foo</filename> zum Löschen vorgemerkt.
@@ -1106,16 +1108,16 @@
</varlistentry>
<varlistentry>
- <term><command>svn mkdir blort</command></term>
+ <term><userinput>svn mkdir blort</userinput></term>
<listitem>
<!--
<para>This command is exactly the same as running
- <command>mkdir blort; svn add blort</command>. That is,
+ <userinput>mkdir blort; svn add blort</userinput>. That is,
a new directory named <filename>blort</filename> is
created and scheduled for addition.</para>
-->
<para>Dieser Befehl macht genau das gleiche wie
- <command>mkdir blort; svn add blort</command>. D.h., ein
+ <userinput>mkdir blort; svn add blort</userinput>. D.h., ein
neues Verzeichnis namens <filename>blort</filename> wird
angelegt und zum Hinzufügen vorgemerkt.</para>
</listitem>
@@ -1157,7 +1159,7 @@
sort of <quote>staging area</quote> to set up your changes
before committing them to the repository. Commands that
operate on URLs don't have this luxury, so when you operate
- directly on a URL, any of the above actions represents an
+ directly on a URL, any of the aforementioned actions represents an
immediate commit.</para>
-->
<para>URL Operationen verhalten sich auf diese Weise, da
@@ -1166,7 +1168,7 @@
Ihre Änderungen vorbereitet werden können, bevor sie in das
Repository committet werden. Befehle, die auf URLs arbeiten,
haben diesen Luxus nicht, so dass die Arbeit direkt mit
- einem URL bei den obigen Aktionen einen sofortigen Commit
+ einem URL bei den oben genannten Aktionen einen sofortigen Commit
repräsentiert.</para>
</sidebar>
@@ -1216,36 +1218,36 @@
<title>Guck mal, Mutti, kein Netzwerk!</title>
<!--
- <para>The commands <command>svn status</command>,
+ <para>You can use the commands <command>svn status</command>,
<command>svn diff</command>, and <command>svn
- revert</command> can be used without any network access even
+ revert</command> without any network access even
if your repository <emphasis>is</emphasis> across the
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
+ connection, such as traveling on an airplane, riding a
commuter train, or hacking on the beach.
<footnote>
- <para>And also that you don't have a WLAN card. Thought
+ <para>And you don't have a WLAN card. Thought
you got us, huh?</para>
</footnote>
</para>
-->
- <para>Die Befehle <command>svn status</command>,
+ <para>Sie können die Befehle <command>svn status</command>,
<command>svn diff</command> und <command>svn
- revert</command> können ohne Netzzugriff verwendet werden,
+ revert</command> ohne Netzzugriff verwenden,
selbst wenn das Repository im Netz <emphasis>ist</emphasis>.
Das macht es leicht, Ihre momentanen Änderungen zu
verwalten, wenn Sie irgendwo ohne Netzverbindung sind, etwa
im Flugzeug, im Pendlerzug oder am Strand.
<footnote>
- <para>Und auch keine WLAN-Karte haben. Sie dachten wohl,
+ <para>Und Sie haben keine WLAN-Karte. Sie dachten wohl,
Sie kriegen uns, was?</para>
</footnote>
</para>
<!--
<para>Subversion does this by keeping private caches of
- pristine versions of each versioned file inside of the
+ pristine versions of each versioned file inside the
<filename>.svn</filename> administrative areas. This allows
Subversion to report—and revert—local
modifications to those files <emphasis>without network
@@ -1255,7 +1257,7 @@
a compressed <firstterm>delta</firstterm> (or
<quote>difference</quote>) against the pristine version.
Having this cache is a tremendous benefit—even if you
- have a fast net connection, it's much faster to send only a
+ have a fast Internet connection, it's much faster to send only a
file's changes rather than the whole file to the
server.</para>
-->
@@ -1271,7 +1273,7 @@
<quote>Differenz</quote>) gegenüber der unveränderten
Version zum Server zu senden. Diesen Cache zu haben,
bedeutet einen riesigen Vorteil—selbst wenn Sie eine
- schnelle Netzverbindung haben, ist es viel schneller, nur
+ schnelle Internet-Verbindung haben, ist es viel schneller, nur
die Änderungen an einer Datei an den Server zu übermitteln,
anstatt die gesamte Datei.</para>
@@ -1281,8 +1283,8 @@
<para>Subversion has been optimized to help you with this task,
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.
+ 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
changes without contacting the repository.</para>
@@ -1343,15 +1345,15 @@
Änderungen von anderen Benutzern einzupflegen.</para>
<!--
- <para>In Subversion, <command>update</command> does just
+ <para>In Subversion, <command>svn update</command> does just
that—it updates your working copy with any changes
- committed to the repository since the last time you've
+ committed to the repository since the last time you
updated your working copy. You may have to break the
habit of using the <command>update</command> command to
see what local modifications you've made.</para>
-->
- <para>In Subversion, <command>update</command> macht genau
- das —es aktualisiert Ihre Arbeitskopie mit jeglichen
+ <para>In Subversion, <command>svn update</command> macht genau
+ das—es aktualisiert Ihre Arbeitskopie mit jeglichen
Änderungen, die seit Ihrer letzten Aktualisierung in das
Repository eingebracht worden sind. Sie sollten sich
abgewöhnen, <command>update</command> zu verwenden, um
@@ -1363,7 +1365,7 @@
<!--
<para>If you run <command>svn status</command> at the top of
your working copy with no arguments, it will detect all file
- and tree changes you've made. Below are a few examples of
+ and tree changes you've made. Here are a few examples of
the most common status codes that <command>svn
status</command> can return. (Note that the text following
<literal>#</literal> is not
@@ -1371,8 +1373,8 @@
-->
<para>Wenn Sie <command>svn status</command> ganz oben in
Ihrer Arbeitskopie aufrufen, werden alle Datei- und
- Verzeichnisbaumänderungen die Sie gemacht haben erfasst. Es
- folgen einige Beispiele der häufigsten Statuscodes, die
+ Verzeichnisbaumänderungen die Sie gemacht haben erfasst.
+ Hier sind einige Beispiele der häufigsten Statuscodes, die
<command>svn status</command> zurückgeben kann. (Beachten
Sie, dass der Text, der <literal>#</literal> folgt, nicht
von <command>svn status</command> ausgegeben wird.)</para>
@@ -1554,7 +1556,7 @@
<!--
<para>Notice the two asterisks: if you were to run
- <command>svn update</command> at this point, you would
+ <userinput>svn update</userinput> at this point, you would
receive changes to <filename>README</filename>
and <filename>trout.c</filename>. This tells you some very
useful information—you'll need to update and get the
@@ -1563,7 +1565,7 @@
out of date (more on this subject later).</para>
-->
<para>Beachten Sie die zwei Sternchen: wenn Sie an dieser
- Stelle <command>svn update</command> aufrufen würden,
+ Stelle <userinput>svn update</userinput> aufrufen würden,
erhielten Sie Änderungen an <filename>README</filename> und
<filename>trout.c</filename>. Das gibt Ihnen einige sehr
wichtige Informationen—Sie müssen aktualisieren, um
@@ -1599,16 +1601,17 @@
<para>Another way to examine your changes is with the
<command>svn diff</command> command. You can find out
<emphasis>exactly</emphasis> how you've modified things by
- running <command>svn diff</command> with no arguments, which
+ running <userinput>svn diff</userinput> with no arguments, which
prints out file changes in <firstterm>unified diff
format</firstterm>:</para>
-->
<para>Eine andere Möglichkeit, Ihre Änderungen zu untersuchen,
ist, den <command>svn diff</command> Befehl zu verwenden.
Sie können <emphasis>genau</emphasis> herausfinden, wie sie
- etwas geändert haben, indem Sie <command>svn diff</command>
- ohne Argumente aufrufen, das Ihnen Dateiänderungen im
- <firstterm>unified diff Format</firstterm> anzeigt:</para>
+ etwas geändert haben, indem Sie <userinput>svn
+ diff</userinput> ohne Argumente aufrufen, das Ihnen
+ Dateiänderungen im <firstterm>unified diff
+ Format</firstterm> anzeigt:</para>
<screen>
$ svn diff
@@ -1695,9 +1698,9 @@
<!--
<para>You could, for example, email the patch file to another
- developer for review or testing prior to commit.</para>
+ developer for review or testing prior to a commit.</para>
-->
- <para>Zum Beispiel können Sie die Patchdatei vor dem Commit an
+ <para>Zum Beispiel können Sie die Patchdatei vor einem Commit an
einen anderen Entwickler zur Kontrolle oder zum Testen
schicken.</para>
@@ -1710,8 +1713,8 @@
(<option>-x</option>) option. For example, to see local
differences in file <filename>foo.c</filename> in context
output format while ignoring case differences, you might run
- <command>svn diff - -diff-cmd /usr/bin/diff - -extensions '-i'
- foo.c</command>.</para>
+ <userinput>svn diff - -diff-cmd /usr/bin/diff - -extensions '-i'
+ foo.c</userinput>.</para>
-->
<para>Subversion verwendet seinen eingebauten
diff-Algorithmus, der standardmässig das unified diff Format
@@ -1723,8 +1726,8 @@
Um z.B. lokale Unterschiede in der Datei
<filename>foo.c</filename> im Kontext-Ausgabeformat anzeigen
zu lassen und dabei die Gross- und Kleinschreibung zu
- ignorieren, könnten Sie <command>svn diff --diff-cmd
- /usr/bin/diff --extensions '-i' foo.c</command>
+ ignorieren, könnten Sie <userinput>svn diff --diff-cmd
+ /usr/bin/diff --extensions '-i' foo.c</userinput>
aufrufen.</para>
</sect3>
@@ -1801,21 +1804,20 @@
<note>
<!--
- <para><command>svn revert</command>
- <replaceable>ITEM</replaceable> has exactly the same
- effect as deleting <replaceable>ITEM</replaceable> from
- your working copy and then running <command>svn update -r
- BASE</command> <replaceable>ITEM</replaceable>. However,
+ <para><userinput>svn revert <replaceable>item</replaceable></userinput> has exactly the same
+ effect as deleting <replaceable>item</replaceable> from
+ your working copy and then running <userinput>svn update -r
+ BASE <replaceable>item</replaceable></userinput>. However,
if you're reverting a file, <command>svn revert</command>
has one very noticeable difference—it doesn't have
to communicate with the repository to restore your
file.</para>
-->
- <para><command>svn revert</command>
- <replaceable>ITEM</replaceable> hat genau denselben Effekt,
- wie <replaceable>ITEM</replaceable> aus der Arbeitskopie zu
+ <para><userinput>svn revert <replaceable>item</replaceable></userinput>
+ hat genau denselben Effekt, wie
+ <replaceable>item</replaceable> aus der Arbeitskopie zu
löschen und dann<command>svn update -r BASE</command>
- <replaceable>ITEM</replaceable> aufzurufen. Allerdings hat
+ <replaceable>item</replaceable> aufzurufen. Allerdings hat
<command>svn revert</command> beim Rückgängigmachen einer
Datei einen merklichen Unterschied—es muss beim
Wiederherstellen der Datei nicht Verbindung mit dem
@@ -1851,12 +1853,12 @@
<title>Konflikte auflösen (Änderungen anderer einarbeiten)</title>
<!--
- <para>We've already seen how <command>svn status -u</command>
- can predict conflicts. Suppose you run <command>svn
- update</command> and some interesting things occur:</para>
+ <para>We've already seen how <userinput>svn status -u</userinput>
+ can predict conflicts. Suppose you run <userinput>svn
+ update</userinput> and some interesting things occur:</para>
-->
- <para>Wir haben bereits gesehen, wie <command>svn status
- -u</command> Konflikte vorhersagen kann. Angenommen, Sie
+ <para>Wir haben bereits gesehen, wie <userinput>svn status
+ -u</userinput> Konflikte vorhersagen kann. Angenommen, Sie
starten <command>svn update</command> und einige interessante
Dinge passieren:</para>
@@ -1934,7 +1936,7 @@
<variablelist>
<varlistentry>
- <term><computeroutput>(p)ostpone</computeroutput></term>
+ <term>(<computeroutput>p</computeroutput>)ostpone</term>
<listitem>
<!--
@@ -1951,7 +1953,7 @@
<varlistentry>
- <term><computeroutput>(d)iff</computeroutput></term>
+ <term>(<computeroutput>d</computeroutput>)iff</term>
<listitem>
<!--
@@ -1966,7 +1968,7 @@
<varlistentry>
- <term><computeroutput>(e)dit</computeroutput></term>
+ <term>(<computeroutput>e</computeroutput>)dit</term>
<listitem>
<!--
@@ -1983,7 +1985,7 @@
<varlistentry>
- <term><computeroutput>(r)esolved</computeroutput></term>
+ <term>(<computeroutput>r</computeroutput>)esolved</term>
<listitem>
<!--
@@ -2002,7 +2004,7 @@
</varlistentry>
<varlistentry>
- <term><computeroutput>(m)ine-(f)ull</computeroutput></term>
+ <term>(<computeroutput>m</computeroutput>)ine-(<computeroutput>f</computeroutput>)ull</term>
<listitem>
<!--
@@ -2017,7 +2019,7 @@
</varlistentry>
<varlistentry>
- <term><computeroutput>(t)heirs-(f)ull</computeroutput></term>
+ <term>(<computeroutput>t</computeroutput>)heirs-(<computeroutput>f</computeroutput>)ull</term>
<listitem>
<!--
@@ -2033,7 +2035,7 @@
</varlistentry>
<varlistentry>
- <term><computeroutput>(l)aunch</computeroutput></term>
+ <term>(<computeroutput>l</computeroutput>)aunch</term>
<listitem>
<!--
@@ -2048,7 +2050,7 @@
</varlistentry>
<varlistentry>
- <term><computeroutput>(h)elp</computeroutput></term>
+ <term>(<computeroutput>h</computeroutput>)elp</term>
<listitem>
<!--
@@ -2077,9 +2079,9 @@
<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,
+ odds are that you'd like to see exactly what is in conflict,
and the <firstterm>diff</firstterm> command
- (<command>d</command>) is what you'll use for this:</para>
+ (<userinput>d</userinput>) is what you'll use for this:</para>
<screen>
…
@@ -2119,7 +2121,7 @@
<para>If you wish to choose some combination of your local
changes, you can use the <quote>edit</quote> command
- (<command>e</command>) to manually edit the file with
+ (<userinput>e</userinput>) to manually edit the file with
conflict markers in a text editor (determined by the
<literal>EDITOR</literal> environment variable). Editing
the file by hand in your favorite text editor is a somewhat
@@ -2128,16 +2130,16 @@
walkthrough), so some people like to use fancy graphical
merge tools instead.</para>
- <para>In order to use a merge tool, you need to either set the
+ <para>To use a merge tool, you need to either set the
<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).
- Subversion will pass four arguments to the merge tool: The
+ Subversion will pass four arguments to the merge tool: the
<literal>BASE</literal> revision of the file, the revision
of the file received from the server as part of the update,
the copy of the file containing your local edits, and
- lastly, the merged copy of the file (which contains conflict
+ the merged copy of the file (which contains conflict
markers). If your merge tool is expecting arguments in a
different order or format, you'll need to write a wrapper
script for Subversion to invoke. After you've edited the
@@ -2151,11 +2153,11 @@
<para>If you decide that you don't need to merge any changes,
but just want to accept one version of the file or the
- other, you can either choose your changes (aka
+ other, you can either choose your changes (a.k.a.
<quote>mine</quote>) by using the <quote>mine-full</quote>
- command (<command>mf</command>) or choose theirs by using the
+ command (<userinput>mf</userinput>) or choose theirs by using the
<quote>theirs-full</quote> command
- (<command>tf</command>).</para>
+ (<userinput>tf</userinput>).</para>
</sect3>
@@ -2168,9 +2170,9 @@
marital disagreements, but it's actually still about
Subversion, so read on. If you're doing an update and
encounter a conflict that you're not prepared to review or
- resolve, you can type <command>p</command> to postpone
+ resolve, you can type <userinput>p</userinput> to postpone
resolving a conflict on a file-by-file basis when you run
- <command>svn update</command>. If you're running an update
+ <userinput>svn update</userinput>. 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
@@ -2201,7 +2203,7 @@
delimit the <quote>sides</quote> of the
conflict—into the file to visibly demonstrate the
overlapping areas. (Subversion uses the
- <literal>svn:mime-type</literal> property to decide if a
+ <literal>svn:mime-type</literal> property to decide whether a
file is capable of contextual, line-based merging. See
<xref linkend="svn.advanced.props.special.mime-type"/>
to learn more.)</para>
@@ -2220,7 +2222,7 @@
copy before you updated your working copy—that
is, without conflict markers. This file has only
your latest changes in it. (If Subversion considers
- the file to be unmergeable, then the
+ the file to be unmergeable, the
<filename>.mine</filename> file isn't created, since
it would be identical to the working file.)</para>
</listitem>
@@ -2283,7 +2285,7 @@
<para>At this point, Subversion will <emphasis>not</emphasis>
allow Sally to commit the file
<filename>sandwich.txt</filename> until the three temporary
- files are removed.</para>
+ files are removed:</para>
<screen>
$ svn commit -m "Add a few more things"
@@ -2318,10 +2320,10 @@
argument.</para>
<para><command>svn resolve</command> removes the three
- temporary files, accepts the version of the file that you
+ temporary files and accepts the version of the file that you
specified with the <option>--accept</option> option, and
Subversion no longer considers the file to be in a state of
- conflict.</para>
+ conflict:</para>
<screen>
$ svn resolve --accept working sandwich.txt
@@ -2343,7 +2345,7 @@
<filename>sandwich.txt</filename> at the same time. Sally
commits her changes, and when you go to update your working
copy, you get a conflict and you're going to have to edit
- <filename>sandwich.txt</filename> to resolve the conflicts.
+ <filename>sandwich.txt</filename> to resolve the conflict.
First, let's take a look at the file:</para>
<screen>
@@ -2365,7 +2367,7 @@
Bottom piece of bread
</screen>
- <para>The strings of less-than signs, equal signs, and
+ <para>The strings of less-than signs, equals signs, and
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
@@ -2394,7 +2396,7 @@
<para>Usually you won't want to just delete the conflict
markers and Sally's changes—she's going to be awfully
surprised when the sandwich arrives and it's not what she
- wanted. So this is where you pick up the phone or walk
+ wanted. 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>
@@ -2402,7 +2404,7 @@
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>
+ your file and remove the conflict markers:</para>
<screen>
Top piece of bread
@@ -2417,7 +2419,7 @@
Bottom piece of bread
</screen>
- <para>Now run <command>svn resolve</command>, and you're
+ <para>Now use <command>svn resolve</command>, and you're
ready to commit your changes:</para>
<screen>
@@ -2429,7 +2431,7 @@
<para>Note that <command>svn resolve</command>, unlike most of
the other commands we deal with in this chapter, requires
that you explicitly list any filenames that you wish to
- resolve. In any case, you want to be careful and run
+ resolve. In any case, you want to be careful and use
<command>svn resolve</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
@@ -2449,8 +2451,8 @@
<title>Discarding your changes in favor of a newly fetched revision</title>
<para>If you get a conflict and decide that you want to throw
- out your changes, you can run <command>svn resolve --accept
- theirs-full</command> and Subversion will discard your edits
+ out your changes, you can run <userinput>svn resolve --accept
+ theirs-full <replaceable>CONFLICTED-PATH</replaceable></userinput> and Subversion will discard your edits
and remove the temporary files:</para>
<screen>
@@ -2470,10 +2472,10 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.cycle.resolve.revert">
- <title>Punting: using <command>svn revert</command></title>
+ <title>Punting: using svn revert</title>
<para>If you decide that you want to throw out your changes
- and start your edits again (Whether this occurs after a
+ and start your edits again (whether this occurs after a
conflict or anytime), just revert your changes:</para>
<screen>
@@ -2484,7 +2486,7 @@
</screen>
<para>Note that when you revert a conflicted file, you don't
- have to run <command>svn resolve</command>.</para>
+ have to use <command>svn resolve</command>.</para>
</sect3>
@@ -2500,7 +2502,7 @@
<para>The <command>svn commit</command> command sends all of
your changes to the repository. When you commit a change, you
- need to supply a <firstterm>log message</firstterm>,
+ need to supply a <firstterm>log message</firstterm>
describing your change. Your log message will be attached to
the new revision you create. If your log message is brief,
you may wish to supply it on the command line using the
@@ -2528,8 +2530,8 @@
<para>If you fail to specify either the
<option>--message</option> or <option>--file</option> option,
- then Subversion will automatically launch your favorite editor
- (see the <literal>editor-cmd</literal> section in
+ Subversion will automatically launch your favorite editor
+ (see the information on <literal>editor-cmd</literal> in
<xref linkend="svn.advanced.confarea.opts.config"/>) for composing a log
message.</para>
@@ -2538,7 +2540,7 @@
decide that you want to cancel your commit, you can just
quit your editor without saving changes. If you've already
saved your commit message, simply delete the text, save
- again, then abort.</para>
+ again, and then abort:</para>
<screen>
$ svn commit
@@ -2551,12 +2553,12 @@
</screen>
</tip>
- <para>The repository doesn't know or care if your changes make
- any sense as a whole; it checks only to make sure that nobody
+ <para>The repository doesn't know or care whether your changes make
+ any sense as a whole; it checks only to make sure 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 are out of date:</para>
<screen>
$ svn commit -m "Add another rule"
@@ -2570,12 +2572,12 @@
network protocol and server you're using, but the idea is the
same in all cases.)</para>
- <para>At this point, you need to run <command>svn
- update</command>, deal with any merges or conflicts that
+ <para>At this point, you need to run <userinput>svn
+ update</userinput>, deal with any merges or conflicts that
result, and attempt your commit again.</para>
<para>That covers the basic work cycle for using Subversion.
- There are many other features in Subversion that you can use
+ Subversion offers many other features that you can use
to manage your repository and working copy, but most of your
day-to-day use of Subversion will involve only the commands
that we've discussed so far in this chapter. We will,
@@ -2602,7 +2604,7 @@
just want to <emphasis>peer into</emphasis> the past instead of
<emphasis>going into</emphasis> it.</para>
- <para>There are several commands that can provide you with
+ <para>Several commands can provide you with
historical data from the repository:</para>
<variablelist>
@@ -2612,14 +2614,14 @@
<listitem>
<para>Shows you broad information: log messages with date
and author information attached to revisions and which
- paths changed in each revision.</para>
+ paths changed in each revision</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>svn diff</command></term>
<listitem>
- <para>Shows line-level details of a particular change.</para>
+ <para>Shows line-level details of a particular change</para>
</listitem>
</varlistentry>
@@ -2627,7 +2629,7 @@
<term><command>svn cat</command></term>
<listitem>
<para>Retrieves a file as it existed in a particular
- revision number and displays it on your screen.</para>
+ revision number and displays it on your screen</para>
</listitem>
</varlistentry>
@@ -2635,7 +2637,7 @@
<term><command>svn list</command></term>
<listitem>
<para>Displays the files in a directory for any given
- revision.</para>
+ revision</para>
</listitem>
</varlistentry>
@@ -2652,7 +2654,7 @@
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>
+ the commit:</para>
<screen>
$ svn log
@@ -2702,11 +2704,11 @@
<sidebar>
- <title>Why Does <command>svn log</command> Not Show Me What I
+ <title>Why Does svn log Not Show Me What I
Just Committed?</title>
- <para>If you make a commit and immediately type <command>svn
- log</command> with no arguments, you may notice that your
+ <para>If you make a commit and immediately type <userinput>svn
+ log</userinput> with no arguments, you may notice that your
most recent commit doesn't show up in the list of log
messages. This is due to a combination of the behavior of
<command>svn commit</command> and the default behavior of
@@ -2756,7 +2758,7 @@
gives just the names of the changed files.</para>
<sidebar>
- <title>Why Does <command>svn log</command> Give Me an Empty
+ <title>Why Does svn log Give Me an Empty
Response?</title>
<para>After working with Subversion for a bit, most users will
@@ -2778,8 +2780,8 @@
nor any of its children was changed, Subversion will show you
an empty log. If you want to see what changed in that
revision, try pointing <command>svn log</command> directly at
- the top-most URL of your repository, as in <command>svn log -r 2
- http://svn.collab.net/repos/svn</command>.</para>
+ the topmost URL of your repository, as in <userinput>svn log -r 2
+ http://svn.collab.net/repos/svn</userinput>.</para>
</sidebar>
@@ -2791,7 +2793,7 @@
<para>We've already seen <command>svn diff</command>
before—it displays file differences in unified diff
- format; it was used to show the local modifications made to
+ format; we used it to show the local modifications made to
our working copy before committing to the repository.</para>
<para>In fact, it turns out that there are
@@ -2801,7 +2803,7 @@
<itemizedlist>
<listitem>
- <para>Examining Local Changes</para>
+ <para>Examining local changes</para>
</listitem>
<listitem>
@@ -2809,7 +2811,7 @@
</listitem>
<listitem>
- <para>Comparing repository to repository</para>
+ <para>Comparing one repository to another</para>
</listitem>
</itemizedlist>
@@ -2818,7 +2820,7 @@
<sect3 id="svn.tour.history.diff.local">
<title>Examining local changes</title>
- <para>As we've seen, invoking <command>svn diff</command> with
+ <para>As we've seen, invoking <userinput>svn diff</userinput> with
no options will compare your working files to the cached
<quote>pristine</quote> copies in
the <filename>.svn</filename> area:</para>
@@ -2846,9 +2848,9 @@
<title>Comparing working copy to repository</title>
<para>If a single <option>--revision</option>
- (<option>-r</option>) number is passed, then your
+ (<option>-r</option>) number is passed, your
working copy is compared to the specified revision in the
- repository.</para>
+ repository:</para>
<screen>
$ svn diff -r 3 rules.txt
@@ -2874,7 +2876,7 @@
<para>If two revision numbers, separated by a colon, are
passed via <option>--revision</option>
- (<option>-r</option>), then the two revisions are directly
+ (<option>-r</option>), the two revisions are directly
compared:</para>
<screen>
@@ -2892,7 +2894,7 @@
$
</screen>
- <para>A more convenient way of comparing a revision to the
+ <para>A more convenient way of comparing one revision to the
previous revision is to use the <option>--change</option>
(<option>-c</option>) option:</para>
@@ -2937,7 +2939,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.history.browsing.cat">
- <title><command>svn cat</command></title>
+ <title>svn cat</title>
<para>If you want to examine an earlier version of a file and
@@ -2965,7 +2967,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.history.browsing.list">
- <title><command>svn list</command></title>
+ <title>svn list</title>
<para>The <command>svn list</command> command shows you what
files are in a repository directory without actually
@@ -2999,7 +3001,7 @@
name.</para>
<warning>
- <para>The <command>svn list</command> with no arguments
+ <para>The <userinput>svn list</userinput> 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 want a
@@ -3044,7 +3046,7 @@
<para>Lastly, if you're building a release and wish to bundle up
your files from Subversion but don't want those
- pesky <filename>.svn</filename> directories in the way, then
+ pesky <filename>.svn</filename> directories in the way,
you can use <command>svn export</command> to create a local
copy of all or part of your repository
sans <filename>.svn</filename> directories. As
@@ -3081,7 +3083,7 @@
<title>Disposing of a Working Copy</title>
- <para>Subversion doesn't track either the state or existence of
+ <para>Subversion doesn't track either the state or the existence of
working copies on the server, so there's no server overhead to
keeping working copies around. Likewise, there's no need to
let the server know that you're going to delete a working
@@ -3096,8 +3098,8 @@
<para>However, if you're definitely not going to use a working
copy again, you can safely delete the entire thing, but you'd
be well served to take a look through the working copy for
- unversioned files. To find these files, run <command>svn
- status</command> and review any files that are prefixed by a
+ unversioned files. To find these files, run <userinput>svn
+ status</userinput> and review any files that are prefixed with a
<literal>?</literal> to make certain that they're not of
importance. After you're done reviewing, you can safely
delete your working copy.</para>
@@ -3111,16 +3113,16 @@
<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
- executes the commands in the log file to apply the requested
+ Subversion writes its intentions to a logfile. Next, it
+ executes the commands in the logfile 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 mid-change. Finally,
- Subversion removes the log file. Architecturally, this is
+ Subversion removes the logfile. Architecturally, this is
similar to a journaled filesystem. If a Subversion operation
- 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
+ is interrupted (e.g., if the process is killed or if the machine
+ crashes), the logfiles remain on disk. By
+ reexecuting the logfiles, Subversion can complete the
previously started operation, and your working copy can get
itself back into a consistent state.</para>
@@ -3128,7 +3130,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> this is the command that you
should run. Also, <command>svn status</command> will display
an <literal>L</literal> next to locked items:</para>
@@ -3144,8 +3146,8 @@
<para>Don't confuse these working copy locks with the ordinary
locks that Subversion users create when using
- the <quote>lock-modify-unlock</quote> model of concurrent
- version control; see
+ the lock-modify-unlock model of concurrent
+ version control; see the sidebar
<xref linkend="svn.advanced.locking.meanings"/> for
clarification.</para>
@@ -3164,7 +3166,7 @@
merging (see <xref linkend="svn.branchmerge"/>) and properties (see
<xref linkend="svn.advanced.props"/>). However, you may want to
take a moment to skim through <xref linkend="svn.ref"/> to
- get an idea of all the many different commands that Subversion
+ get an idea of all the different commands that Subversion
has—and how you can use them to make your work
easier.</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 Tue Aug 12 11:40:38 2008
@@ -8,7 +8,7 @@
check out a working copy from a Subversion repository. You are
comfortable with submitting and receiving changes using the
<command>svn commit</command> and <command>svn update</command>
- functions. You've probably even developed a reflex that causes
+ operations. You've probably even developed a reflex that causes
you to run the <command>svn status</command> command almost
unconsciously. For all intents and purposes, you are ready to
use Subversion in a typical environment.</para>
@@ -129,7 +129,7 @@
<para>The revision immediately <emphasis>before</emphasis>
the last revision in which an item changed.
Technically, this boils down to
- <literal>COMMITTED</literal>-1.</para>
+ <literal>COMMITTED</literal>−1.</para>
</listitem>
</varlistentry>
@@ -396,6 +396,17 @@
information that your site needs to display without having to
read an index file or play path manipulation games.</para>
+ <note>
+ <para>While Subversion places few restrictions on the names
+ and values you use for properties, it has not been designed
+ to optimally carry large property values or large sets of
+ properties on a given file or directory. Subversion
+ commonly holds all the property names and values associated
+ with a single item in memory at the same time, which can
+ cause detrimental performance or failed operations when
+ extremely large property sets are used.</para>
+ </note>
+
<para>Custom revision properties are also frequently used. One
common such use is a property whose value contains an issue
tracker ID with which the revision is associated, perhaps
@@ -415,7 +426,7 @@
more accurately, the available interfaces to them—have
a major shortcoming: while it is a simple matter to
<emphasis>set</emphasis> a custom property,
- <emphasis>finding</emphasis> that property later is whole
+ <emphasis>finding</emphasis> that property later is a whole
different ball of wax.</para>
<para>Trying to locate a custom revision property generally
@@ -460,11 +471,11 @@
<sect2 id="svn.advanced.props.manip">
<title>Manipulating Properties</title>
- <para>The <command>svn</command> command affords a few ways to
+ <para>The <command>svn</command> program affords a few ways to
add or modify file and directory properties. For properties
with short, human-readable values, perhaps the simplest way to
add a new property is to specify the property name and value
- on the command line of the <command>propset</command>
+ on the command line of the <command>svn propset</command>
subcommand:</para>
<screen>
@@ -477,7 +488,7 @@
offers for your property values. And if you are planning to
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
+ So the <command>svn propset</command> subcommand takes a
<option>--file</option> (<option>-F</option>) option for
specifying the name of a file that contains the new property
value.</para>
@@ -561,7 +572,7 @@
<para>There's even a variation of the
<command>proplist</command> command that will list both the
- name and value of all of the properties. Simply supply the
+ name and the value for all of the properties. Simply supply the
<option>--verbose</option> (<option>-v</option>) option.</para>
<screen>
@@ -584,8 +595,8 @@
<para>The last property-related subcommand is
<command>propdel</command>. Since Subversion allows you to
store properties with empty values, you can't remove a
- property altogether using <command>propedit</command> or
- <command>propset</command>. For example, this command will
+ property altogether using <command>svn propedit</command> or
+ <command>svn propset</command>. For example, this command will
<emphasis>not</emphasis> yield the desired effect:</para>
<screen>
@@ -614,7 +625,7 @@
<para>Remember those unversioned revision properties? You can
modify those, too, using the same <command>svn</command>
subcommands that we just described. Simply add the
- <option>--revprop</option> command line parameter and specify
+ <option>--revprop</option> command-line parameter and specify
the revision whose property you wish to modify. Since
revisions are global, you don't need to specify a target path
to these property-related commands so long as you are
@@ -771,7 +782,7 @@
<para>You might also have noticed the nonstandard way that
Subversion currently displays property differences. You can
- still run <command>svn diff</command> and redirect the output
+ still use <command>svn diff</command> and redirect its output
to create a usable patch file. The <command>patch</command>
program will ignore property patches—as a rule, it
ignores any noise it can't understand. This does,
@@ -788,7 +799,7 @@
<para>Properties are a powerful feature of Subversion, acting as
key components of many Subversion features discussed elsewhere
in this and other chapters—textual diff and merge
- support, keyword substitution, newline translation, etc. But
+ support, keyword substitution, newline translation, and so on. But
to get the full benefit of properties, they must be set on the
right files and directories. Unfortunately, that
step can be easily forgotten in the routine of things, especially
@@ -809,7 +820,7 @@
linkend="svn.advanced.props.special.executable" /> later in
this chapter for more about this property.)</para>
- <para>Secondly, Subversion tries to determine the file's MIME
+ <para>Second, Subversion tries to determine the file's MIME
type. If you've configured a
<literal>mime-types-files</literal> runtime configuration
parameter, Subversion will try to find a MIME type mapping in
@@ -818,7 +829,7 @@
<literal>svn:mime-type</literal> property to the MIME type it
found. If no mapping file is configured, or no mapping for
your file's extension could be found, Subversion runs a very
- basic heuristic to determine if the file contains nontextual
+ basic heuristic to determine whether the file contains nontextual
content. If so, it automatically sets the
<literal>svn:mime-type</literal> property on that file to
<literal>application/octet-stream</literal> (the generic
@@ -840,7 +851,7 @@
and can not only override the default MIME type decision made
by Subversion during those operations, but can also set
additional Subversion or custom properties, too. For example,
- you might create a mapping that says that any time you add
+ you might create a mapping that says that anytime you add
JPEG files—ones whose names match the pattern
<literal>*.jpg</literal>—Subversion should automatically
set the <literal>svn:mime-type</literal> property on those
@@ -849,7 +860,7 @@
<literal>svn:eol-style</literal> set to
<literal>native</literal>, and <literal>svn:keywords</literal>
set to <literal>Id</literal>. Automatic property support is
- perhaps the handiest property related tool in the Subversion
+ perhaps the handiest property-related tool in the Subversion
toolbox. See <xref
linkend="svn.advanced.confarea.opts.config"/> for more about
configuring that support.</para>
@@ -920,10 +931,10 @@
<para>Unfortunately, some of those extensions have changed
their meanings over time. When personal computers first appeared,
a file named <filename>README.DOC</filename> would have
- almost certainly been a plaintext file, just like today's
- <filename>.txt</filename> files. But by the mid-1990's, you
+ almost certainly been a plain-text file, just like today's
+ <filename>.txt</filename> files. But by the mid-1990s, you
could almost bet that a file of that name would not be a
- plaintext file at all, but instead a Microsoft Word document
+ plain-text file at all, but instead a Microsoft Word document
in a proprietary, non-human-readable format. But this
change didn't occur overnight—there was certainly a
period of confusion for computer users over what exactly
@@ -942,14 +953,14 @@
dynamically by server-side scripts, there was often no real
file per se, and therefore no filename. Web
servers, for example, needed some other way to tell browsers
- what they were downloading so the browser could do something
+ what they were downloading so that the browser could do something
intelligent with that information, whether that was to
display the data using a program registered to handle that
- data type or to prompt the user for where on the client
+ datatype or to prompt the user for where on the client
machine to store the downloaded data.</para>
<para>Eventually, a standard emerged for, among other things,
- describing the contents of a data stream. In 1996, RFC2045
+ describing the contents of a data stream. In 1996, RFC 2045
was published. It was the first of five RFCs describing
MIME. It describes the concept of media types and subtypes
and recommends a syntax for the representation of those
@@ -1054,7 +1065,7 @@
<literal>svn:mime-type</literal> property, Subversion
assumes the file contains human-readable data. Generally
speaking, Subversion uses this knowledge only to determine
- if contextual difference reports for that file are
+ whether contextual difference reports for that file are
possible. Otherwise, to Subversion, bytes are bytes.</para>
<para>This means that by default, Subversion doesn't pay any
@@ -1090,7 +1101,7 @@
occur.</para>
<para>But in practice, many common tools either fail to
- properly read a file with foreign EOL markers, or they
+ properly read a file with foreign EOL markers, or
convert the file's line endings to the native style when the
file is saved. If the former is true for a developer, he
has to use an external conversion utility (such as
@@ -1101,8 +1112,8 @@
original quite literally on every line! Prior to committing
his changes, the user has two choices. Either he can use a
conversion utility to restore the modified file to the same
- line-ending style that it was in before his edits were made.
- Or, he can simply commit the file—new EOL markers and
+ line-ending style that it was in before his edits were made,
+ or he can simply commit the file—new EOL markers and
all.</para>
<para>The result of scenarios like these include wasted time
@@ -1207,7 +1218,7 @@
these things exist.</para>
<para>So Subversion provides two ways for telling it which files
- you would prefer for it to simply disregard. One of the ways
+ you would prefer that it simply disregard. One of the ways
involves the use of Subversion's runtime configuration system
(see <xref linkend="svn.advanced.confarea" />), and therefore
applies to all the Subversion operations that make use of that
@@ -1257,14 +1268,14 @@
<varlistentry>
<term><literal>?</literal></term>
<listitem>
- <para>Matches any single character.</para>
+ <para>Matches any single character</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>*</literal></term>
<listitem>
<para>Matches any string of characters, including the
- empty string.</para>
+ empty string</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -1272,7 +1283,7 @@
<listitem>
<para>Begins a character class definition terminated by
<literal>]</literal>, used for matching a subset of
- characters.</para>
+ characters</para>
</listitem>
</varlistentry>
</variablelist>
@@ -1398,19 +1409,19 @@
also have some unversioned files: the latest
<filename>calculator</filename> program that you've compiled
from your source code, a source file named
- <filename>data.c</filename>, and a set of debugging output log
- files. Now, you know that your build system always results in
+ <filename>data.c</filename>, and a set of debugging output logfiles.
+ Now, you know that your build system always results in
the <filename>calculator</filename> program being generated.
<footnote>
<para>Isn't that the whole point of a build system?</para>
</footnote>
And you know that your test suite always leaves those debugging
- log files lying around. These facts are true for all working
+ logfiles lying around. These facts are true for all working
copies of this project, not just your own. And you know that
you aren't interested in seeing those things every time you run
<command>svn status</command>, and you are pretty sure that
nobody else is interested in them either. So you use
- <command>svn propedit svn:ignore calc</command> to add some
+ <userinput>svn propedit svn:ignore calc</userinput> to add some
ignore patterns to the <filename>calc</filename> directory. For
example, you might add this as the new value of the
<literal>svn:ignore</literal> property:</para>
@@ -1476,14 +1487,14 @@
<para>Even if <literal>svn:ignore</literal> is set, you may run
into problems if you use shell wildcards in a command. Shell
wildcards are expanded into an explicit list of targets before
- Subversion operates on them, so running <command>svn
- <replaceable>SUBCOMMAND</replaceable> *</command> is just like
- running <command>svn <replaceable>SUBCOMMAND</replaceable>
- file1 file2 file3 …</command>. In the case of the
+ Subversion operates on them, so running <userinput>svn
+ <replaceable>SUBCOMMAND</replaceable> *</userinput> is just like
+ running <userinput>svn <replaceable>SUBCOMMAND</replaceable>
+ file1 file2 file3 …</userinput>. In the case of the
<command>svn add</command> command, this has an effect similar
to passing the <option>--no-ignore</option> option. So
- instead of using a wildcard, use <command>svn add --force
- .</command> to do a bulk scheduling of unversioned things for
+ instead of using a wildcard, use <userinput>svn add --force
+ .</userinput> to do a bulk scheduling of unversioned things for
addition. The explicit target will ensure that the current
directory isn't overlooked because of being already under
version control, and the <option>--force</option> option will
@@ -1515,7 +1526,7 @@
file changes, and more importantly, just
<emphasis>after</emphasis> the file changes, it is a hassle
for any process except the version control system to keep
- the data completely up-to-date. Left to human authors, the
+ the data completely up to date. Left to human authors, the
information would inevitably grow stale.</para>
<para>For example, say you have a document in which you would
@@ -1533,10 +1544,10 @@
<literal>$</literal><replaceable>KeywordName</replaceable><literal>$</literal>.</para>
<para>All keywords are case-sensitive where they appear as
- anchors in files: you must use the correct capitalization in
- order for the keyword to be expanded. You should consider the
+ anchors in files: you must use the correct capitalization
+ for the keyword to be expanded. You should consider the
value of the <literal>svn:keywords</literal> property to be
- case-sensitive too—certain keyword names will be recognized
+ case-sensitive, too—certain keyword names will be recognized
regardless of case, but this behavior is deprecated.</para>
<para>Subversion defines the list of keywords available for
@@ -1548,11 +1559,13 @@
<term><literal>Date</literal></term>
<listitem>
<para>This keyword describes the last time the file was
- known to have been changed in the repository, and
- is of the form <literal>$Date:
- 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006)
- $</literal>. It may also be specified as
- <literal>LastChangedDate</literal>.</para>
+ known to have been changed in the repository, and is of
+ the form <literal>$Date: 2006-07-22 21:42:37 -0700 (Sat,
+ 22 Jul 2006) $</literal>. It may also be specified as
+ <literal>LastChangedDate</literal>. Unlike the
+ <literal>Id</literal> keyword, which uses UTC, the
+ <literal>Date</literal> keyword displays dates using the
+ local time zone.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -1590,18 +1603,21 @@
<varlistentry>
<term><literal>Id</literal></term>
<listitem>
- <para>This keyword is a compressed combination of the
- other keywords. Its substitution looks something like
+ <para>This keyword is a compressed combination of the other
+ keywords. Its substitution looks something like
<literal>$Id: calc.c 148 2006-07-28 21:30:43Z sally
$</literal>, and is interpreted to mean that the file
<filename>calc.c</filename> was last changed in revision
148 on the evening of July 28, 2006 by the user
- <literal>sally</literal>.</para>
+ <literal>sally</literal>. The date displayed by this
+ keyword is in UTC, unlike that of the
+ <literal>Date</literal> keyword (which uses the local time
+ zone).</para>
</listitem>
</varlistentry>
</variablelist>
- <para>Several of the previous descriptions use the phrase
+ <para>Several of the preceding descriptions use the phrase
<quote>last known</quote> or similar wording. Keep in mind that
keyword expansion is a client-side operation, and your client
<quote>knows</quote> only about changes that have occurred in
@@ -1628,8 +1644,7 @@
subcommands. The <literal>svn:keywords</literal> property,
when set on a versioned file, controls which keywords will
be substituted on that file. The value is a space-delimited
- list of the keyword names or aliases found in the previous
- table.</para>
+ list of keyword names or aliases.</para>
<para>For example, say you have a versioned file named
<filename>weather.txt</filename> that looks like
@@ -1669,7 +1684,7 @@
substitute text. Instead of seeing your keyword anchor
<literal>$LastChangedDate$</literal>, you'll see its
substituted result. That result also contains the name of
- the keyword and continues to be bounded by the dollar sign
+ the keyword and continues to be delimited by the dollar sign
(<literal>$</literal>) characters. And as we predicted, the
<literal>Rev</literal> keyword was not substituted because
we didn't ask for it to be.</para>
@@ -1767,9 +1782,9 @@
committed revision rolls into a new place value (say, from
99 to 100), or if another person with a longer username
commits the file, stuff gets all crooked again. However, if
- you are using Subversion 1.2 or better, you can use the new
+ you are using Subversion 1.2 or later, you can use the new
fixed-length keyword syntax and define some field widths that
- seem sane so your file might look like this:</para>
+ seem sane, so your file might look like this:</para>
<screen>
$Rev:: $: Revision of last commit
@@ -1862,8 +1877,8 @@
$
</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 directory
+ <para>Now, let's check out the same tree again, but this time
+ we'll ask Subversion to give us only the topmost directory
with none of its children at all:</para>
<screen>
@@ -1971,7 +1986,7 @@
</screen>
<para>As described, each of these depths is something more than
- only-the-target, but something less than full recursion.</para>
+ only the target, but something less than full recursion.</para>
<para>We've used <command>svn checkout</command> as an example
here, but you'll find the <option>--depth</option> option
@@ -1996,8 +2011,8 @@
<option>--set-depth</option>. It is with this option that you
can change the sticky depth of a working copy item. Watch what
happens as we take our empty-depth checkout and gradually
- telescope it deeper using <command>svn update
- --set-depth</command>:</para>
+ telescope it deeper using <userinput>svn update
+ --set-depth <replaceable>NEW-DEPTH</replaceable> <replaceable>TARGET</replaceable></userinput>:</para>
<screen>
$ svn update --set-depth files mom-empty
@@ -2056,7 +2071,7 @@
in a single working copy doesn't complicate the way you interact
with that working copy. You can still make, revert, display,
and commit local modifications in your working copy without
- providing any new options (including <option>--depth</option> or
+ providing any new options (including <option>--depth</option> and
<option>--set-depth</option>) to the relevant subcommands. Even
<command>svn update</command> works as it does elsewhere when no
specific depth is provided—it updates the working copy
@@ -2070,9 +2085,9 @@
projects or software modules living as siblings in a single
repository location (<filename>trunk/project1</filename>,
<filename>trunk/project2</filename>,
- <filename>trunk/project3</filename>, and so on). In such
- scenarios, it might be the case that you personally care only
- about a handful of those projects—maybe some primary
+ <filename>trunk/project3</filename>, etc.). In such
+ scenarios, it might be the case that you personally care
+ about only a handful of those projects—maybe some primary
project and a few other modules on which it depends. You can
check out individual working copies of all of these things, but
those working copies are disjoint and, as a result, it can be
@@ -2089,10 +2104,10 @@
<para>Subversion 1.5's implementation of shallow checkouts is
good but does not support a couple of interesting behaviors.
First, you cannot de-telescope a working copy item. Running
- <command>svn update --set-depth empty</command> on an
+ <userinput>svn update --set-depth empty</userinput> in an
infinite-depth working copy will not have the effect of
- discarding everything but the top-most directory—it will
- simply error out. Secondly, there is no depth value to indicate
+ discarding everything but the topmost directory—it will
+ simply error out. Second, there is no depth value to indicate
that you wish an item to be explicitly excluded. You have to do
implicit exclusion of an item by including everything
else.</para>
@@ -2119,7 +2134,7 @@
granularity of a word or a single character of text. But common
among those algorithms is that they generally work only on text
files. The landscape starts to look pretty grim when you start
- talking about content merges of non-textual file formats. And
+ talking about content merges of nontextual file formats. And
when you can't find a tool that can handle that type of merging,
you begin to run into problems with the copy-modify-merge
model.</para>
@@ -2128,7 +2143,7 @@
aground. Harry and Sally are both graphic designers working on
the same project, a bit of marketing collateral for an
automobile mechanic. Central to the design of a particular
- poster is an image of a car in need of some body work, stored in
+ poster is an image of a car in need of some bodywork, stored in
a file using the PNG image format. The poster's layout is
almost finished, and both Harry and Sally are pleased with the
particular photo they chose for their damaged car—a baby
@@ -2145,7 +2160,7 @@
greater impact. He, too, updates to <literal>HEAD</literal>,
and then draws some cracks on the vehicle's windshield. He
manages to finish his work before Sally finishes hers, and after
- admiring the fruits of his undeniable talent, commits the
+ admiring the fruits of his undeniable talent, he commits the
modified image. Shortly thereafter, Sally is finished with the
car's new finish and tries to commit her changes. But, as
expected, Subversion fails the commit, informing Sally that
@@ -2189,29 +2204,18 @@
checkouts</quote> mechanisms of other version control
systems.</para>
- <para>Subversion's locking feature serves two main
- purposes:</para>
-
- <orderedlist>
- <listitem>
- <para><emphasis>Serializing access to a versioned
- object</emphasis>. By allowing a user to
- programmatically claim the exclusive right to change to a
- file in the repository, that user can be reasonably
- confident that energy invested on unmergeable changes won't
- be wasted—his commit of those changes will succeed.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Aiding communication</emphasis>. By alerting
- other users that serialization is in effect for a particular
- versioned object, those other users can reasonably expect
- that the object is about to be changed by someone else,
- and they, too, can avoid wasting their time and energy on
- unmergeable changes that won't be committable due to eventual
- out-of-dateness.</para>
- </listitem>
- </orderedlist>
+ <para>Subversion's locking feature exists ultimately to minimize
+ wasted time and effort. By allowing a user to programmatically
+ claim the exclusive right to change a file in the repository,
+ that user can be reasonably confident that any energy he invests
+ on unmergeable changes won't be wasted—his commit of those
+ changes will succeed. Also, because Subversion communicates to
+ other users that serialization is in effect for a particular
+ versioned object, those users can reasonably expect that the
+ object is about to be changed by someone else. They, too, can
+ then avoid wasting their time and energy on unmergeable changes
+ that won't be committable due to eventual
+ out-of-dateness.</para>
<para>When referring to Subversion's locking feature, one is
actually talking about a fairly diverse collection of behaviors,
@@ -2245,7 +2249,7 @@
<command>svn cleanup</command> command, as described in <xref
linkend="svn.tour.cleanup"/>.</para>
- <para>Thirdly, there are <firstterm>database locks</firstterm>,
+ <para>Third, there are <firstterm>database locks</firstterm>,
used internally by the Berkeley DB backend to prevent clashes
between multiple programs trying to access the database. This
is the sort of lock whose unwanted persistence after an error
@@ -2278,7 +2282,7 @@
repository will demand two pieces of information—that
the client performing the commit be authenticated as the lock
owner, and that the lock token has been provided as part of
- the commit process as a sort of proof that client knows which
+ the commit process as a form of proof that the client knows which
lock it is using.</para>
<para>To demonstrate lock creation, let's refer back to our
@@ -2295,20 +2299,20 @@
$
</screen>
- <para>There are a number of new things demonstrated in the
- previous example. First, notice that Harry passed the
+ <para>The preceding example demonstrates a number of new things.
+ First, notice that Harry passed the
<option>--message</option> (<option>-m</option>) option to
<command>svn lock</command>. Similar to <command>svn
commit</command>, the <command>svn lock</command> command can
- take comments (either via <option>--message</option>
+ take comments—via either <option>--message</option>
(<option>-m</option>) or <option>--file</option>
- (<option>-F</option>) to describe the reason for locking the
+ (<option>-F</option>)—to describe the reason for locking the
file. Unlike <command>svn commit</command>, however,
<command>svn lock</command> will not demand a message by
launching your preferred text editor. Lock comments are
optional, but still recommended to aid communication.</para>
- <para>Secondly, the lock attempt succeeded. This means that the
+ <para>Second, the lock attempt succeeded. This means that the
file wasn't already locked, and that Harry had the latest
version of the file. If Harry's working copy of the file had
been out of date, the repository would have rejected the
@@ -2366,8 +2370,8 @@
<para>A lock token isn't an authentication token, so much as
an <emphasis>authorization</emphasis> token. The token
isn't a protected secret. In fact, a lock's unique token is
- discoverable by anyone who runs <command>svn info
- URL</command>. A lock token is special only when it lives
+ discoverable by anyone who runs <userinput>svn info
+ <replaceable>URL</replaceable></userinput>. A lock token is special only when it lives
inside a working copy. It's proof that the lock was created
in that particular working copy, and not somewhere else by
some other client. Merely authenticating as the lock owner
@@ -2381,8 +2385,8 @@
authenticated as the lock's owner. In other words, the lock
token prevents one piece of Subversion-related software from
undermining the work of another. (In our example, if you
- really need to change the file from an alternate working
- copy, you would need to <firstterm>break</firstterm> the lock and re-lock the
+ really need to change the file from an alternative working
+ copy, you would need to <firstterm>break</firstterm> the lock and relock the
file.)</para>
</sidebar>
@@ -2420,7 +2424,7 @@
<para>Notice that after the commit is finished, <command>svn
status</command> shows that the lock token is no longer
- present in working copy. This is the standard behavior of
+ present in the working copy. This is the standard behavior of
<command>svn commit</command>—it searches the working
copy (or list of targets, if you provide such a list) for
local modifications and sends all the lock tokens it
@@ -2432,8 +2436,8 @@
being sloppy about locking or from holding locks for too long.
If Harry haphazardly locks 30 files in a directory named
<filename>images</filename> because he's unsure of which files
- he needs to change, yet changes only 4 of those files, when he
- runs <command>svn commit images</command>, the process will
+ he needs to change, yet changes only four of those files, when he
+ runs <userinput>svn commit images</userinput>, the process will
still release all 30 locks.</para>
<para>This behavior of automatically releasing locks can be
@@ -2461,8 +2465,8 @@
<title>Discovering Locks</title>
<para>When a commit fails due to someone else's locks, it's
- fairly easy to learn about them. The easiest of
- these is <command>svn status --show-updates</command>:</para>
+ fairly easy to learn about them. The easiest way is to run
+ <userinput>svn status --show-updates</userinput>:</para>
<screen>
$ svn status -u
@@ -2474,7 +2478,7 @@
</screen>
<para>In this example, Sally can see not only that her copy of
- <filename>foo.h</filename> is out of date, but that one of the
+ <filename>foo.h</filename> is out of date, but also that one of the
two modified files she plans to commit is locked in the
repository. The <literal>O</literal> symbol stands for
<quote>Other,</quote> meaning that a lock exists on the file
@@ -2503,8 +2507,8 @@
$
</screen>
- <para>Just as <command>svn info</command> can be used to examine
- objects in the working copy, it can also be used to examine
+ <para>Just as you can use <command>svn info</command> to examine
+ objects in the working copy, you can also use it to examine
objects in the repository. If the main argument to
<command>svn info</command> is a working copy path, then all
of the working copy's cached information is displayed; any
@@ -2512,13 +2516,13 @@
lock token (if a file is locked by another user or in another
working copy, <command>svn info</command> on a working copy
path will show no lock information at all). If the main
- argument to <command>svn info</command> is a URL, then the
+ argument to <command>svn info</command> is a URL, the
information reflects the latest version of an object in the
repository, and any mention of a lock describes the current
lock on the object.</para>
<para>So in this particular example, Sally can see that Harry
- locked the file on February 16th to <quote>make a quick
+ locked the file on February 16 to <quote>make a quick
tweak.</quote> It being June, she suspects that he probably
forgot all about the lock. She might phone Harry to complain
and ask him to release the lock. If he's unavailable, she
@@ -2567,7 +2571,7 @@
$
</screen>
- <para>The more interesting option is allowing users to break
+ <para>The more interesting option is to allow users to break
each other's locks over the network. To do this, Sally simply
needs to pass the <option>--force</option> to the <command>svn
unlock</command> command:</para>
@@ -2602,13 +2606,13 @@
<para>Simply breaking a lock may not be enough. In
the running example, Sally may not only want to break Harry's
- long-forgotten lock, but re-lock the file for her own use.
- She can accomplish this by running <command>svn unlock
- --force</command> and then <command>svn lock</command>
+ long-forgotten lock, but relock the file for her own use.
+ She can accomplish this by using <command>svn unlock</command>
+ with <option>--force</option> and then <command>svn lock</command>
back-to-back, but there's a small chance that somebody else
might lock the file between the two commands. The simpler thing
- to is <firstterm>steal</firstterm> the lock, which involves
- breaking and re-locking the file all in one atomic step. To
+ to do is to <firstterm>steal</firstterm> the lock, which involves
+ breaking and relocking the file all in one atomic step. To
do this, Sally passes the <option>--force</option> option
to <command>svn lock</command>:</para>
@@ -2625,7 +2629,7 @@
the original lock token, but that lock no longer exists. The
lock token is said to be <firstterm>defunct</firstterm>. The
lock represented by the lock token has either been broken (no
- longer in the repository), or stolen (replaced with a
+ longer in the repository) or stolen (replaced with a
different lock). Either way, Harry can see this by asking
<command>svn status</command> to contact the
repository:</para>
@@ -2641,8 +2645,8 @@
$
</screen>
- <para>If the repository lock was broken, then <command>svn
- status --show-updates</command> displays a
+ <para>If the repository lock was broken, then <userinput>svn
+ status --show-updates</userinput> displays a
<literal>B</literal> (Broken) symbol next to the file. If a
new lock exists in place of the old one, then a
<literal>T</literal> (sTolen) symbol is shown. Finally,
@@ -2656,10 +2660,10 @@
lock should be. Some folks argue that locks must be
strictly enforced at all costs, releasable only by the
original creator or administrator. They argue that if
- anyone can break a lock, then chaos runs rampant and the
+ anyone can break a lock, chaos runs rampant and the
whole point of locking is defeated. The other side argues
that locks are first and foremost a communication tool. If
- users are constantly breaking each others' locks, then it
+ users are constantly breaking each other's locks, it
represents a cultural failure within the team and the
problem falls outside the scope of software enforcement.</para>
@@ -2694,13 +2698,13 @@
<para>For example, suppose Harry locks an image file and then
begins editing it. Meanwhile, miles away, Sally wants to do
- the same thing. She doesn't think to run <command>svn status
- --show-updates</command>, so she has no idea that Harry has
+ the same thing. She doesn't think to run <userinput>svn status
+ --show-updates</userinput>, so she has no idea that Harry has
already locked the file. She spends hours editing the file,
and when she tries to commit her change, she discovers that
either the file is locked or that she's out of date.
Regardless, her changes aren't mergeable with Harry's. One of
- these two people has to throw away their work, and a lot of
+ these two people has to throw away his or her work, and a lot of
time has been wasted.</para>
<para>Subversion's solution to this problem is to provide a
@@ -2708,22 +2712,22 @@
<emphasis>before</emphasis> the editing begins. The mechanism
is a special property: <literal>svn:needs-lock</literal>. If
that property is attached to a file (regardless of its value,
- which is irrelevant), then Subversion will try to use
+ which is irrelevant), Subversion will try to use
filesystem-level permissions to make the file read-only—unless,
of course, the user has explicitly locked the file.
- When a lock token is present (as a result of running
- <command>svn lock</command>), the file becomes read-write.
+ When a lock token is present (as a result of using
+ <command>svn lock</command>), the file becomes read/write.
When the lock is released, the file becomes read-only
again.</para>
<para>The theory, then, is that if the image file has this
- property attached, then Sally would immediately notice
+ property attached, Sally would immediately notice
something is strange when she opens the file for editing:
many applications alert users immediately when a read-only
file is opened for editing, and nearly all would
prevent her from saving changes to the file. This
reminds her to lock the file before editing, whereby she
- discovers the pre-existing lock:</para>
+ discovers the preexisting lock:</para>
<screen>
$ /usr/local/bin/gimp raisin.jpg
@@ -2826,7 +2830,7 @@
When you commit a change to the <literal>svn:externals</literal>
property, Subversion will synchronize the checked-out items
against the changed externals definition when you next run
- <command>svn update</command>. The same thing will happen when
+ <userinput>svn update</userinput>. The same thing will happen when
others update their working copies and receive your changes to
the externals definition.</para>
@@ -2880,7 +2884,7 @@
<para>As of Subversion 1.5, though, a new format of the
<literal>svn:externals</literal> property is supported.
Externals definitions are still multiline, but the order and
- format of the various pieces of information has changed. The
+ format of the various pieces of information have changed. The
new syntax more closely mimics the order of arguments you might
pass to <command>svn checkout</command>: the optional revision
flags come first, then the external Subversion repository URL,
@@ -2928,12 +2932,12 @@
</tip>
<para>For most repositories, these three ways of formatting the
- external definitions have the same ultimate effect. They all
+ externals definitions have the same ultimate effect. They all
bring the same benefits. Unfortunately, they all bring the same
annoyances, too. Since the definitions shown use absolute URLs,
moving or copying a directory to which they are attached will
not affect what gets checked out as an external (though the
- relative local target subdirectory will, of course, move with
+ relative local target subdirectory will, of course, move with the
renamed directory). This can be confusing—even
frustrating—in certain situations. For example, say you
have a top-level directory named
@@ -2969,7 +2973,7 @@
$ svn move -q my-project renamed-project
$ svn commit -m "Rename my-project to renamed-project."
Deleting my-project
-Adding my-renamed-project
+Adding renamed-project
Committed revision 12.
$ svn update
@@ -2990,12 +2994,12 @@
won't be able to commit anything from the working copies created
by those externals. On the other hand, if they use the
<literal>https://</literal> form of the URLs, anyone who might
- be checking out via <literal>http://</literal> because their
+ be checking out via <literal>http://</literal> because his
client doesn't support <literal>https://</literal> will be
unable to fetch the external items. Be aware, too, that if you
- need to re-parent your working copy (using <command>svn switch
- --relocate</command>), externals definitions will
- <emphasis>not</emphasis> also be re-parented.</para>
+ need to reparent your working copy (using <command>svn switch</command>
+ with the <option>--relocate</option> option), externals definitions will
+ <emphasis>not</emphasis> also be reparented.</para>
<para>Subversion 1.5 takes a huge step in relieving these
frustrations. As mentioned earlier, the URLs used in the new
@@ -3008,25 +3012,25 @@
<term>../</term>
<listitem><para>Relative to the URL of the directory on which
the <literal>svn:externals</literal> property is
- set.</para></listitem>
+ set</para></listitem>
</varlistentry>
<varlistentry>
<term>^/</term>
<listitem><para>Relative to the root of the repository in
which the <literal>svn:externals</literal> property is
- versioned.</para></listitem>
+ versioned</para></listitem>
</varlistentry>
<varlistentry>
<term>//</term>
<listitem><para>Relative to the scheme of the URL of the
directory on which the <literal>svn:externals</literal>
- property is set.</para></listitem>
+ property is set</para></listitem>
</varlistentry>
<varlistentry>
<term>/</term>
<listitem><para>Relative to the root URL of the server on
which the <literal>svn:externals</literal> property is
- versioned.</para></listitem>
+ versioned</para></listitem>
</varlistentry>
</variablelist>
@@ -3043,15 +3047,15 @@
<para>The support that exists for externals definitions in
Subversion remains less than ideal, though. An externals
- definition can only point to directories, not files. Also, the
+ definition can point only to directories, not to files. Also, the
local subdirectory part of the definition cannot contain
<literal>..</literal> parent directory indicators (such as
<filename>../../skins/myskin</filename>). Perhap most
- disappointinly, the working copies created via the externals
+ disappointingly, the working copies created via the externals
definition support are still disconnected from the primary
working copy (on whose versioned directories the
<literal>svn:externals</literal> property was actually set).
- And Subversion still only truly operates on nondisjoint working
+ And Subversion still truly operates only on nondisjoint working
copies. So, for example, if you want to commit changes that
you've made in one or more of those external working copies, you
must run <command>svn commit</command> explicitly on those
@@ -3061,7 +3065,7 @@
<para>We've already mentioned some of the additional shortcomings
of the old <literal>svn:externals</literal> format and how the
new Subversion 1.5 format improves upon it. But be careful when
- making use of the new format that you don't inadvertantly cause
+ making use of the new format that you don't inadvertently cause
problems for other folks accessing your repository who are using
older Subversion clients. While Subversion 1.5 clients will
continue to recognize and support the original externals
@@ -3128,7 +3132,7 @@
really want.</para>
<para>And thanks to moves, versioned object history can get far
- more twisted than that, even. For example, you might have a
+ more twisted than even that. For example, you might have a
directory named <filename>concept</filename>, containing some
nascent software project you've been toying with. Eventually,
though, that project matures to the point that the idea seems to
@@ -3161,13 +3165,13 @@
some reason.</para>
<para>In scenarios like these, attempting to instruct
- Subversion to work with these re-used paths can be a little like
+ Subversion to work with these reused paths can be a little like
instructing a motorist in Chicago's West Suburbs to drive east
down Roosevelt Road and turn left onto Main Street. In a mere
20 minutes, you can cross <quote>Main Street</quote> in
Wheaton, Glen Ellyn, and Lombard. And no, they aren't the same
street. Our motorist—and our Subversion—need a
- little more detail in order to do the right thing.</para>
+ little more detail to do the right thing.</para>
<para>In version 1.1, Subversion introduced a way for you to tell
it exactly which Main Street you meant. It's called the
@@ -3200,8 +3204,8 @@
</footnote>
we can think of <quote>Main Street</quote> as our path and
<quote>Wheaton</quote> as our peg revision. These two pieces of
- information identify a unique path that can be travelled (north or
- south on Main Street), and they keep us from travelling up and
+ information identify a unique path that can be traveled (north or
+ south on Main Street), and they keep us from traveling up and
down the wrong Main Street in search of our destination. Now we
throw in <quote>606 N.</quote> as our operative revision of
sorts, and we know <emphasis>exactly</emphasis> where to
@@ -3210,7 +3214,7 @@
<sidebar>
<title>The Peg Revision Algorithm</title>
- <para>The Subversion command-line performs the peg revision
+ <para>The Subversion command-line client performs the peg revision
algorithm any time it needs to resolve possible ambiguities in
the paths and revisions provided to it. Here's an example of
such an invocation:</para>
@@ -3220,7 +3224,7 @@
</screen>
<para>If <replaceable>OPERATIVE-REV</replaceable> is older than
- <replaceable>PEG-REV</replaceable>, then the algorithm is as
+ <replaceable>PEG-REV</replaceable>, the algorithm is as
follows:</para>
<orderedlist>
@@ -3237,7 +3241,7 @@
<listitem>
<para>Perform the requested action on that ancestor,
wherever it is located, or whatever its name might
- be or have been at that time.</para>
+ be or might have been at that time.</para>
</listitem>
</orderedlist>
@@ -3260,7 +3264,7 @@
can be only one such object.</para>
</listitem>
<listitem>
- <para>Trace the object's history backwards (through any
+ <para>Trace the object's history backward (through any
possible renames) to its ancestor in the revision
<replaceable>PEG-REV</replaceable>.</para>
</listitem>
@@ -3268,7 +3272,7 @@
<para>Verify that the object's location (path-wise) in
<replaceable>PEG-REV</replaceable> is the same as it is in
<replaceable>OPERATIVE-REV</replaceable>. If that's the
- case, then at least the two locations are known to be
+ case, at least the two locations are known to be
directly related, so perform the requested action on the
location in <replaceable>OPERATIVE-REV</replaceable>.
Otherwise, relatedness was not established, so error out
@@ -3290,24 +3294,24 @@
</sidebar>
<para>Say that long ago we created our repository, and in revision 1
- added our first <filename>concept</filename> directory, plus an
+ we added our first <filename>concept</filename> directory, plus an
<filename>IDEA</filename> file in that directory talking about
the concept. After several revisions in which real code was
added and tweaked, we, in revision 20, renamed this directory to
<filename>frabnaggilywort</filename>. By revision 27, we had a
new concept, a new <filename>concept</filename> directory to
hold it, and a new <filename>IDEA</filename> file to describe
- it. And then 5 years and 20 thousand revisions flew by,
+ it. And then five years and thousands of revisions flew by,
just like they would in any good romance story.</para>
<para>Now, years later, we wonder what the
<filename>IDEA</filename> file looked like back in revision 1.
- But Subversion needs to know if we are asking about how the
+ But Subversion needs to know whether we are asking about how the
<emphasis>current</emphasis> file looked back in revision 1, or
- if we are asking for the contents of whatever file lived at
+ whether we are asking for the contents of whatever file lived at
<filename>concepts/IDEA</filename> in revision 1. Certainly
those questions have different answers, and because of peg
- revisions, you can ask question. To find out how the
+ revisions, you can ask those questions. To find out how the
current <filename>IDEA</filename> file looked in that old
revision, you run:</para>
@@ -3329,7 +3333,7 @@
<para>And when executed, it has the expected results.</para>
- <para>The perceptive reader is probably wondering at this point if
+ <para>The perceptive reader is probably wondering at this point whether
the peg revision syntax causes problems for working copy paths
or URLs that actually have at signs in them. After
all, how does <command>svn</command> know whether
@@ -3441,15 +3445,15 @@
overlap, modifying different files in the same module, or even
modifying different lines in the same file.</para>
- <para>There are various work methodologies that developers can
- employ to keep these logical changes organized. Some use
+ <para>developers can employ various work methodologies
+ to keep these logical changes organized. Some use
separate working copies of the same repository to hold each
individual change in progress. Others might choose to create
short-lived feature branches in the repository and use a single
working copy that is constantly switched to point to one such
branch or another. Still others use <command>diff</command> and
<command>patch</command> tools to back up and restore uncommitted
- changes to and from patchfiles associated with each change.
+ changes to and from patch files associated with each change.
Each of these methods has its pros and cons, and to a large
degree, the details of the changes being made heavily influence
the methodology used to distinguish them.</para>
@@ -3540,11 +3544,11 @@
<para>Harry now sets off to fix the secondary UI problem. Since
he knows which file he'll be changing, he assigns that path to
- a changelist, too. Unfortunately, Harry careless assigns this
+ a changelist, too. Unfortunately, Harry carelessly assigns this
third file to the same changelist as the previous two files:</para>
<screen>
-$ svn changelist math-fix button.c
+$ svn changelist math-fixes button.c
Path 'button.c' is now a member of changelist 'math-fixes'.
$ svn status
@@ -3617,7 +3621,7 @@
<!-- =============================================================== -->
<sect2 id="svn.advanced.changelists.asfilters">
- <title>Changelists as Operation Filters</title>
+ <title>Changelists As Operation Filters</title>
<para>The visual grouping that Harry sees in the output of
<command>svn status</command> as shown in our previous section
@@ -3711,7 +3715,7 @@
<para>The <option>--changelist</option> option acts only as a
filter for Subversion command targets, and will not add
targets to an operation. For example, on a commit operation
- specified as <command>svn commit /path/to/dir</command>, the
+ specified as <userinput>svn commit /path/to/dir</userinput>, the
target is the directory <filename>/path/to/dir</filename>
and its children (to infinite depth). If you then add a
changelist specifier to that command, only those files in
@@ -3756,7 +3760,7 @@
Changelists are artifacts of a particular working copy, which
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
+ can be assigned only to files—Subversion doesn't
currently support the use of changelists with directories.
Finally, you can have at most one changelist assignment on a
given working copy file. Here is where the blog post category
@@ -3796,10 +3800,10 @@
server responds with an appropriate answer. The details of
the network protocol are hidden from the user—the client
attempts to access a URL, and depending on the URL scheme, a
- particular protocol is used to contact the server (see <xref
+ particular protocol is used to contact the server (see the sidebar <xref
linkend="svn.basic.in-action.wc.sb-1"/>).</para>
- <tip><para>Run <command>svn --version</command> to see
+ <tip><para>Run <userinput>svn --version</userinput> to see
which URL schemes and protocols the client knows how to
use.</para>
</tip>
@@ -3811,26 +3815,26 @@
to the server. Once authentication is complete, the server
responds with the original information that the client asked for.
Notice that this system is different from systems such as CVS,
- where the client pre-emptively offers credentials (<quote>logs
+ where the client preemptively offers credentials (<quote>logs
in</quote>) to the server before ever making a request. In
Subversion, the server <quote>pulls</quote> credentials by
challenging the client at the appropriate moment, rather than
the client <quote>pushing</quote> them. This makes certain
operations more elegant. For example, if a server is
configured to allow anyone in the world to read a repository,
- then the server will never issue an authentication challenge
+ the server will never issue an authentication challenge
when a client attempts to <command>svn checkout</command>.</para>
<para>If the particular network requests issued by the client
- result in a new revision being created in the repository,
- (e.g., <command>svn commit</command>), then Subversion uses the
+ result in a new revision being created in the repository
+ (e.g., <command>svn commit</command>), Subversion uses the
authenticated username associated with those requests as the
author of the revision. That is, the authenticated user's
name is stored as the value of the
<literal>svn:author</literal> property on the new revision
(see <xref linkend="svn.ref.properties"/>). If
- the client was not authenticated (in other words, if the server
- never issued an authentication challenge), then the revision's
+ the client was not authenticated (i.e., if the server
+ never issued an authentication challenge), the revision's
<literal>svn:author</literal> property is empty.
</para>
@@ -3860,7 +3864,7 @@
first looks for the appropriate credentials in the user's disk
cache. If seemingly suitable credentials are not present, or
if the cached credentials ultimately fail to authenticate,
- then the client will, by default, fall back to prompting the
+ the client will, by default, fall back to prompting the
user for the necessary information.</para>
<para>The security-conscious reader will suspect immediately
@@ -3886,7 +3890,7 @@
password. (Note that if the user's Windows account password
is reset by an administrator, all of the cached passwords
become undecipherable. The Subversion client will behave
- as if they don't exist, prompting for passwords when
+ as though they don't exist, prompting for passwords when
required.)</para>
</listitem>
@@ -3895,7 +3899,7 @@
all repository passwords in the login keyring (managed by
the Keychain service), which is protected by the user's
account password. User preference settings can impose
- additional policies, such as requiring the user's account
+ additional policies, such as requiring that the user's account
password be entered each time the Subversion password is
used.</para>
</listitem>
@@ -3913,7 +3917,7 @@
<para>Of course, for the truly paranoid, none of these
mechanisms meets the test of perfection. So for those folks
- willing to sacrifice convenience for the ultimate security,
+ willing to sacrifice convenience for the ultimate in security,
Subversion provides various ways of disabling its credentials
caching system altogether.</para>
@@ -3994,13 +3998,13 @@
authentication behavior, specifically regarding the
<option>--username</option> and <option>--password</option>
options. Many client subcommands accept these options, but it
- is important to understand using these options does
+ is important to understand that using these options does
<emphasis>not</emphasis> automatically send credentials to the
server. As discussed earlier, the server <quote>pulls</quote>
credentials from the client when it deems necessary; the
client cannot <quote>push</quote> them at will. If a username
- and/or password are passed as options, they will only be
- presented to the server if the server requests them. These
+ and/or password are passed as options, they will be
+ presented to the server only if the server requests them. These
options are typically used to authenticate as a different user
than Subversion would have chosen by default (such as your
system login name) or when trying to avoid interactive
@@ -4012,7 +4016,7 @@
that it never issues an authentication challenge. When
users pass <option>--username</option> and
<option>--password</option> options to the client, they're
- surprised to see that they're never used; i.e., new
+ surprised to see that they're never used; that is, new
revisions still appear to have been committed
anonymously!</para>
</note>
@@ -4034,7 +4038,7 @@
<para>If no command-line credentials were provided, or the
provided ones were invalid, the client looks up the server's
hostname, port, and realm in the runtime configuration's
- <filename>auth/</filename> area, to see if appropriate
+ <filename>auth/</filename> area, to see whether appropriate
credentials are cached there. If so, it attempts to use
those credentials to authenticate.</para>
</listitem>
@@ -4057,6 +4061,30 @@
</sect1>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.summary">
+ <title>Summary</title>
+
+ <para>After reading this chapter, you should have a firm grasp on
+ some of Subversion's features that, while perhaps not used
+ <emphasis>every</emphasis> time you interact with your version
+ control system, are certainly handy to know about. But don't
+ stop here! Read on to the following chapter, where you'll learn
+ about branches, tags, and merging. Then you'll have nearly full
+ mastery of the Subversion client. Though our lawyers won't
+ allow us to promise you anything, this additional knowledge
+ could make you measurably more cool.
+ <footnote>
+ <para>No purchase necessary. Certains terms and conditions
+ apply. No guarantee of coolness—implicit or
+ otherwise—exists. Mileage may vary.</para>
+ </footnote>
+ </para>
+
+ </sect1>
+
</chapter>
<!--
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 Tue Aug 12 11:40:38 2008
@@ -11,11 +11,11 @@
<para>Branching, tagging, and merging are concepts common to
almost all version control systems. If you're not familiar with
these ideas, we provide a good introduction in this chapter. If
- you are familiar, then hopefully you'll find it interesting to
+ you are familiar, hopefully you'll find it interesting to
see how Subversion implements them.</para>
<para>Branching is a fundamental part of version control. If
- you're going to allow Subversion to manage your data, then this
+ you're going to allow Subversion to manage your data, this
is a feature you'll eventually come to depend on. This chapter
assumes that you're already familiar with Subversion's basic
concepts (<xref linkend="svn.basic"/>).</para>
@@ -62,7 +62,7 @@
branches by copying your data, and remembers that the copies are
related to one another. It also helps you duplicate changes
from one branch to another. Finally, it can make portions of
- your working copy reflect different branches, so that you can
+ your working copy reflect different branches so that you can
<quote>mix and match</quote> different lines of development in
your daily work.</para>
@@ -75,7 +75,7 @@
<title>Using Branches</title>
<para>At this point, you should understand how each commit creates
- an entire new filesystem tree (called a <quote>revision</quote>)
+ an entirely new filesystem tree (called a <quote>revision</quote>)
in the repository. If you don't, go back and read about revisions in
<xref linkend="svn.basic.in-action.revs"/>.</para>
@@ -110,7 +110,7 @@
process of fixing small bugs here and there. She's depending on
the fact that the latest version of the project (in
<filename>/calc/trunk</filename>) is always usable. If you
- start committing your changes bit-by-bit, you'll surely break
+ start committing your changes bit by bit, you'll surely break
things for Sally (and other team members as well).</para>
<para>One strategy is to crawl into a hole: you and Sally can stop
@@ -125,14 +125,14 @@
copy of <filename>/calc/trunk</filename> on two different
machines), you'll need to manually copy your changes back and
forth or just do all the work on a single computer. By that
- same token, it's difficult to share your changes-in-progress
+ same token, it's difficult to share your changes in progress
with anyone else. A common software development <quote>best
practice</quote> is to allow your peers to review your work as
you go. If nobody sees your intermediate commits, you lose
potential feedback and may end up going down the wrong path for
weeks before another person on your team notices. Finally, when
you're finished with all your changes, you might find it very
- difficult to re-merge your final work with the rest of the
+ difficult to remerge your final work with the rest of the
company's main body of code. Sally (or others) may have made
many other changes in the repository that are difficult to
incorporate into your working copy—especially if you
@@ -152,7 +152,7 @@
<para>Creating a branch is very simple—you make a copy of
the project in the repository using the <command>svn
- copy</command> command. Subversion is not only able to copy
+ copy</command> command. Subversion is able to copy not only
single files, but whole directories as well. In this case,
you want to make a copy of the
<filename>/calc/trunk</filename> directory. Where should the
@@ -196,7 +196,7 @@
within the working copy, this technique isn't recommended. It
can be quite slow, in fact! Copying a directory on the
client side is a linear-time operation, in that it actually
- has to duplicate every file and subdirectory on local disk.
+ has to duplicate every file and subdirectory on the local disk.
Copying a directory on the server, however, is a constant-time
operation, and it's the way most people create
branches.</para>
@@ -215,9 +215,9 @@
duplicate any data. Instead, it creates a new directory
entry that points to an <emphasis>existing</emphasis> tree.
If you're an experienced Unix user, you'll recognize this as
- the same concept behind a hard-link. As further changes are
+ the same concept behind a hard link. As further changes are
made to files and directories beneath the copied directory,
- Subversion continues to employ this hard-link concept where
+ Subversion continues to employ this hard link concept where
it can. It duplicates data only when it is necessary to
disambiguate different versions of objects.</para>
@@ -235,9 +235,9 @@
<para>Of course, these internal mechanics of copying and
sharing data are hidden from the user, who simply sees
copies of trees. The main point here is that copies are
- cheap, both in time and space. If you create a branch
- entirely within the repository (by running <command>svn copy
- URL1 URL2</command>), it's a quick, constant-time operation.
+ cheap, both in time and in space. If you create a branch
+ entirely within the repository (by running <userinput>svn copy
+ <replaceable>URL1</replaceable> <replaceable>URL2</replaceable></userinput>), it's a quick, constant-time operation.
Make branches as often as you want.</para>
</sidebar>
@@ -264,7 +264,7 @@
updates, because her working copy is of
<filename>/calc/trunk</filename>. (Be sure to read <xref
linkend="svn.branchmerge.switchwc"/> later in this chapter: the
- <command>svn switch</command> command is an alternate way of
+ <command>svn switch</command> command is an alternative way of
creating a working copy of a branch.)</para>
<para>Let's pretend that a week goes by, and the following
@@ -290,8 +290,8 @@
</listitem>
</itemizedlist>
- <para>There are now two independent lines of development (shown
- in <xref linkend="svn.branchmerge.using.work.dia-1"/>) happening on
+ <para>Now two independent lines of development (shown
+ in <xref linkend="svn.branchmerge.using.work.dia-1"/>) are happening on
<filename>integer.c</filename>.</para>
<figure id="svn.branchmerge.using.work.dia-1">
@@ -345,7 +345,7 @@
It shows the creation of the branch as an event in the
history, because <filename>integer.c</filename> was implicitly
copied when all of <filename>/calc/trunk/</filename> was
- copied. Now look what happens when Sally runs the same
+ copied. Now look at what happens when Sally runs the same
command on her copy of the file:</para>
<screen>
@@ -393,10 +393,10 @@
<sect2 id="svn.branchmerge.using.concepts">
<title>The Key Concepts Behind Branching</title>
- <para>There are two important lessons that you should remember
+ <para>You should remember two important lessons
from this section. First, Subversion has no internal concept
of a branch—it knows only how to make copies. When you
- copy a directory, the resulting directory is only
+ copy a directory, the resultant directory is only
a <quote>branch</quote> because <emphasis>you</emphasis>
attach that meaning to it. You may think of the directory
differently, or treat it differently, but to Subversion it's
@@ -459,22 +459,22 @@
<para>In the examples that follow, we're assuming that both your
Subversion client and server are running Subversion 1.5 (or
later). If either client or server is older than version 1.5,
- then things are more complicated: the system won't track changes
+ things are more complicated: the system won't track changes
automatically, and you'll have to use painful manual methods to
achieve similar results. That is, you'll always need to use the
detailed merge syntax to specify specific ranges of revisions to
- replicate (See
+ replicate (see
<xref linkend="svn.branchmerge.advanced.advancedsyntax"/> later
in this chapter), and take special care to keep track of what's
already been merged and what hasn't. For this reason,
- we <emphasis>strongly</emphasis> recommend making sure that your
- client and server are at least version 1.5 or later.</para>
+ we <emphasis>strongly</emphasis> recommend that you make sure your
+ client and server are at least at version 1.5.</para>
<!-- =============================================================== -->
<sect2 id="svn.branchmerge.changesets">
<title>Changesets</title>
- <para>Before we get too far in, we should warn you that there's
+ <para>Before we proceed further, we should warn you that there's
going to be a lot of discussion of <quote>changes</quote> in
the pages ahead. A lot of people experienced with version
control systems use the terms <quote>change</quote>
@@ -483,9 +483,9 @@
a <firstterm>changeset</firstterm>.</para>
<para>Everyone seems to have a slightly different definition
- of <quote>changeset,</quote> or at least a different
+ of changeset, or at least a different
expectation of what it means for a version control system to
- have one. For our purpose, let's say that a changeset is just
+ have one. For our purposes, let's say that a changeset is just
a collection of changes with a unique name. The changes might
include textual edits to file contents, modifications to tree
structure, or tweaks to metadata. In more common speak, a
@@ -494,21 +494,21 @@
<para>In Subversion, a global revision number N names a tree in
the repository: it's the way the repository looked after the
Nth commit. It's also the name of an implicit changeset: if
- you compare tree N with tree N-1, you can derive the exact
+ you compare tree N with tree N−1, you can derive the exact
patch that was committed. For this reason, it's easy to think
of revision N as not just a tree, but a changeset as well. If
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 r9238.</quote> Somebody
- can then run <command>svn log -r 9238</command> to read about
+ can then run <userinput>svn log -r 9238</userinput> to read about
the exact changeset that fixed the bug, and run
- <command>svn diff -c 9238</command> to see the patch itself.
+ <userinput>svn diff -c 9238</userinput> to see the patch itself.
And (as you'll see shortly)
- Subversion's <command>merge</command> command is able to use
+ Subversion's <command>svn merge</command> command is able to use
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
+ arguments: passing <userinput>-c 9238</userinput> to <command>svn merge</command> would merge
changeset r9238 into your working copy.</para>
</sect2>
@@ -548,10 +548,10 @@
U integer.c
</screen>
- <para>This basic syntax—<command>svn merge
- URL</command>—tells Subversion to merge all recent
+ <para>This basic syntax—<userinput>svn merge
+ <replaceable>URL</replaceable></userinput>—tells Subversion to merge all recent
changes from the URL to the current working directory (which
- is typically the root of your working copy.) After running
+ is typically the root of your working copy). After running
the prior example, your branch working copy now contains new
local modifications, and these edits are duplications of all
of the changes that have happened on the trunk since you first
@@ -583,10 +583,10 @@
no <emphasis>syntactic</emphasis> conflicts doesn't mean there
aren't any <emphasis>semantic</emphasis> conflicts!) If you
encounter serious problems, you can always abort the local
- changes by running <command>svn revert . -R</command> (which
+ changes by running <userinput>svn revert . -R</userinput> (which
will undo all local modifications) and start a
long <quote>what's going on?</quote> discussion with your
- collaborators. If things look good, however, then you can
+ collaborators. If things look good, however, you can
submit these changes into the repository:</para>
<screen>
@@ -644,7 +644,7 @@
express changes in tree structure and properties by directly
applying them to your working copy. Even more important,
this command records the changes that have been duplicated
- to your branch, so that Subversion is aware of exactly which
+ to your branch so that Subversion is aware of exactly which
changes exist in each location (see
<xref linkend="svn.branchmerge.basicmerging.mergeinfo"/>.)
This is a critical feature that makes branch management
@@ -703,26 +703,26 @@
up-to-date working copy of <filename>/trunk</filename>. You
can do this by either doing an <command>svn
checkout</command>, dredging up an old trunk working copy from
- somewhere on your disk, or by using <command>svn
+ somewhere on your disk, or using <command>svn
switch</command> (see
<xref linkend="svn.branchmerge.switchwc"/>.) However you get a
trunk working copy, remember that it's a best practice to do
your merge into a working copy that
has <emphasis>no</emphasis> local edits and has been recently
- updated (i.e., is not a mixture of local revisions.) If your
+ updated (i.e., is not a mixture of local revisions). If your
working copy isn't <quote>clean</quote> in these ways, you can
run into some unnecessary conflict-related headaches
and <command>svn merge</command> will likely return an
error.</para>
<para>Once you have a clean working copy of the trunk, you're
- ready merge your branch back into it:</para>
+ ready to merge your branch back into it:</para>
<screen>
$ pwd
/home/user/calc-trunk
-$ svn update # (just to make sure the working copy is at latest everywhere)
+$ svn update # (make sure the working copy is up to date)
At revision 390.
$ svn merge --reintegrate http://svn.example.com/repos/calc/branches/my-calc-branch
@@ -743,7 +743,7 @@
Committed revision 391.
</screen>
- <para>Congratulations, your branch has now been re-merged back
+ <para>Congratulations, your branch has now been remerged back
into the main line of development. Notice our use of
the <option>--reintegrate</option> option this time around.
The option is critical for reintegrating changes from a branch
@@ -763,23 +763,18 @@
<para>When merging your branch back to the trunk, however, the
underlying mathematics is quite different. Your feature
- branch is now a mish-mosh of both duplicated trunk changes and
+ branch is now a mishmosh of both duplicated trunk changes and
private branch changes, so there's no simple contiguous range
of revisions to copy over. By specifying
the <option>--reintegrate</option> option, you're asking
Subversion to carefully replicate <emphasis>only</emphasis>
- those changes unique to your branch. (And in fact it does
+ those changes unique to your branch. (And in fact, it does
this by comparing the latest trunk tree with the latest branch
tree: the resulting difference is exactly your branch
changes!)</para>
- <para>Now that your branch is merged to trunk, you have a couple
- of options. You can keep working on your branch, repeating
- the whole process of occasionally syncing with the trunk and
- eventually using <option>--reintegrate</option> to merge it
- back again. Or, if you're really done with the branch, you
- can destroy your working copy of it and then remove it from
- the repository:</para>
+ <para>Now that your private branch is merged to trunk, you may
+ wish to remove it from the repository:</para>
<screen>
$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \
@@ -799,6 +794,35 @@
at some point, should you desire (see
<xref linkend="svn.branchmerge.basicmerging.resurrect"/>).</para>
+ <para>In Subversion 1.5, once
+ a <option>--reintegrate</option> merge is done from branch to trunk,
+ the branch is no longer usable for further work. It's not
+ able to correctly absorb new trunk changes, nor can it be
+ properly reintegrated to trunk again. For this reason, if you
+ want to keep working on your feature branch, we recommend
+ destroying it and then re-creating it from the trunk:</para>
+
+ <screen>
+$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \
+ -m "Remove my-calc-branch."
+Committed revision 392.
+
+$ svn copy http://svn.example.com/repos/calc/trunk \
+ http://svn.example.com/repos/calc/branches/new-branch
+ -m "Create a new branch from trunk."
+Committed revision 393.
+
+$ cd my-calc-branch
+
+$ svn switch http://svn.example.com/repos/calc/branches/new-branch
+Updated to revision 393.
+</screen>
+
+ <para>The final command in the prior example—<command>svn
+ switch</command>—is a way of updating an existing working
+ copy to reflect a different repository directory. We'll discuss
+ this more in <xref linkend="svn.branchmerge.switchwc"/>.</para>
+
</sect2>
<!-- =============================================================== -->
@@ -811,7 +835,7 @@
Specifically, merge data is tracked in
the <literal>svn:mergeinfo</literal> property attached to
files and directories. (If you're not familiar with
- Subversion properties, now is the time to go skim over
+ Subversion properties, now is the time to skim
<xref linkend="svn.advanced.props"/>.)</para>
<para>You can examine the property, just like any
@@ -833,7 +857,7 @@
has received the specific changes
is <filename>/branches/my-calc-branch</filename>.</para>
- <para>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
@@ -866,7 +890,7 @@
a <quote>source</quote> URL (where the changes would be coming
from), and takes an optional <quote>target</quote> URL (where
the changes would be merged to). If no target URL is given,
- then it assumes that the current working directory is the
+ it assumes that the current working directory is the
target. In the prior example, because we're querying our
branch working copy, the command assumes we're interested in
receiving changes to <filename>/branches/mybranch</filename>
@@ -874,7 +898,7 @@
<para>Another way to get a more precise preview of a merge
operation is to use the <option>--dry-run</option>
- option.</para>
+ option:</para>
<screen>
$ svn merge http://svn.example.com/repos/calc/trunk --dry-run
@@ -887,15 +911,15 @@
<para>The <option>--dry-run</option> option doesn't actually
apply any local changes to the working copy. It shows only
status codes that <emphasis>would</emphasis> be printed in a
- real merge. It's useful for getting a <quote>high
- level</quote> preview of the potential merge, for those times
+ real merge. It's useful for getting a <quote>high-level</quote>
+ preview of the potential merge, for those times
when running <command>svn diff</command> gives too much
detail.</para>
<tip>
<para>After performing a merge operation, but before committing
- the results of the merge, you can use <command>svn diff
- --depth=empty /path/to/merge/target</command> to see only
+ the results of the merge, you can use <userinput>svn diff
+ --depth=empty <replaceable>/path/to/merge/target</replaceable></userinput> to see only
the changes to the immediate target of your merge. If your
merge target was a directory, only property differences will
be displayed. This is a handy way to see the changes to the
@@ -909,8 +933,8 @@
isn't an inherently risky thing (unless you've made local
modifications to your working copy—but we've already
stressed that you shouldn't be merging into such an
- environment.) If you don't like the results of the merge,
- simply <command>svn revert . -R</command> the changes from
+ environment). If you don't like the results of the merge,
+ simply run <userinput>svn revert . -R</userinput> to revert the changes from
your working copy and retry the command with different
options. The merge isn't final until you
actually <command>svn commit</command> the results.</para>
@@ -921,7 +945,7 @@
revert</command> over and over, you may run into some
annoying (but easily bypassed) roadblocks. For example, if
the merge operation adds a new file (i.e., schedules it for
- addition), then <command>svn revert</command> won't actually
+ addition), <command>svn revert</command> won't actually
remove the file; it simply unschedules the addition. You're
left with an unversioned file. If you then attempt to run
the merge again, you may get conflicts due to the
@@ -980,7 +1004,7 @@
changesets, to your working copy. In our case of undoing a
change, we're asking <command>svn merge</command> to apply
changeset #303 to our working copy
- <emphasis>backwards</emphasis>.</para>
+ <emphasis>backward</emphasis>.</para>
<para>Keep in mind that rolling back a change like this is just
like any other <command>svn merge</command> operation, so you
@@ -995,7 +1019,7 @@
the commit, did it? The change still exists in revision 303.
If somebody checks out a version of the
<filename>calc</filename> project between revisions 303 and
- 349, they'll still see the bad change, right?</para>
+ 349, she'll still see the bad change, right?</para>
<para>Yes, that's true. When we talk about
<quote>removing</quote> a change, we're really talking about
@@ -1035,7 +1059,7 @@
do I get my old file or directory back?</quote></para>
<para>The first step is to define
- exactly <emphasis role="bold">which</emphasis> item you're
+ exactly <emphasis>which</emphasis> item you're
trying to resurrect. Here's a useful metaphor: you can think
of every object in the repository as existing in a sort of
two-dimensional coordinate system. The first coordinate is a
@@ -1048,7 +1072,7 @@
<para>First, you might need to use <command>svn log</command> to
discover the exact coordinate pair you wish to resurrect. A
- good strategy is to run <command>svn log --verbose</command>
+ good strategy is to run <userinput>svn log --verbose</userinput>
in a directory that used to contain your deleted item. The
<option>--verbose</option> (<option>-v</option>) option shows
a list of all changed items in each revision; all you need to
@@ -1086,7 +1110,7 @@
choices.</para>
<para>One option is to use <command>svn merge</command> to apply
- revision 808 <quote>in reverse.</quote> (We've already
+ revision 808 <quote>in reverse.</quote> (We already
discussed how to undo changes in
<xref linkend="svn.branchmerge.basicmerging.undo"/>.) This
would have the effect of re-adding <filename>real.c</filename>
@@ -1102,11 +1126,11 @@
want. Certainly, you could reverse-merge revision 808 and
then <command>svn revert</command> the local modifications to
<filename>integer.c</filename>, but this technique doesn't
- scale well. What if there were 90 files changed in revision
+ scale well. What if 90 files were changed in revision
808?</para>
<para>A second, more targeted strategy is not to use
- <command>svn merge</command> at all, but rather the
+ <command>svn merge</command> at all, but rather to use the
<command>svn copy</command> command. Simply copy the exact
revision and path <quote>coordinate pair</quote> from the
repository to your working copy:</para>
@@ -1143,7 +1167,7 @@
$ svn add real.c
A real.c
-$ svn commit -m "Recreated real.c from revision 807."
+$ svn commit -m "Re-created real.c from revision 807."
Adding real.c
Transmitting file data .
Committed revision 1390.
@@ -1179,9 +1203,9 @@
<para>Here ends the automated magic. Sooner or later, once you
get the hang of branching and merging, you're going to have to
ask Subversion to merge <emphasis>specific</emphasis> changes
- from one place to another. In order to do this, you're going to
+ from one place to another. To do this, you're going to
have to start passing more complicated arguments to <command>svn
- merge</command>. This next section describes the fully expanded
+ merge</command>. The next section describes the fully expanded
syntax of the command and discusses a number of common
scenarios that require it.</para>
@@ -1192,7 +1216,7 @@
<para>Just as the term <quote>changeset</quote> is often used in
version control systems, so is the term
- of <firstterm>cherrypicking</firstterm>. This word refers to
+ <firstterm>cherrypicking</firstterm>. This word refers to
the act of choosing <emphasis>one</emphasis> specific
changeset from a branch and replicating it to another.
Cherrypicking may also refer to the act of duplicating a
@@ -1205,14 +1229,14 @@
<para>Why would people want to replicate just a single change?
It comes up more often than you'd think. For example, let's
go back in time and imagine that you haven't yet merged your
- private feature-branch back to the trunk. At the
+ private feature branch back to the trunk. At the
water cooler, you get word that Sally made an interesting
change to <filename>integer.c</filename> on the trunk.
Looking over the history of commits to the trunk, you see that
in revision 355 she fixed a critical bug that directly
impacts the feature you're working on. You might not be ready
to merge all the trunk changes to your branch just yet, but
- you certainly need that particular bugfix in order to continue
+ you certainly need that particular bug fix in order to continue
your work.</para>
<screen>
@@ -1247,7 +1271,7 @@
<para>You can now go through the usual testing procedures before
committing this change to your branch. After the commit,
- Subversion marks r355 as having been merged to the branch, so
+ Subversion marks r355 as having been merged to the branch so
that future <quote>magic</quote> merges that synchronize your
branch with the trunk know to skip over r355. (Merging the
same change to the same branch almost always results in a
@@ -1284,8 +1308,8 @@
U button.c
</screen>
- <para>This use-case of replicating
- (or <firstterm>backporting</firstterm>) bugfixes from one
+ <para>This use case of replicating
+ (or <firstterm>backporting</firstterm>) bug fixes from one
branch to another is perhaps the most popular reason for
cherrypicking changes; it comes up all the time, for example,
when a team is maintaining a <quote>release branch</quote> of
@@ -1296,19 +1320,19 @@
<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
+ two independent patches to your working copy 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
+ trickier. If the first range of changes creates
conflicts, you <emphasis>must</emphasis> resolve them
- interactively in order for the merge process to continue and
+ interactively 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
+ of this writing. This behavior may improve in future
versions of Subversion.</para>
</footnote>
</para>
@@ -1319,7 +1343,7 @@
do have different syntax in many cases. Be sure to read about
them in <xref linkend="svn.ref"/> for details, or ask
<command>svn help</command>. For example, <command>svn
- merge</command> requires a working-copy path as a target, i.e.,
+ merge</command> requires a working copy path as a target, that is,
a place where it should apply the generated patch. If the
target isn't specified, it assumes you are trying to perform
one of the following common operations:</para>
@@ -1365,8 +1389,8 @@
<para>The main source of confusion is the
<emphasis>name</emphasis> of the command. The term
<quote>merge</quote> somehow denotes that branches are
- combined together, or that there's some sort of mysterious
- blending of data going on. That's not the case. A better
+ combined together, or that some sort of mysterious
+ blending of data is going on. That's not the case. A better
name for the command might have been <command>svn
diff-and-apply</command>, because that's all that happens:
two repository trees are compared, and the differences are
@@ -1374,7 +1398,7 @@
<para>If you're using <command>svn merge</command> to do basic
copying of changes between branches, it will generally do the
- right thing automatically. For example, a command like the
+ right thing automatically. For example, a command such as the
following:</para>
<screen>
@@ -1392,7 +1416,7 @@
<para>If you choose to use the <command>svn merge</command>
command in all its full glory by giving it specific revision
- ranges to duplicate, then the command takes three main
+ ranges to duplicate, the command takes three main
arguments:</para>
<orderedlist>
@@ -1412,7 +1436,7 @@
</orderedlist>
<para>Once these three arguments are specified, the two trees
- are compared, and the resulting differences are applied to the
+ are compared, and the differences are applied to the
target working copy as local modifications. When the command
is done, the results are no different than if you had
hand-edited the files or run various <command>svn
@@ -1440,7 +1464,7 @@
naming the working copy target. The second syntax can be used
as a shorthand for situations when you're comparing two
different revisions of the same URL. The last syntax shows
- how the working-copy argument is optional; if omitted, it
+ how the working copy argument is optional; if omitted, it
defaults to the current directory.</para>
<para>While the first example shows the <quote>full</quote>
@@ -1461,61 +1485,71 @@
where <literal>svn:mergeinfo</literal> data is not created or
changed. Remember to be a bit wary of these scenarios:</para>
- <itemizedlist>
- <listitem>
- <para><emphasis>Merging unrelated sources</emphasis>. If you
+ <variablelist>
+ <varlistentry>
+ <term>Merging unrelated sources</term>
+ <listitem>
+ <para>If you
ask <command>svn merge</command> to compare two URLs that
aren't related to each other, a patch will still be
generated and applied to your working copy, but no merging
metadata will be created. There's no common history
between the two sources, and future <quote>smart</quote>
merges depend on that common history.</para>
- </listitem>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para><emphasis>Merging from foreign
- repositories</emphasis>. While it's possible to run a
- command such as <command>svn merge -r 100:200
- http://svn.foreignproject.com/repos/trunk</command>, the
- resulting patch will also lack any historical merge
- metadata. At time of writing, Subversion has no way of
+ <varlistentry>
+ <term>Merging from foreign repositories</term>
+ <listitem>
+ <para>While it's possible to run a
+ command such as <userinput>svn merge -r 100:200
+ <replaceable>http://svn.foreignproject.com/repos/trunk</replaceable></userinput>, the
+ resultant patch will also lack any historical merge
+ metadata. At time of this writing, Subversion has no way of
representing different repository URLs within
the <literal>svn:mergeinfo</literal> property.</para>
</listitem>
+ </varlistentry>
- <listitem>
- <para><emphasis>Using <option>--ignore-ancestry</option></emphasis>.
- If this option is passed to <command>svn merge</command>, it
- causes the merging logic to mindlessly generate differences
- the same way that <command>svn diff</command> does, ignoring
- any historical relationships. We discuss this later in the
- chapter in
- <xref linkend="svn.branchmerge.advanced.ancestry"/>.</para>
- </listitem>
+ <varlistentry>
+ <term>Using <option>--ignore-ancestry</option></term>
+ <listitem>
+ <para>If this option is passed to <command>svn
+ merge</command>, it causes the merging logic to mindlessly
+ generate differences the same way that <command>svn
+ diff</command> does, ignoring any historical
+ relationships. We discuss this later in the chapter in
+ <xref linkend="svn.branchmerge.advanced.ancestry"/>.</para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para><emphasis>Applying reverse merges to a target's
- natural history</emphasis>. In a prior section
- (<xref linkend="svn.branchmerge.basicmerging.undo"/>) we
- discussed how to use <command>svn merge</command> to apply
- a <quote>reverse patch</quote> as a way of rolling back
- changes. If this technique is used to undo a change to a
- object's personal history (e.g., commit r5 to the trunk,
- then immediately roll back r5 using <command>svn merge -c
- -5</command>), this sort of merge doesn't affect the
- recorded mergeinfo.
- <footnote><para>Interestingly, after rolling back a
- revision like this, we wouldn't be able to re-apply
- the revision using <command>svn merge -c 5</command>,
+ <varlistentry>
+ <term>Apply reverse merges to a target's natural history</term>
+ <listitem>
+ <para>Earlier in this chapter
+ (<xref linkend="svn.branchmerge.basicmerging.undo"/>)
+ we discussed how to use <command>svn merge</command>
+ to apply a <quote>reverse patch</quote> as a way of
+ rolling back changes. If this technique is used to
+ undo a change to an object's personal history (e.g.,
+ commit r5 to the trunk, then immediately roll back r5
+ using <userinput>svn merge . -c -5</userinput>), this
+ sort of merge doesn't affect the recorded mergeinfo.
+ <footnote>
+ <para>Interestingly, after rolling back a
+ revision like this, we wouldn't be able to reapply
+ the revision using <userinput>svn merge . -c 5</userinput>,
since the mergeinfo would already list r5 as being
applied. We would have to use
the <option>--ignore-ancestry</option> option to make
the merge command ignore the existing
mergeinfo!</para>
</footnote>
- </para>
- </listitem>
- </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect2>
@@ -1536,10 +1570,10 @@
always apply <quote>cleanly</quote> to your working copy.
The server produces the delta by comparing two trees: a
virtual snapshot of your working copy, and the revision tree
- you're interested in. Because the left-hand side of the
+ you're interested in. Because the left hand side of the
comparison is exactly equal to what you already have, the
delta is guaranteed to correctly convert your working copy
- into the right-hand tree.</para>
+ into the right hand tree.</para>
<para>But <command>svn merge</command> has no such guarantees
and can be much more chaotic: the advanced user can ask the
@@ -1568,21 +1602,21 @@
(h) help for more options:
</screen>
- <para>In the previous example it might be the case that
+ <para>In the previous example, it might be the case that
<filename>baz.c</filename> exists in both snapshots of the
- branch being compared, and the resulting delta wants to
+ branch being compared, and the resultant delta wants to
change the file's contents, but the file doesn't exist in
the working copy. Whatever the case, the
<quote>skipped</quote> message means that the user is most
- likely comparing the wrong two trees; they're the classic
+ likely comparing the wrong two trees; it's the classic
sign of user error. When this happens, it's easy to
recursively revert all the changes created by the merge
- (<command>svn revert --recursive</command>), delete any
+ (<userinput>svn revert . --recursive</userinput>), delete any
unversioned files or directories left behind after the
revert, and rerun <command>svn merge</command> with
different arguments.</para>
- <para>Also notice that the previous example shows a conflict
+ <para>Also notice that the preceeding example shows a conflict
happening on <filename>glorb.h</filename>. We already
stated that the working copy has no local edits: how can a
conflict possibly happen? Again, because the user can use
@@ -1592,7 +1626,7 @@
the file has no local modifications.</para>
<para>Another small difference between <command>svn
- update</command> and <command>svn merge</command> are the
+ update</command> and <command>svn merge</command> is the
names of the full-text files created when a conflict
happens. In <xref linkend="svn.tour.cycle.resolve"/>, we saw
that an update produces files named
@@ -1607,7 +1641,7 @@
describing which side of the double-tree comparison the file
came from. In any case, these differing names will help you
distinguish between conflicts that happened as a result of an
- update versus ones that happened as a result of a
+ update and ones that happened as a result of a
merge.</para>
</sect2>
@@ -1622,13 +1656,13 @@
<filename>/trunk</filename>, but to be more conservative about
backporting changes to a stable branch you use for releasing
to the public. On one extreme, you can manually cherrypick
- single changesets from trunk to the branch—just the
+ single changesets from the trunk to the branch—just the
changes that are stable enough to pass muster. Maybe things
aren't quite that strict, though; perhaps most of the time
you'd like to just let <command>svn merge</command>
automatically merge most changes from trunk to branch. In
this case, you'd like a way to mask a few specific changes
- out, i.e. prevent them from ever being automatically
+ out, that is, prevent them from ever being automatically
merged.</para>
<para>In Subversion 1.5, the only way to block a changeset is to
@@ -1666,7 +1700,7 @@
the change wasn't actually merged, it just wasn't wanted.
There's no way to ask Subversion for a list of <quote>blocked
changelists.</quote> If you want to track them (so that you
- can unblock them someday.) you'll need to record them in a
+ can unblock them someday). you'll need to record them in a
text file somewhere, or perhaps in an invented property. In
Subversion 1.5, unfortunately, this is the only way to manage
blocked revisions; the plans are to make a better interface
@@ -1683,13 +1717,13 @@
The <command>svn log</command> and <command>svn
blame</command> commands are just the tools for this: when
invoked on individual files, they show not only the history of
- changesets that affected the file, but exactly which user
- wrote which line of code, and when they did it.</para>
+ changesets that affected the file, but also exactly which user
+ wrote which line of code, and when she did it.</para>
<para>When changes start getting replicated between branches,
however, things start to get complicated. For example, if you
were to ask <command>svn log</command> about the history of
- your feature branch, it shows exactly every revision that ever
+ your feature branch, it would show exactly every revision that ever
affected the branch:</para>
<screen>
@@ -1719,9 +1753,9 @@
<para>But is this really an accurate picture of all the changes
that happened on the branch? What's being left out here is
the fact that revisions 390, 381, and 357 were actually the
- results of merging changes from trunk. If you look at a one
+ results of merging changes from the trunk. If you look at one
of these logs in detail, the multiple trunk changesets that
- comprised the branch change are nowhere to be seen.</para>
+ comprised the branch change are nowhere to be seen:</para>
<screen>
$ svn log -v -r 390
@@ -1767,14 +1801,14 @@
</screen>
<para>By making the log operation use merge history, we see not
- just the revision we queried (r390), but the two revisions
+ just the revision we queried (r390), but also the two revisions
that came along on the ride with it—a couple of changes
made by Sally to the trunk. This is a much more complete
picture of history!</para>
<para>The <command>svn blame</command> command also takes the
<option>--use-merge-history</option> (<option>-g</option>)
- option. If this option is neglected, then somebody looking at
+ option. If this option is neglected, somebody looking at
a line-by-line annotation of <filename>button.c</filename> may
get the mistaken impression that you were responsible for the
lines that fixed a certain error:</para>
@@ -1814,7 +1848,7 @@
very likely hear reference to the term
<firstterm>ancestry</firstterm>. This word is used to
describe the relationship between two objects in a
- repository: if they're related to each other, then one
+ repository: if they're related to each other, one
object is said to be an ancestor of the other.</para>
<para>For example, suppose you commit revision 100, which
@@ -1879,12 +1913,12 @@
shuffled around and renamed, often causing great disruption
to everyone working on the project. Sounds like a perfect
case to use a branch, doesn't it? Just create a branch,
- shuffle things around, then merge the branch back to the
+ shuffle things around, and then merge the branch back to the
trunk, right?</para>
<para>Alas, this scenario doesn't work so well right now and
is considered one of Subversion's current weak spots. The
- problem is that Subversion's <command>update</command>
+ problem is that Subversion's <command>svn update</command>
command isn't as robust as it should be, particularly when
dealing with copy and move operations.</para>
@@ -1894,7 +1928,7 @@
is running <command>svn update</command> or <command>svn
merge</command>. Instead of telling the client, <quote>Copy
that file you already have to this new location,</quote> it
- instead sends down an entirely new file. This can lead to
+ sends down an entirely new file. This can lead to
problems, especially because the same thing happens with
renamed files. A lesser-known fact about Subversion is that
it lacks <quote>true renames</quote>—the <command>svn
@@ -1946,7 +1980,7 @@
<title>Blocking Merge-Unaware Clients</title>
<para>If you've just upgraded your server to Subversion 1.5 or
- later, then there's a significant risk that pre-1.5 Subversion
+ later, there's a significant risk that pre-1.5 Subversion
clients can mess up your automated merge tracking. Why is
this? When a pre-1.5 Subversion client performs <command>svn
merge</command>, it doesn't modify the value of
@@ -1959,7 +1993,7 @@
resulting from repeated merges.</para>
<para>If you and your team are relying on the merge-tracking
- features of Subversion, then you may want to configure your
+ features of Subversion, you may want to configure your
repository to prevent older clients from committing changes.
The easy way to do this is by inspecting
the <quote>capabilities</quote> parameter in
@@ -1983,8 +2017,8 @@
feature has an extremely complex internal implementation, and
the <literal>svn:mergeinfo</literal> property is the only
window the user has into the machinery. Because the feature
- is relatively new, there are numbers of edge cases and
- possible unexpected behaviors that may pop up.</para>
+ is relatively new, a numbers of edge cases and
+ possible unexpected behaviors may pop up.</para>
<para>For example, sometimes mergeinfo will be generated when
running a simple <command>svn copy</command> or <command>svn
@@ -1996,7 +2030,7 @@
as <quote>explicit</quote> versus <quote>implicit</quote>
mergeinfo, <quote>operative</quote>
versus <quote>inoperative</quote> revisions, specific
- mechanisms of mergeinfo <quote>elision</quote>, and
+ mechanisms of mergeinfo <quote>elision,</quote> and
even <quote>inheritance</quote> from parent to child
directories.</para>
@@ -2008,13 +2042,13 @@
concepts; they'll eventually fade into the background as pesky
implementation details. All that said, if you enjoy this sort
of thing, you can get a fantastic overview in a paper posted
- at Collabnet's website: <ulink
+ at CollabNet's website: <ulink
url="http://www.collab.net/community/subversion/articles/merge-info.html"
- >http://www.collab.net/community/subversion/articles/merge-info.html</ulink>.</para>
+ />.</para>
<para>For now, if you want to steer clear of bugs and odd
- behaviors in automatic merging, the Collabnet article
- recommends you stick to these simple best practices:</para>
+ behaviors in automatic merging, the CollabNet article
+ recommends that you stick to these simple best practices:</para>
<itemizedlist>
<listitem>
@@ -2024,14 +2058,14 @@
</listitem>
<listitem>
<para>For long-lived release branches (as described in
- <xref linkend="svn.branchmerge.commonpatterns"/>), only
- perform merges on the root of the branch, not on
+ <xref linkend="svn.branchmerge.commonpatterns"/>),
+ perform merges only on the root of the branch, not on
subdirectories.</para>
</listitem>
<listitem>
<para>Never merge into working copies with a mixture of
working revision numbers, or with
- <quote>switched</quote> subdirectories (as described
+ <quote>switched</quote> subdirectories (as described next
in <xref linkend="svn.branchmerge.switchwc"/>). A merge
target should be a working copy which represents
a <emphasis>single</emphasis> location in the repository
@@ -2040,7 +2074,7 @@
<listitem>
<para>Don't ever edit the <literal>svn:mergeinfo</literal>
property directly; use <command>svn
- merge --record-only</command> to effect a desired change
+ merge</command> with the <option>--record-only</option> option to effect a desired change
to the metadata (as demonstrated in
<xref linkend="svn.branchmerge.advanced.blockchanges"/>).</para>
</listitem>
@@ -2088,9 +2122,9 @@
</screen>
<para>After <quote>switching</quote> to the branch, your working
- copy is no different than what you would get from doing a fresh
+ copy is no different from what you would get from doing a fresh
checkout of the directory. And it's usually more efficient to
- use this command, because often branches differ only by a small
+ use this command, because often branches differ by only a small
degree. The server sends only the minimal set of changes
necessary to make your working copy reflect the branch
directory.</para>
@@ -2116,18 +2150,18 @@
</listitem>
</orderedlist>
- <para>In other words, if a user knows that the branch-work needs
- only to happen on a specific subdirectory, they use
+ <para>In other words, if a user knows that the branch work needs
+ to happen on only a specific subdirectory, she uses
<command>svn switch</command> to move only that subdirectory to
the branch. (Or sometimes users will switch just a single
- working file to the branch!) That way, they can continue to
- receive normal <quote>trunk</quote> updates to most of their
+ working file to the branch!) That way, the user can continue to
+ receive normal <quote>trunk</quote> updates to most of her
working copy, but the switched portions will remain immune
- (unless someone commits a change to their branch). This feature
+ (unless someone commits a change to her branch). This feature
adds a whole new dimension to the concept of a <quote>mixed
working copy</quote>—not only can working copies contain a
- mixture of working revisions, but a mixture of repository
- locations as well.</para>
+ mixture of working revisions, but they can also contain a
+ mixture of repository locations as well.</para>
<para>If your working copy contains a number of switched subtrees
from different repository locations, it continues to function as
@@ -2139,8 +2173,7 @@
mixture of repository locations, these locations must all be
within the <emphasis>same</emphasis> repository. Subversion
repositories aren't yet able to communicate with one another;
- that's a feature planned for the
- future.
+ that feature is planned for the future.
<footnote>
<para>You <emphasis>can</emphasis>, however, use <command>svn
switch</command> with the <option>--relocate</option> option
@@ -2155,7 +2188,7 @@
<title>Switches and Updates</title>
<para>Have you noticed that the output of <command>svn
- switch</command> and <command>svn update</command> look the
+ switch</command> and <command>svn update</command> looks the
same? The switch command is actually a superset of the update
command.</para>
@@ -2168,12 +2201,12 @@
paths.</para>
<para>That is, if your working copy is a mirror of
- <filename>/calc/trunk</filename>, then <command>svn
+ <filename>/calc/trunk</filename>, <command>svn
update</command> will automatically compare your working copy
of <filename>/calc/trunk</filename> to
<filename>/calc/trunk</filename> in the
<literal>HEAD</literal> revision. If you're switching your
- working copy to a branch, then <command>svn switch</command>
+ working copy to a branch, <command>svn switch</command>
will compare your working copy of
<filename>/calc/trunk</filename> to some
<emphasis>other</emphasis> branch directory in the
@@ -2243,7 +2276,7 @@
<para>Once again, <command>svn copy</command> comes to the
rescue. If you want to create a snapshot of
<filename>/calc/trunk</filename> exactly as it looks in the
- <literal>HEAD</literal> revision, then make a copy of it:</para>
+ <literal>HEAD</literal> revision, make a copy of it:</para>
<screen>
$ svn copy http://svn.example.com/repos/calc/trunk \
@@ -2260,7 +2293,7 @@
<filename>release-1.0</filename> directory is forever a
snapshot of how the <filename>/trunk</filename> directory
looked in the <literal>HEAD</literal> revision at the time you
- made the copy. Of course you might want to be more precise
+ made the copy. Of course, you might want to be more precise
about exactly which revision you copy, in case somebody else
may have committed changes to the project when you weren't
looking. So if you know that revision 901 of
@@ -2268,7 +2301,7 @@
want, you can specify it by passing <option>-r 901</option> to
the <command>svn copy</command> command.</para>
- <para>But wait a moment: isn't this tag-creation procedure the
+ <para>But wait a moment: isn't this tag creation procedure the
same procedure we used to create a branch? Yes, in fact, it
is. In Subversion, there's no difference between a tag and a
branch. Both are just ordinary directories that are created
@@ -2285,7 +2318,7 @@
decide where your tags will live, and make sure all users know
how to treat the directories they copy. (That is, make sure
they know not to commit to them.) The second approach is more
- paranoid: you can use one of the access-control scripts
+ paranoid: you can use one of the access control scripts
provided with Subversion to prevent anyone from doing anything
but creating new copies in the tags area (see
<xref linkend="svn.serverconfig"/>). The paranoid approach,
@@ -2310,8 +2343,8 @@
of your work, you may decide that you need to create a working
copy that is designed to have specific features and bug fixes.
You can accomplish this by selectively backdating files or
- directories to particular revisions (using <command>svn update
- -r</command> liberally), by switching files and directories to
+ directories to particular revisions (using <command>svn update</command>
+ with the <option>-r</option> option liberally), by switching files and directories to
particular branches (making use of <command>svn
switch</command>), or even just by making a bunch of local
changes. When you're done, your working copy is a hodgepodge
@@ -2325,7 +2358,7 @@
Luckily, <command>svn copy</command> actually has four
different uses (which you can read about in <xref
linkend="svn.ref"/>), including the ability to copy a
- working-copy tree to the repository:</para>
+ working copy tree to the repository:</para>
<screen>
$ ls
@@ -2341,14 +2374,14 @@
<para>Now there is a new directory in the repository,
<filename>/calc/tags/mytag</filename>, which is an exact
snapshot of your working copy—mixed revisions, URLs,
- local changes and all.</para>
+ local changes, and all.</para>
<para>Other users have found interesting uses for this feature.
Sometimes there are situations where you have a bunch of local
changes made to your working copy, and you'd like a
collaborator to see them. Instead of running <command>svn
diff</command> and sending a patch file (which won't capture
- directory, symlink, or property changes), you can instead
+ directory, symlink, or property changes), you can
use <command>svn copy</command> to <quote>upload</quote> your
working copy to a private area of the repository. Your
collaborator can then either check out a verbatim copy of your
@@ -2358,7 +2391,7 @@
<para>While this is a nice method for uploading a quick snapshot
of your working copy, note that this is <emphasis>not</emphasis>
a good way to initially create a branch. Branch creation should
- be an event onto itself, and this method conflates the creation
+ be an event unto itself, and this method conflates the creation
of a branch with extra changes to files, all within a single revision.
This makes it very difficult (later on) to identify a single
revision number as a branch point.</para>
@@ -2390,7 +2423,7 @@
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. If a repository holds only one project, then
+ tag copies. If a repository holds only one project,
often people create these top-level directories:</para>
<screen>
@@ -2458,7 +2491,7 @@
Committed revision 375.
</screen>
- <para>And now your branch is gone. Of course it's not really
+ <para>And now your branch is gone. Of course, it's not really
gone: the directory is simply missing from the
<literal>HEAD</literal> revision, no longer distracting
anyone. If you use <command>svn checkout</command>,
@@ -2545,16 +2578,16 @@
<sect2 id="svn.branchmerge.commonpatterns.release">
<title>Release Branches</title>
- <para>Most software has a typical lifecycle: code, test,
+ <para>Most software has a typical life cycle: code, test,
release, repeat. There are two problems with this process.
First, developers need to keep writing new features while
- quality-assurance teams take time to test supposedly stable
+ quality assurance teams take time to test supposedly stable
versions of the software. New work cannot halt while the
software is tested. Second, the team almost always needs to
support older, released versions of software; if a bug is
discovered in the latest code, it most likely exists in
released versions as well, and customers will want to get
- that bugfix without having to wait for a major new
+ that bug fix without having to wait for a major new
release.</para>
<para>Here's where version control can help. The typical
@@ -2567,7 +2600,7 @@
trunk.</emphasis>
Day-to-day changes are committed to
- <filename>/trunk</filename>: new features, bugfixes, and
+ <filename>/trunk</filename>: new features, bug fixes, and
so on.</para>
</listitem>
@@ -2576,7 +2609,7 @@
<quote>release</quote> branch.</emphasis>
When the team thinks the software is ready for release
- (say, a 1.0 release), then <filename>/trunk</filename>
+ (say, a 1.0 release), <filename>/trunk</filename>
might be copied to
<filename>/branches/1.0</filename>.</para>
</listitem>
@@ -2607,10 +2640,10 @@
<para><emphasis>The branch is maintained over time.</emphasis>
While work continues on <filename>/trunk</filename> for
- version 2.0, bugfixes continue to be ported from
+ version 2.0, bug fixes continue to be ported from
<filename>/trunk</filename> to
<filename>/branches/1.0</filename>. When enough
- bugfixes have accumulated, management may decide to do a
+ bug fixes have accumulated, management may decide to do a
1.0.1 release: <filename>/branches/1.0</filename> is
copied to <filename>/tags/1.0.1</filename>, and the tag
is packaged and released.</para>
@@ -2639,7 +2672,7 @@
stability of <filename>/trunk</filename>. Unlike release
branches (which may need to be supported forever), feature
branches are born, used for a while, merged back to the trunk,
- then ultimately deleted. They have a finite span of
+ and then ultimately deleted. They have a finite span of
usefulness.</para>
<para>Again, project policies vary widely concerning exactly
@@ -2660,13 +2693,13 @@
<para>Most projects take a middle-of-the-road approach. They
commonly insist that <filename>/trunk</filename> compile and
pass regression tests at all times. A feature branch is
- only required when a change requires a large number of
+ required only when a change requires a large number of
destabilizing commits. A good rule of thumb is to ask this
question: if the developer worked for days in isolation and
then committed the large change all at once (so that
<filename>/trunk</filename> were never destabilized), would it
be too large a change to review? If the answer to that
- question is <quote>yes,</quote> then the change should be
+ question is <quote>yes,</quote> the change should be
developed on a feature branch. As the developer commits
incremental changes to the branch, they can be easily reviewed
by peers.</para>
@@ -2713,8 +2746,8 @@
final merge step is analogous to running <command>svn
commit</command> from a working copy. After all, what else
<emphasis>is</emphasis> a working copy but a very shallow
- private branch? It's a branch that's only capable of
- storing one change at a time.</para>
+ private branch? It's a branch that's capable of
+ storing only one change at a time.</para>
</sect2>
@@ -2738,7 +2771,7 @@
<para>For example, software developers might be working on an
application that makes use of a third-party library. Subversion
- has just such a relationship with the Apache Portable Runtime
+ has just such a relationship with the Apache Portable Runtime (APR)
library (see <xref linkend="svn.developer.usingapi.apr" />).
The Subversion source code depends on the APR library for all
its portability needs. In earlier stages of Subversion's
@@ -2749,16 +2782,17 @@
API only at well-tested, stable release points.</para>
<para>Now, if your project depends on someone else's information,
- there are several ways that you could attempt to synchronize that
- information with your own. Most painfully, you could issue oral
- or written instructions to all the contributors of your project,
- telling them to make sure that they have the specific versions
+ you could attempt to synchronize that information with your own
+ in several ways. Most painfully, you could issue oral or
+ written instructions to all the contributors of your project,
+ telling them to make sure they have the specific versions
of that third-party information that your project needs. If the
third-party information is maintained in a Subversion
repository, you could also use Subversion's externals
definitions to effectively <quote>pin down</quote> specific
versions of that information to some location in your own
- working copy directory (see <xref linkend="svn.advanced.externals" />).</para>
+ working copy directory (see
+ <xref linkend="svn.advanced.externals" />).</para>
<para>But sometimes you want to maintain custom modifications to
third-party code in your own version control system. Returning
@@ -2774,7 +2808,7 @@
<para>Now you face an interesting situation. Your project could
house its custom modifications to the third-party data in some
disjointed fashion, such as using patch files or full-fledged
- alternate versions of files and directories. But these quickly
+ alternative versions of files and directories. But these quickly
become maintenance headaches, requiring some mechanism by which
to apply your custom changes to the third-party code and
necessitating regeneration of those changes with each successive
@@ -2789,10 +2823,10 @@
<para>Vendor branches provide two benefits. First, by storing
the currently supported vendor drop in your own version control
- system, the members of your project never need to question
+ system, you ensure that the members of your project never need to question
whether they have the right version of the vendor's data. They
simply receive that correct version as part of their regular
- working copy updates. Secondly, because the data lives in your
+ working copy updates. Second, because the data lives in your
own Subversion repository, you can store your custom changes to
it in-place—you have no more need of an automated (or
worse, manual) method for swapping in your customizations.</para>
@@ -2806,7 +2840,7 @@
<filename>/vendor</filename>) to hold the vendor branches.
Then you import the third-party code into a subdirectory of
that top-level directory. You then copy that subdirectory
- into your main development branch (for example,
+ into your main development branch (e.g.,
<filename>/trunk</filename>) at the appropriate location. You
always make your local changes in the main development branch.
With each new release of the code you are tracking, you bring
@@ -2862,7 +2896,7 @@
modified version of libcomplex is now completely integrated
into our calculator program.
<footnote>
- <para>And entirely bug-free, of course!</para>
+ <para>And is entirely bug-free, of course!</para>
</footnote>
</para>
@@ -2939,7 +2973,7 @@
releases of software. This complicates the process of
ensuring that our modifications are still valid for the new
version of code, and things can quickly degrade into a
- situation where we have to manually recreate our
+ situation where we have to manually re-create our
customizations in the new version. Once Subversion knows
about the history of a given source file—including all
its previous locations—the process of merging in the new
@@ -2964,7 +2998,7 @@
Subversion supplies the <command>svn_load_dirs.pl</command>
script to assist with this process. This script automates the
importing steps we mentioned in the general vendor branch
- management procedure to make sure that mistakes are minimized.
+ management procedure to make sure mistakes are minimized.
You will still be responsible for using the merge commands to
merge the new versions of the third-party data into your main
development branch, but <command>svn_load_dirs.pl</command>
@@ -3003,7 +3037,7 @@
current vendor drop will be imported. Finally, the third
argument is the local directory to import. Using our previous
example, a typical run of <command>svn_load_dirs.pl</command>
- might look like:</para>
+ might look like this:</para>
<screen>
$ svn_load_dirs.pl http://svn.example.com/repos/vendor/libcomplex \
@@ -3029,7 +3063,7 @@
<para>When you run <command>svn_load_dirs.pl</command>, it
examines the contents of your existing <quote>current</quote>
vendor drop and compares them with the proposed new vendor
- drop. In the trivial case, there will be no files that are in
+ drop. In the trivial case, no files will be in
one version and not the other, and the script will perform the
new import without incident. If, however, there are
discrepancies in the file layouts between versions,
@@ -3048,8 +3082,8 @@
<command>svn_load_dirs.pl</command> using the
<option>-p</option> command-line option. Each line of the
configuration file is a whitespace-delimited set of two or
- four values: a Perl-style regular expression to match the
- added path against, a control keyword (either
+ four values: a Perl-style regular expression against which to match the
+ added path, a control keyword (either
<literal>break</literal> or <literal>cont</literal>), and then
optionally a property name and value.</para>
@@ -3067,12 +3101,12 @@
(which means that no more property changes should be applied
to that path). If the control specification is
<literal>cont</literal>—an abbreviation for
- <literal>continue</literal>—then matching will continue
+ <literal>continue</literal>—matching will continue
with the next line of the configuration file.</para>
<para>Any whitespace in the regular expression, property name,
or property value must be surrounded by either single or
- double quote characters. You can escape quote characters that
+ double quotes. You can escape quotes that
are not used for wrapping whitespace by preceding them with a
backslash (<literal>\</literal>) character. The backslash
escapes only quotes when parsing the configuration file, so do
@@ -3088,22 +3122,22 @@
<sect1 id="svn.branchmerge.summary">
<title>Summary</title>
- <para>We've covered a lot of ground in this chapter. We've
+ <para>We covered a lot of ground in this chapter. We
discussed the concepts of tags and branches and demonstrated
how Subversion implements these concepts by copying directories
- with the <command>svn copy</command> command. We've shown how
+ with the <command>svn copy</command> command. We showed how
to use <command>svn merge</command> to copy changes from one
- branch to another or roll back bad changes. We've gone over
+ branch to another or roll back bad changes. We went over
the use of <command>svn switch</command> to create
- mixed-location working copies. And we've talked about how one
+ mixed-location working copies. And we talked about how one
might manage the organization and lifetimes of branches in a
repository.</para>
<para>Remember the Subversion mantra: branches and tags are cheap.
So don't be afraid to use them when needed!</para>
- <para>As a helpful reminder of all the operations we've discussed,
- the following table is a handy reference that you can consult as
+ <para>As a helpful reminder of all the operations we discussed,
+ here is handy reference table you can consult as
you begin to make use of branches.</para>
<table id="svn.branchemerge.summary.tbl-1">
@@ -3118,82 +3152,82 @@
<tbody>
<row>
<entry>Create a branch or tag</entry>
- <entry>svn copy URL1 URL2</entry>
+ <entry><userinput>svn copy <replaceable>URL1</replaceable> <replaceable>URL2</replaceable></userinput></entry>
</row>
<row>
<entry>Switch a working copy to a branch or tag</entry>
- <entry>svn switch URL</entry>
+ <entry><userinput>svn switch <replaceable>URL</replaceable></userinput></entry>
</row>
<row>
<entry>Synchronize a branch with trunk</entry>
- <entry>svn merge trunkURL; svn commit</entry>
+ <entry><userinput>svn merge <replaceable>trunkURL</replaceable>; svn commit</userinput></entry>
</row>
<row>
<entry>See merge history or eligible changesets</entry>
- <entry>svn mergeinfo target [--from-source=URL]</entry>
+ <entry><userinput>svn mergeinfo target --from-source=<replaceable>URL</replaceable></userinput></entry>
</row>
<row>
<entry>Merge a branch back into trunk</entry>
- <entry>svn merge --reintegrate branchURL; svn commit</entry>
+ <entry><userinput>svn merge --reintegrate <replaceable>branchURL</replaceable>; svn commit</userinput></entry>
</row>
<row>
<entry>Merge one specific change</entry>
- <entry>svn merge -c REV URL; svn commit</entry>
+ <entry><userinput>svn merge -c <replaceable>REV</replaceable> <replaceable>URL</replaceable>; svn commit</userinput></entry>
</row>
<row>
<entry>Merge a range of changes</entry>
- <entry>svn merge -r REV1:REV2 URL; svn commit</entry>
+ <entry><userinput>svn merge -r <replaceable>REV1</replaceable>:<replaceable>REV2</replaceable> <replaceable>URL</replaceable>; svn commit</userinput></entry>
</row>
<row>
<entry>Block a change from automatic merging</entry>
- <entry>svn merge -c REV --record-only URL; svn commit</entry>
+ <entry><userinput>svn merge -c <replaceable>REV</replaceable> --record-only <replaceable>URL</replaceable>; svn commit</userinput></entry>
</row>
<row>
<entry>Preview a merge</entry>
- <entry>svn merge URL --dry-run</entry>
+ <entry><userinput>svn merge <replaceable>URL</replaceable> --dry-run</userinput></entry>
</row>
<row>
<entry>Abandon merge results</entry>
- <entry>svn revert -R .</entry>
+ <entry><userinput>svn revert -R .</userinput></entry>
</row>
<row>
<entry>Resurrect something from history</entry>
- <entry>svn copy URL at REV local-path</entry>
+ <entry><userinput>svn copy <replaceable>URL</replaceable>@<replaceable>REV</replaceable> <replaceable>localPATH</replaceable></userinput></entry>
</row>
<row>
<entry>Undo a committed change</entry>
- <entry>svn merge -c -REV URL; svn commit</entry>
+ <entry><userinput>svn merge -c -<replaceable>REV</replaceable> <replaceable>URL</replaceable>; svn commit</userinput></entry>
</row>
<row>
<entry>Examine merge-sensitive history</entry>
- <entry>svn log -g; svn blame -g</entry>
+ <entry><userinput>svn log -g; svn blame -g</userinput></entry>
</row>
<row>
<entry>Create a tag from a working copy</entry>
- <entry>svn copy . tagURL</entry>
+ <entry><userinput>svn copy . <replaceable>tagURL</replaceable></userinput></entry>
</row>
<row>
<entry>Rearrange a branch or tag</entry>
- <entry>svn mv URL1 URL2</entry>
+ <entry><userinput>svn mv <replaceable>URL1</replaceable> <replaceable>URL2</replaceable></userinput></entry>
</row>
<row>
<entry>Remove a branch or tag</entry>
- <entry>svn rm URL</entry>
+ <entry><userinput>svn rm <replaceable>URL</replaceable></userinput></entry>
</row>
</tbody>
</tgroup>
Modified: trunk/src/de/book/ch05-repository-admin.xml
==============================================================================
--- trunk/src/de/book/ch05-repository-admin.xml (original)
+++ trunk/src/de/book/ch05-repository-admin.xml Tue Aug 12 11:40:38 2008
@@ -18,7 +18,7 @@
the repository.</para>
<para>If you plan to access a Subversion repository only in the
- role of a user whose data is under version control (that is, via
+ role of a user whose data is under version control (i.e., via
a Subversion client), you can skip this chapter altogether.
However, if you are, or wish to become, a Subversion repository
administrator,
@@ -48,7 +48,7 @@
<emphasis>inside</emphasis> the repository.</para>
<para>Seen through the eyes of a typical file browser application
- (such as the Windows Explorer) or command-line based filesystem
+ (such as Windows Explorer) or command-line based filesystem
navigation tools, the Subversion repository is just another
directory full of stuff. There are some subdirectories with
human-readable configuration files in them, some subdirectories
@@ -73,7 +73,7 @@
<varlistentry>
<term>conf</term>
<listitem>
- <para>A directory containing configuration files.</para>
+ <para>A directory containing configuration files</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -81,41 +81,41 @@
<listitem>
<para>A directory provided to
<filename>mod_dav_svn</filename> for its private
- housekeeping data.</para>
+ housekeeping data</para>
</listitem>
</varlistentry>
<varlistentry>
<term>db</term>
<listitem>
- <para>The data store for all of your versioned data.</para>
+ <para>The data store for all of your versioned data</para>
</listitem>
</varlistentry>
<varlistentry>
<term>format</term>
<listitem>
<para>A file that contains a single integer that
- indicates the version number of the repository layout.</para>
+ indicates the version number of the repository layout</para>
</listitem>
</varlistentry>
<varlistentry>
<term>hooks</term>
<listitem>
<para>A directory full of hook script templates (and hook
- scripts themselves, once you've installed some).</para>
+ scripts themselves, once you've installed some)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>locks</term>
<listitem>
<para>A directory for Subversion's repository lock
- files, used for tracking accessors to the repository.</para>
+ files, used for tracking accessors to the repository</para>
</listitem>
</varlistentry>
<varlistentry>
<term>README.txt</term>
<listitem>
<para>A file whose contents merely inform its readers that
- they are looking at a Subversion repository.</para>
+ they are looking at a Subversion repository</para>
</listitem>
</varlistentry>
</variablelist>
@@ -126,7 +126,7 @@
filesystem, complete with customizable event triggers. This
filesystem has its own notions of directories and files, very
similar to the notions of such things held by real filesystems
- (such as NTFS, FAT32, ext3, and so on). But this is a special
+ (such as NTFS, FAT32, ext3, etc.). But this is a special
filesystem—it hangs these directories and files from
revisions, keeping all the changes you've ever made to them
safely stored and forever accessible. This is where the
@@ -145,11 +145,11 @@
creating and configuring a repository are fairly straightforward
tasks. There are a few preliminary decisions you'll want to
make, but the actual work involved in any given setup of a
- Subversion repository is pretty basic, tending towards
+ Subversion repository is pretty basic, tending toward
mindless repetition if you find yourself setting up multiples of
these things.</para>
- <para>Some things you'll want to consider up front, though, are:</para>
+ <para>Some things you'll want to consider beforehand, though, are:</para>
<itemizedlist>
<listitem>
@@ -247,7 +247,7 @@
tagging (see <xref linkend="svn.branchmerge"/>), the
Subversion community recommends that you choose a repository
location for each <firstterm>project
- root</firstterm>—the <quote>top-most</quote> directory
+ root</firstterm>—the <quote>topmost</quote> directory
that contains data related to that project—and then
create three subdirectories beneath that root:
<filename>trunk</filename>, meaning the directory under which
@@ -259,12 +259,12 @@
changed.
<footnote>
<para>The <filename>trunk</filename>, <filename>tags</filename>,
- and <filename>branches</filename> trio are sometimes referred
+ and <filename>branches</filename> trio is sometimes referred
to as <quote>the TTB directories.</quote></para>
</footnote>
</para>
- <para>For example, your repository might look like:</para>
+ <para>For example, your repository might look like this:</para>
<screen>
/
@@ -291,7 +291,7 @@
repository, perhaps putting projects with similar goals or
shared code in the same subdirectory, or maybe just grouping
them alphabetically. Such an arrangement might look
- like:</para>
+ like this:</para>
<screen>
/
@@ -325,7 +325,7 @@
<filename>trunk</filename>, <filename>tags</filename>, and
<filename>branches</filename> directories live in the root
directory of your repository, and your projects are in
- subdirectories beneath those, like:</para>
+ subdirectories beneath those, like so:</para>
<screen>
/
@@ -351,9 +351,9 @@
users. Especially in large, multiproject situations with
many users, those users may tend to be familiar with only one
or two of the projects in the repository. But the
- projects-as-branch-siblings tends to de-emphasize project
+ projects-as-branch-siblings approach tends to deemphasize project
individuality and focus on the entire set of projects as a
- single entity. That's a social issue though. We like our
+ single entity. That's a social issue, though. We like our
originally suggested arrangement for purely practical
reasons—it's easier to ask about (or modify, or migrate
elsewhere) the entire history of a single project when there's
@@ -369,7 +369,7 @@
<para>Before creating your Subversion repository, an obvious
question you'll need to answer is where the thing is going to
- live. This is strongly connected to a myriad of other
+ live. This is strongly connected to myriad other
questions involving how the repository will be accessed (via a
Subversion server or directly), by whom (users behind your
corporate firewall or the whole world out on the open
@@ -443,68 +443,68 @@
<entry morerows="1">Reliability</entry>
<entry>Data integrity</entry>
<entry>When properly deployed, extremely reliable;
- Berkeley DB 4.4 brings auto-recovery.</entry>
+ Berkeley DB 4.4 brings auto-recovery</entry>
<entry>Older versions had some rarely demonstrated, but
- data-destroying bugs.</entry>
+ data-destroying bugs</entry>
</row>
<row>
<entry>Sensitivity to interruptions</entry>
<entry>Very; crashes and permission problems can leave the
database <quote>wedged,</quote> requiring journaled
- recovery procedures.</entry>
- <entry>Quite insensitive.</entry>
+ recovery procedures</entry>
+ <entry>Quite insensitive</entry>
</row>
<row>
<entry morerows="3">Accessibility</entry>
<entry>Usable from a read-only mount</entry>
- <entry>No.</entry>
- <entry>Yes.</entry>
+ <entry>No</entry>
+ <entry>Yes</entry>
</row>
<row>
<entry>Platform-independent storage</entry>
- <entry>No.</entry>
- <entry>Yes.</entry>
+ <entry>No</entry>
+ <entry>Yes</entry>
</row>
<row>
<entry>Usable over network filesystems</entry>
- <entry>Generally, no.</entry>
- <entry>Yes.</entry>
+ <entry>Generally, no</entry>
+ <entry>Yes</entry>
</row>
<row>
<entry>Group permissions handling</entry>
<entry>Sensitive to user umask problems; best if accessed
- by only one user.</entry>
- <entry>Works around umask problems.</entry>
+ by only one user</entry>
+ <entry>Works around umask problems</entry>
</row>
<row>
<entry morerows="2">Scalability</entry>
<entry>Repository disk usage</entry>
- <entry>Larger (especially if logfiles aren't purged).</entry>
- <entry>Smaller.</entry>
+ <entry>Larger (especially if logfiles aren't purged)</entry>
+ <entry>Smaller</entry>
</row>
<row>
<entry>Number of revision trees</entry>
- <entry>Database; no problems.</entry>
+ <entry>Database; no problems</entry>
<entry>Some older native filesystems don't scale well with
- thousands of entries in a single directory.</entry>
+ thousands of entries in a single directory</entry>
</row>
<row>
<entry>Directories with many files</entry>
- <entry>Slower.</entry>
- <entry>Faster.</entry>
+ <entry>Slower</entry>
+ <entry>Faster</entry>
</row>
<row>
<entry morerows="1">Performance</entry>
<entry>Checking out latest revision</entry>
- <entry>No meaningful difference.</entry>
- <entry>No meaningful difference.</entry>
+ <entry>No meaningful difference</entry>
+ <entry>No meaningful difference</entry>
</row>
<row>
<entry>Large commits</entry>
<entry>Slower overall, but cost is amortized across the
- lifetime of the commit.</entry>
+ lifetime of the commit</entry>
<entry>Faster overall, but finalization delay may cause
- client timeouts.</entry>
+ client timeouts</entry>
</row>
</tbody>
</tgroup>
@@ -545,7 +545,7 @@
progress, the developers decided to use Berkeley DB for a
variety of reasons, including its open source license,
transaction support, reliability, performance, API
- simplicity, thread-safety, support for cursors, and so
+ simplicity, thread safety, support for cursors, and so
on.</para>
<para>Berkeley DB provides real transaction
@@ -558,7 +558,7 @@
is constantly changing at the hand of some other
process—and can make decisions based on that view. If
the decision made happens to conflict with what another
- process is doing, the entire operation is rolled back as if
+ process is doing, the entire operation is rolled back as though
it never happened, and Subversion gracefully retries the
operation against a new, updated (and yet still static) view
of the database.</para>
@@ -591,11 +591,11 @@
Subversion repository that was created on a Unix system onto
a Windows system and expect it to work. While much of the
Berkeley DB database format is architecture-independent,
- there are other aspects of the environment that are not.
- Secondly, Subversion uses Berkeley DB in a way that will not
+ other aspects of the environment are not.
+ Second, Subversion uses Berkeley DB in a way that will not
operate on Windows 95/98 systems—if you need to house
a BDB-backed repository on a Windows machine, stick with
- Windows 2000 or newer.</para>
+ Windows 2000 or later.</para>
<para>While Berkeley DB promises to behave correctly on
network shares that meet a particular set of specifications,
@@ -644,14 +644,14 @@
ownership and permissions on the database files.</para>
<note>
- <para>Berkeley DB 4.4 brings (to Subversion 1.4 and better)
+ <para>Berkeley DB 4.4 brings (to Subversion 1.4 and later)
the ability for Subversion to automatically and
transparently recover Berkeley DB environments in need of
such recovery. When a Subversion process attaches to a
repository's Berkeley DB environment, it uses some process
accounting mechanisms to detect any unclean disconnections
by previous processes, performs any necessary recovery,
- and then continues on as if nothing happened. This
+ and then continues on as though nothing happened. This
doesn't completely eliminate instances of repository
wedging, but it does drastically reduce the amount of
human interaction required to recover from them.</para>
@@ -663,7 +663,7 @@
or <command>svnserve</command> (see <xref
linkend="svn.serverconfig"/>)—rather than accessing it
as many different users via <literal>file://</literal> or
- <literal>svn+ssh://</literal> URLs. If accessing a Berkeley
+ <literal>svn+ssh://</literal> URLs. If you're accessing a Berkeley
DB repository directly as multiple users, be sure to read
<xref linkend="svn.serverconfig.multimethod"/> later in this
chapter.</para>
@@ -693,19 +693,19 @@
in other revision trees. Unlike a Berkeley DB database,
this storage format is portable across different operating
systems and isn't sensitive to CPU architecture. Because
- there's no journaling or shared-memory files being used, the
+ no journaling or shared-memory files are being used, the
repository can be safely accessed over a network filesystem
and examined in a read-only environment. The lack of
- database overhead also means that the overall repository
+ database overhead also means the overall repository
size is a bit smaller.</para>
- <para>FSFS has different performance characteristics too.
+ <para>FSFS has different performance characteristics, too.
When committing a directory with a huge number of files,
FSFS is able to more quickly append directory entries. On
the other hand, FSFS writes the latest version of a file as
a delta against an earlier version, which means that
checking out the latest tree is a bit slower than fetching
- the fulltexts stored in a Berkeley DB HEAD revision. FSFS
+ the full-texts stored in a Berkeley DB HEAD revision. FSFS
also has a longer delay when finalizing a commit, which
could in extreme cases cause clients to time out while
waiting for a response.</para>
@@ -729,7 +729,7 @@
</footnote>
FSFS is a newer bit of engineering. Prior to Subversion
1.4, it was still shaking out some pretty serious data
- integrity bugs, which, while only triggered in very rare
+ integrity bugs, which, while triggered in only very rare
cases, nonetheless did occur. That said, FSFS has quickly
become the backend of choice for some of the largest public
and private Subversion repositories, and it promises a lower
@@ -746,7 +746,7 @@
<sect1 id="svn.reposadmin.create">
<title>Creating and Configuring Your Repository</title>
- <para>Earlier, in <xref linkend="svn.reposadmin.planning" />, we
+ <para>Earlier in this chapter (in <xref linkend="svn.reposadmin.planning" />), we
looked at some of the important decisions that should be made
before creating and configuring your Subversion repository.
Now, we finally get to get our hands dirty! In this section,
@@ -845,7 +845,7 @@
or the modification of an unversioned property. Some hooks
(the so-called <quote>pre hooks</quote>) run in advance of a
repository operation and provide a means by which to both
- report what is about to happen and to prevent it from
+ report what is about to happen and prevent it from
happening at all. Other hooks (the <quote>post hooks</quote>)
run after the completion of a repository event and are useful
for performing tasks that examine—but don't
@@ -931,11 +931,11 @@
the big picture of how your repository is deployed.
For example, if you are using server configuration
to determine which users are permitted to commit
- changes to your repository, then you don't need to do this
+ changes to your repository, you don't need to do this
sort of access control via the hook system.</para>
<para>There is no shortage of Subversion hook programs and
- scripts freely available either from the Subversion community
+ scripts that are freely available either from the Subversion community
itself or elsewhere. These scripts cover a wide range of
utility—basic access control, policy adherence checking,
issue tracker integration, email- or syndication-based commit
@@ -969,11 +969,11 @@
<title>Berkeley DB Configuration</title>
<para>A Berkeley DB environment is an encapsulation of one or
- more databases, logfiles, region files and configuration
+ more databases, logfiles, region files, and configuration
files. The Berkeley DB environment has its own set of default
configuration values for things such as the number of database
locks allowed to be taken out at any given time, the maximum
- size of the journaling logfiles, etc. Subversion's
+ size of the journaling logfiles, and so on. Subversion's
filesystem logic additionally chooses default values for some
of the Berkeley DB configuration options. However, sometimes
your particular repository, with its unique collection of data
@@ -991,7 +991,7 @@
Subversion itself creates this file when it creates the rest
of the repository. The file initially contains some default
options, as well as pointers to the Berkeley DB online
- documentation so you can read about what those options do. Of
+ documentation so that you can read about what those options do. Of
course, you are free to add any of the supported Berkeley DB
options to your <filename>DB_CONFIG</filename> file. Just be
aware that while Subversion never attempts to read or
@@ -1020,7 +1020,7 @@
section will introduce you to the repository administration
tools provided by Subversion and discuss how to wield them to
accomplish tasks such as repository data migration, upgrades,
- backups and cleanups.</para>
+ backups, and cleanups.</para>
<!-- =============================================================== -->
<sect2 id="svn.reposadmin.maint.tk">
@@ -1161,17 +1161,17 @@
<orderedlist>
<listitem>
- <para>The author, followed by a newline.</para>
+ <para>The author, followed by a newline</para>
</listitem>
<listitem>
- <para>The date, followed by a newline.</para>
+ <para>The date, followed by a newline</para>
</listitem>
<listitem>
<para>The number of characters in the log message,
- followed by a newline.</para>
+ followed by a newline</para>
</listitem>
<listitem>
- <para>The log message itself, followed by a newline.</para>
+ <para>The log message itself, followed by a newline</para>
</listitem>
</orderedlist>
@@ -1313,7 +1313,7 @@
<command>fsfs-reshard.py</command> comes in. This script
reshuffles the repository's file structure into a new
arrangement that reflects the requested number of sharding
- subdirecties. This is especially useful for converting an
+ subdirectories. This is especially useful for converting an
older Subversion repository into the new Subversion 1.5
sharded layout (which Subversion will not automatically do
for you) or for fine-tuning an already sharded
@@ -1325,7 +1325,7 @@
<sect3 id="svn.reposadmin.maint.tk.bdbutil">
<title>Berkeley DB utilities</title>
- <para>If you're using a Berkeley DB repository, then all of
+ <para>If you're using a Berkeley DB repository, all of
your versioned filesystem's structure and data live in a set
of database tables within the <filename>db/</filename>
subdirectory of your repository. This subdirectory is a
@@ -1341,7 +1341,7 @@
<command>svnadmin list-unused-dblogs</command> and
<command>svnadmin list-dblogs</command> perform a
subset of what is provided by the Berkeley
- <command>db_archive</command> command, and <command>svnadmin
+ <command>db_archive</command> utility, and <command>svnadmin
recover</command> reflects the common use cases of the
<command>db_recover</command> utility.</para>
@@ -1384,7 +1384,7 @@
repository is configured (using the
<literal>pre-revprop-change</literal> hook; see <xref
linkend="svn.reposadmin.create.hooks"/>) to accept changes to
- this log message after the commit is finished, then the user
+ this log message after the commit is finished, the user
can <quote>fix</quote> her log message remotely using
<command>svn propset</command> (see <xref
linkend="svn.ref.svn.c.propset"/>). However, because of the
@@ -1446,8 +1446,8 @@
<title>How Subversion saves disk space</title>
<para>To keep the repository small,
- Subversion uses <firstterm>deltification</firstterm> (or,
- <quote>deltified storage</quote>) within the repository
+ Subversion uses <firstterm>deltification</firstterm> (or
+ deltified storage) within the repository
itself. Deltification involves encoding the representation
of a chunk of data as a collection of differences against
some other chunk of data. If the two pieces of data are
@@ -1459,10 +1459,10 @@
changes.</quote> The result is that most of the repository
data that tends to be bulky—namely, the contents of
versioned files—is stored at a much smaller size than
- the original <quote>fulltext</quote> representation of that
+ the original full-text representation of that
data. And for repositories created with Subversion 1.4 or
later, the space savings are even better—now those
- fulltext representations of file contents are themselves
+ full-text representations of file contents are themselves
compressed.</para>
<note>
@@ -1515,7 +1515,7 @@
to determine who created the transaction, when it was
created, what types of changes were made in the
transaction—information that is helpful in determining
- whether or not the transaction is a safe candidate for
+ whether the transaction is a safe candidate for
removal! If you do indeed want to remove a transaction, its
name can be passed to <command>svnadmin rmtxns</command>,
which will perform the cleanup of the transaction. In fact,
@@ -1562,7 +1562,7 @@
<para>The output of the script is basically a concatenation of
several chunks of <command>svnlook info</command> output
(see <xref linkend="svn.reposadmin.maint.tk.svnlook"/>) and
- will look something like:</para>
+ will look something like this:</para>
<screen>
$ txn-info.sh myrepos
@@ -1594,7 +1594,7 @@
logs, Subversion revision history, and so on—can be
employed in the decision-making process. And of course, an
administrator can often simply communicate with a seemingly
- dead transaction's owner (via email, for example) to verify
+ dead transaction's owner (via email, e.g.) to verify
that the transaction is, in fact, in a zombie state.</para>
</sect3>
@@ -1610,7 +1610,7 @@
all the actions taken along the route of changing the
database from one state to another—while the database
files, at any given time, reflect a particular state, the
- logfiles contain all the many changes along the way
+ logfiles contain all of the many changes along the way
<emphasis>between</emphasis> states. Thus, they can grow
and accumulate quite rapidly.</para>
@@ -1618,8 +1618,8 @@
DB, the database environment has the ability to remove its
own unused logfiles automatically. Any
repositories created using <command>svnadmin</command>
- when compiled against Berkeley DB version 4.2 or greater
- will be configured for this automatic log file removal. If
+ when compiled against Berkeley DB version 4.2 or later
+ will be configured for this automatic logfile removal. If
you don't want this feature enabled, simply pass the
<option>--bdb-log-keep</option> option to the
<command>svnadmin create</command> command. If you forget
@@ -1633,7 +1633,7 @@
linkend="svn.reposadmin.create.bdb"/> for more information about
database configuration.</para>
- <para>Without some sort of automatic log file removal in
+ <para>Without some sort of automatic logfile removal in
place, logfiles will accumulate as you use your repository.
This is actually somewhat of a feature of the database
system—you should be able to recreate your entire
@@ -1658,13 +1658,13 @@
<warning>
<para>BDB-backed repositories whose logfiles are used as
part of a backup or disaster recovery plan should
- <emphasis>not</emphasis> make use of the log file
+ <emphasis>not</emphasis> make use of the logfile
autoremoval feature. Reconstruction of a repository's
- data from logfiles can only be accomplished when
+ data from logfiles can only be accomplished only when
<emphasis>all</emphasis> the logfiles are available. If
some of the logfiles are removed from disk before the
backup system has a chance to copy them elsewhere, the
- incomplete set of backed-up log files is essentially
+ incomplete set of backed-up logfiles is essentially
useless.</para> </warning>
</sect3>
@@ -1683,12 +1683,12 @@
BDB-backed repositories, though—if you are using
FSFS-backed ones instead, this won't apply to you. And for
those of you using Subversion 1.4 with Berkeley DB 4.4 or
- better, you should find that Subversion has become much more
+ later, you should find that Subversion has become much more
resilient in these types of situations. Still, wedged
Berkeley DB repositories do occur, and an administrator needs
to know how to safely deal with this circumstance.</para>
- <para>In order to protect the data in your repository, Berkeley
+ <para>To protect the data in your repository, Berkeley
DB uses a locking mechanism. This mechanism ensures that
portions of the database are not simultaneously modified by
multiple database accessors, and that each process sees the
@@ -1702,7 +1702,7 @@
section of the database. (This has nothing to do with the
locks that you, as a user, can apply to versioned files within
the repository; we try to clear up the confusion caused by
- this terminology collision in <xref
+ this terminology collision in the sidebar <xref
linkend="svn.advanced.locking.meanings" />.)</para>
<para>In the course of using your Subversion repository, fatal
@@ -1719,7 +1719,7 @@
transactions, checkpoints, and prewrite journaling to
ensure that only the most catastrophic of events
<footnote>
- <para>e.g., hard drive + huge electromagnet = disaster</para>
+ <para>For example, hard drive + huge electromagnet = disaster.</para>
</footnote>
can permanently destroy a database environment. A
sufficiently paranoid repository administrator will have made
@@ -1731,7 +1731,7 @@
<orderedlist>
<listitem>
- <para>Make sure that there are no processes accessing (or
+ <para>Make sure no processes are accessing (or
attempting to access) the repository. For networked
repositories, this also means shutting down the Apache HTTP
Server or svnserve daemon.</para>
@@ -1745,8 +1745,8 @@
<quote>unwedged.</quote></para>
</listitem>
<listitem>
- <para>Run the command <command>svnadmin recover
- /var/svn/repos</command>. You should see output like
+ <para>Run the command <userinput>svnadmin recover
+ /var/svn/repos</userinput>. You should see output such as
this:</para>
<screen>
@@ -1767,8 +1767,8 @@
wedging. Make sure that you run this command as the user that
owns and manages the database, not just as
<literal>root</literal>. Part of the recovery process might
- involve recreating from scratch various database files (shared
- memory regions, for example). Recovering as
+ involve re-creating from scratch various database files (shared
+ memory regions, e.g.). Recovering as
<literal>root</literal> will create those files such that they
are owned by <literal>root</literal>, which means that even
after you restore connectivity to your repository, regular
@@ -1799,7 +1799,7 @@
<para>Subversion provides such functionality by way of
<firstterm>repository dump streams</firstterm>. A repository
- dump stream (often referred to as a <quote>dumpfile</quote>
+ dump stream (often referred to as a <quote>dump file</quote>
when stored as a file on disk) is a portable, flat file format
that describes the various revisions in your
repository—what was changed, by whom, when, and so on.
@@ -1814,8 +1814,8 @@
<warning>
<para>While the Subversion repository dump format contains
human-readable portions and a familiar structure (it
- resembles an RFC-822 format, the same type of format used
- for most email), it is <emphasis>not</emphasis> a plaintext
+ resembles an RFC 822 format, the same type of format used
+ for most email), it is <emphasis>not</emphasis> a plain-text
file format. It is a binary file format, highly sensitive
to meddling. For example, many text editors will corrupt
the file by automatically converting line endings.</para>
@@ -1837,7 +1837,7 @@
are still other reasons for dumping and loading, including
re-deploying a Berkeley DB repository on a new OS or CPU
architecture, switching between the Berkeley DB and FSFS
- backends, or (as we'll cover later in <xref
+ backends, or (as we'll cover later in this chapter in <xref
linkend="svn.reposadmin.maint.filtering" />) purging versioned
data from repository history.</para>
@@ -1879,7 +1879,7 @@
requested range of revisions. Note that <command>svnadmin
dump</command> is reading revision trees from the repository
just like any other <quote>reader</quote> process would
- (<command>svn checkout</command>, for example), so it's safe
+ (e.g., <command>svn checkout</command>), so it's safe
to run this command at any time.</para>
<para>The other subcommand in the pair, <command>svnadmin
@@ -1940,8 +1940,8 @@
<para>Note that because <command>svnadmin</command> uses
standard input and output streams for the repository dump and
- load process, people who are feeling especially saucy can try
- things like this (perhaps even using different versions of
+ load processes, people who are feeling especially saucy can try
+ things such as this (perhaps even using different versions of
<command>svnadmin</command> on each side of the pipe):</para>
<screen>
@@ -1960,7 +1960,7 @@
by using the <option>--deltas</option> option. With this
option, successive revisions of files will be output as
compressed, binary differences—just as file revisions
- are stored in a repository. This option is slower, but
+ are stored in a repository. This option is slower, but it
results in a dump file much closer in size to the original
repository.</para>
@@ -1988,11 +1988,11 @@
<para>By default, Subversion will not express the first dumped
revision as merely differences to be applied to the previous
revision. For one thing, there is no previous revision in the
- dump file! And secondly, Subversion cannot know the state of
+ dump file! And second, Subversion cannot know the state of
the repository into which the dump data will be loaded (if it
ever is). To ensure that the output of each
execution of <command>svnadmin dump</command> is
- self-sufficient, the first dumped revision is by default a
+ self-sufficient, the first dumped revision is, by default, a
full representation of every directory, file, and property in
that revision of the repository.</para>
@@ -2040,10 +2040,10 @@
using the <option>--parent-dir</option> option of
<command>svnadmin load</command>, you can specify a new
virtual root directory for the load process. That means if
- you have dump files for three repositories, say
+ you have dump files for three repositories—say
<filename>calc-dumpfile</filename>,
<filename>cal-dumpfile</filename>, and
- <filename>ss-dumpfile</filename>, you can first create a new
+ <filename>ss-dumpfile</filename>—you can first create a new
repository to hold them all:</para>
<screen>
@@ -2141,7 +2141,7 @@
to manually inspect and modify it.</para>
<para>That's where <command>svndumpfilter</command> becomes
- useful. This program acts as path-based filter for
+ useful. This program acts as a path-based filter for
repository dump streams. Simply give it either a list of
paths you wish to keep or a list of paths you wish to not
keep, and then pipe your repository dump data through this
@@ -2149,9 +2149,9 @@
that contains only the versioned paths you (explicitly or
implicitly) requested.</para>
- <para>Let's look a realistic example of how you might use this
- program. We discuss elsewhere (see <xref
- linkend="svn.reposadmin.projects.chooselayout"/>) the
+ <para>Let's look at a realistic example of how you might use this
+ program. Earlier in this chapter (see <xref
+ linkend="svn.reposadmin.projects.chooselayout"/>), we discussed the
process of deciding how to choose a layout for the data in
your repositories—using one repository per project or
combining them, arranging stuff within your repository, and
@@ -2220,7 +2220,7 @@
<filename>branches</filename> directories to live in the root
of your repository, you might wish to edit your dump files,
tweaking the <literal>Node-path</literal> and
- <literal>Node-copyfrom-path</literal> headers so they no
+ <literal>Node-copyfrom-path</literal> headers so that they no
longer have that first <filename>calc/</filename> path
component. Also, you'll want to remove the section of dump
data that creates the <filename>calc</filename> directory. It
@@ -2236,9 +2236,9 @@
<warning>
<para>If you do plan on manually editing the dump file to
- remove a top-level directory, make sure that your editor is
+ remove a top-level directory, make sure your editor is
not set to automatically convert end-of-line characters to
- the native format (e.g. <literal>\r\n</literal> to
+ the native format (e.g., <literal>\r\n</literal> to
<literal>\n</literal>), as the content will then not agree
with the metadata. This will render the dump file
useless.</para>
@@ -2246,7 +2246,7 @@
<para>All that remains now is to create your three new
repositories, and load each dump file into the right
- repository, ignoring the UUID found in the dumpstream:</para>
+ repository, ignoring the UUID found in the dump stream:</para>
<screen>
$ svnadmin create calc
@@ -2302,7 +2302,7 @@
<para>If empty revisions are not dropped, preserve the
revision properties (log message, author, date, custom
properties, etc.) for those empty revisions.
- Otherwise, empty revisions will only contain the
+ Otherwise, empty revisions will contain only the
original datestamp, and a generated log message that
indicates that this revision was emptied by
<command>svndumpfilter</command>.</para>
@@ -2336,7 +2336,7 @@
them), other programs that generate dump data might
not be so consistent.</para>
</footnote>
- you should probably normalize those paths so they all
+ you should probably normalize those paths so that they all
have, or all lack, leading slashes.</para>
<para>Also, copied paths can give you some trouble.
@@ -2345,7 +2345,7 @@
It is possible that at some point in the lifetime of your
repository, you might have copied a file or directory from
some location that <command>svndumpfilter</command> is
- excluding, to a location that it is including. In order to
+ excluding, to a location that it is including. To
make the dump data self-sufficient,
<command>svndumpfilter</command> needs to still show the
addition of the new path—including the contents of any
@@ -2367,7 +2367,7 @@
repository of its own, you would, of course, use the
<command>svndumpfilter include</command> command to keep all
the changes in and under
- <filename>trunk/my-project</filename>. But the resulting
+ <filename>trunk/my-project</filename>. But the resultant
dump file makes no assumptions about the repository into
which you plan to load this data. Specifically, the dump
data might begin with the revision that added the
@@ -2397,7 +2397,7 @@
as a soft-upgrade mechanism, and so on.</para>
<para>As of version 1.4, Subversion provides a program for
- managing scenarios like
+ managing scenarios such as
these—<command>svnsync</command>. This works by
essentially asking the Subversion server to
<quote>replay</quote> revisions, one at a time. It then uses
@@ -2405,7 +2405,7 @@
another repository. Neither repository needs to be locally
accessible to the machine on which <command>svnsync</command> is
running—its parameters are repository URLs, and it does
- all its work through Subversion's repository access (RA)
+ all its work through Subversion's Repository Access (RA)
interfaces. All it requires is read access to the source
repository and read/write access to the destination
repository.</para>
@@ -2413,7 +2413,7 @@
<note>
<para>When using <command>svnsync</command> against a remote
source repository, the Subversion server for that repository
- must be running Subversion version 1.4 or better.</para>
+ must be running Subversion version 1.4 or later.</para>
</note>
<para>Assuming you already have a source repository that you'd
@@ -2481,7 +2481,7 @@
repository lives. This remote host has a global configuration
that permits anonymous users to read the contents of
repositories on the host, but requires users to authenticate
- in order to modify those repositories. (Please forgive us for
+ to modify those repositories. (Please forgive us for
glossing over the details of Subversion server configuration
for the moment—those are covered thoroughly in <xref
linkend="svn.serverconfig" />.) And for no other reason than
@@ -2543,7 +2543,7 @@
ensure that only the <literal>syncuser</literal> user is
permitted to commit new revisions to the repository. We do
this using a <filename>start-commit</filename> hook scripts
- like the one in <xref
+ such as the one in <xref
linkend="svn.reposadmin.maint.replication.start-commit"
/>.</para>
@@ -2642,7 +2642,7 @@
repository is. Finally, it asks the source repository's
server to start replaying all the revisions between 0 and that
latest revision. As <command>svnsync</command> get the
- resulting response from the source repository's server, it
+ resultant response from the source repository's server, it
begins forwarding those revisions to the target repository's
server as new commits.</para>
@@ -2699,7 +2699,7 @@
synchronize</command> command, and it will happily pick up
right where it left off. In fact, as new revisions appear in
the source repository, this is exactly what you to do
- in order to keep your mirror up to date.</para>
+ to keep your mirror up to date.</para>
<sidebar>
<title>svnsync Bookkeeping</title>
@@ -2743,11 +2743,11 @@
<para>That <command>svnsync</command> stores the source
repository URL in a bookkeeping property on the mirror
- repository is the reason why you only have to specify that
- URL once, during <command>svnsync init</command>. Future
+ repository is the reason why you have to specify that
+ URL only once, during <command>svnsync init</command>. Future
synchronization operations against that mirror simply
consult the special <literal>svn:sync-from-url</literal>
- property stored on the mirror itself in order to know where
+ property stored on the mirror itself to know where
to synchronize from. This value is used literally by the
synchronization process, though. So while from within
CollabNet's network you can perhaps access our example
@@ -2785,7 +2785,7 @@
for example, you were maintaining a mirror of a mirror of a
third repository. When <command>svnsync</command> sees its
own special properties in revision 0 of the source
- repository, it simple ignores them.</para>
+ repository, it simply ignores them.</para>
</sidebar>
@@ -2800,7 +2800,7 @@
and patch up its copy of revision 12. You'll need to tell it
to do so manually by using (or with some additional tooling
around) the <command>svnsync copy-revprops</command>
- subcommand, which simply re-replicates all the revision
+ subcommand, which simply rereplicates all the revision
properties for a particular revision or range thereof.</para>
<screen>
@@ -2826,9 +2826,9 @@
<para>Also, while it isn't very commonplace to do so,
<command>svnsync</command> does gracefully mirror repositories
- in which the user as whom it authenticates only has partial
+ in which the user as whom it authenticates has only partial
read access. It simply copies only the bits of the repository
- that it is permitted to see. Obviously such a mirror is not
+ that it is permitted to see. Obviously, such a mirror is not
useful as a backup solution.</para>
<para>In Subversion 1.5, <command>svnsync</command> grew the
@@ -2839,15 +2839,15 @@
repository's root URL when running <command>svnsync
init</command>, you specify the URL of some subdirectory
within that repository. Synchronization to that mirror will
- now only copy the bits that changed under that source
+ now copy only the bits that changed under that source
repository subdirectory. There are some limitations to this
- support though. First, you can't mirror multiple disjoint
+ support, though. First, you can't mirror multiple disjoint
subdirectories of the source repository into a single mirror
repository—you'd need to instead mirror some parent
- directory that is common to both. Secondly, the filtering
+ directory that is common to both. Second, the filtering
logic is entirely path-based, so if the subdirectory you are
mirroring was renamed at some point in the past, your mirror
- would only contain the revisions since the directory appeared
+ would contain only the revisions since the directory appeared
at the URL you specified. And likewise, if the source
subdirectory is renamed in the future, your synchronization
processes will stop mirroring data at the point that the
@@ -2863,7 +2863,7 @@
chapter for more about this.</para>
<para>Once the two repositories have the same UUID, you can use
- <command>svn switch --relocate</command> to point your working
+ <command>svn switch</command> with the <option>--relocate</option> option to point your working
copy to whichever of the repositories you wish to operate
against, a process that is described in <xref
linkend="svn.ref.svn.c.switch" />. There is a possible danger
@@ -2898,7 +2898,7 @@
<para>Despite numerous advances in technology since the birth of
the modern computer, one thing unfortunately rings true with
- crystalline clarity—sometimes, things go very, very
+ crystalline clarity—sometimes things go very, very
awry. Power outages, network connectivity dropouts, corrupt
RAM, and crashed hard drives are but a taste of the evil that
Fate is poised to unleash on even the most conscientious
@@ -2929,15 +2929,15 @@
the Subversion development team has already done so. The
<command>svnadmin hotcopy</command> command takes care of the
minutia involved in making a hot backup of your repository.
- And its invocation is as trivial as Unix's
- <command>cp</command> or Windows' <command>copy</command>
+ And its invocation is as trivial as the Unix
+ <command>cp</command> or Windows <command>copy</command>
operations:</para>
<screen>
$ svnadmin hotcopy /var/svn/repos /var/svn/repos-backup
</screen>
- <para>The resulting backup is a fully functional Subversion
+ <para>The resultant backup is a fully functional Subversion
repository, able to be dropped in as a replacement for your
live repository should something go horribly wrong.</para>
@@ -2963,21 +2963,21 @@
automatically manage the names of the backed-up repository
directories to avoid collisions with previous backups and
will <quote>rotate off</quote> older backups, deleting them so
- only the most recent ones remain. Even if you also have an
+ that only the most recent ones remain. Even if you also have an
incremental backup, you might want to run this program on a
regular basis. For example, you might consider using
<command>hot-backup.py</command> from a program scheduler
(such as <command>cron</command> on Unix systems), which can
- cause it to run nightly (or at whatever granularity of Time
+ cause it to run nightly (or at whatever granularity of time
you deem safe).</para>
<para>Some administrators use a different backup mechanism built
around generating and storing repository dump data. We
described in <xref linkend="svn.reposadmin.maint.migrate" />
- how to use <command>svnadmin dump --incremental</command> to
+ how to use <command>svnadmin dump</command> with the <option>--incremental</option> option to
perform an incremental backup of a given revision or range of
- revisions. And of course, there is a full backup variation of
- this achieved by omitting the <option>--incremental</option>
+ revisions. And of course, you can achieve a full backup variation of
+ this by omitting the <option>--incremental</option>
option to that command. There is some value in these methods,
in that the format of your backed-up information is
flexible—it's not tied to a particular platform,
@@ -3011,7 +3011,7 @@
linkend="svn.reposadmin.maint.replication" />) actually
provides a rather handy middle-ground approach. If you are
regularly synchronizing a read-only mirror with your main
- repository, then in a pinch, your read-only mirror is probably
+ repository, in a pinch your read-only mirror is probably
a good candidate for replacing that main repository if it
falls over. The primary disadvantage of this method is that
only the versioned repository data gets
@@ -3019,7 +3019,7 @@
user-specified repository path locks, and other items that
might live in the physical repository directory but not
<emphasis>inside</emphasis> the repository's virtual versioned
- filesystem are not handled by svnsync.</para>
+ filesystem are not handled by <command>svnsync</command>.</para>
<para>In any backup scenario, repository administrators need
to be aware of how modifications to unversioned revision
@@ -3052,7 +3052,7 @@
diversified one that leverages combinations of the methods
described here. The Subversion developers, for example, back
up the Subversion source code repository nightly using
- <command>hot-backup.py</command> and an offsite
+ <command>hot-backup.py</command> and an off-site
<command>rsync</command> of those full backups; keep multiple
archives of all the commit and property change notification
emails; and have repository mirrors maintained by various
@@ -3097,7 +3097,7 @@
loading repository history (as described earlier in <xref
linkend="svn.reposadmin.maint.migrate" />), you get to decide
whether to apply the UUID encapsulated in the data dump
- stream to the repository you are loading the data into. The
+ stream to the repository in which you are loading the data. The
particular circumstance will dictate the correct
behavior.</para>
@@ -3127,7 +3127,7 @@
these tasks are a little more complicated. You can explicitly
set a repository's UUID by piping a repository dump file stub
that carries the new UUID specification through
- <command>svnadmin load --force-uuid</command>.</para>
+ <userinput>svnadmin load --force-uuid <replaceable>REPOS-PATH</replaceable></userinput>.</para>
<screen>
$ svnadmin load --force-uuid /var/svn/repos <<EOF
@@ -3140,7 +3140,7 @@
$
</screen>
- <para>Having older versions of Subversion generate a brand new
+ <para>Having older versions of Subversion generate a brand-new
UUID is not quite as simple to do, though. Your best bet here
is to find some other way to generate a UUID, and then
explicitly set the repository's UUID to that value.</para>
@@ -3162,7 +3162,7 @@
tools provided by your operating system for manipulating
directories—<command>mv</command>, <command>cp
-a</command>, and <command>rm -r</command> on Unix platforms;
- <command>copy</command>, <command>move</command> and
+ <command>copy</command>, <command>move</command>, and
<command>rmdir /s /q</command> on Windows; vast numbers of mouse
and menu gyrations in various graphical file explorer
applications, and so on.</para>
@@ -3183,7 +3183,7 @@
the fact that Subversion uses repository UUIDs to distinguish
repositories. If you copy a Subversion repository using a
typical shell recursive copy command, you'll wind up with two
- repositories identical in every way—including their UUIDs.
+ repositories that are identical in every way—including their UUIDs.
In some circumstances, this might be desirable. But in the
instances where it is not, you'll need to generate a new UUID
for one of these identical repositories. See <xref
@@ -3199,9 +3199,9 @@
<title>Summary</title>
<para>By now you should have a basic understanding of how to
- create, configure, and maintain Subversion repositories. We've
+ create, configure, and maintain Subversion repositories. We
introduced you to the various tools that will assist you with
- this task. Throughout the chapter, we've noted common
+ this task. Throughout the chapter, we noted common
administration pitfalls and offered suggestions for avoiding
them.</para>
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 Tue Aug 12 11:40:38 2008
@@ -11,10 +11,10 @@
<para>This chapter describes how to get your Subversion repository
exposed outside its host machine for use by remote clients. We
will cover Subversion's currently available server mechanisms,
- discussing the configuration and use of each. After reading
- this section, you should be able to decide which networking
- setup is right for your needs, and understand how to enable such
- a setup on your host computer.</para>
+ discussing the configuration and use of each. After reading this
+ chapter, you should be able to decide which networking setup is
+ right for your needs, as well as understand how to enable such a
+ setup on your host computer.</para>
<!-- ================================================================= -->
@@ -32,15 +32,15 @@
an infinite number of network implementations. In practice,
there are only two servers at the time of this writing.</para>
- <para>Apache is an extremely popular webserver; using the
+ <para>Apache is an extremely popular web server; using the
<command>mod_dav_svn</command> module, Apache can access a
repository and make it available to clients via the
WebDAV/DeltaV protocol, which is an extension of HTTP. Because
- Apache is an extremely extensible web server, it provides a
- number of features <quote>for free</quote>, such as encrypted
- SSL communication, logging, integration with a number of
- third-party authentication systems, and limited built-in web
- browsing of repositories.</para>
+ Apache is an extremely extensible server, it provides a number
+ of features <quote>for free,</quote> such as encrypted SSL
+ communication, logging, integration with a number of third-party
+ authentication systems, and limited built-in web browsing of
+ repositories.</para>
<para>In the other corner is <command>svnserve</command>: a small,
lightweight server program that speaks a custom protocol with
@@ -49,7 +49,7 @@
significantly faster network operations—but at the cost of
some features as well. While it can use SASL to provide a
variety of authentication and encryption options, it has no
- logging or built-in web-browsing. It is, however, extremely
+ logging or built-in web browsing. It is, however, extremely
easy to set up and is often the best option for small teams just
starting out with Subversion.</para>
@@ -61,7 +61,7 @@
also used exclusively to authenticate, so real system accounts
are required on the server host (unlike
vanilla <command>svnserve</command>, which has its own private
- user accounts.) Finally, because this setup requires that each
+ user accounts). Finally, because this setup requires that each
user spawn a private, temporary <command>svnserve</command>
process, it's equivalent (from a permissions point of view) to
allowing a group of local users to all access the repository
@@ -69,11 +69,11 @@
has no meaning, since each user is accessing the repository
database files directly.</para>
- <para>Here's a quick summary of the three typical server
- deployments.</para>
+ <para><xref linkend="svn.serverconfig.overview.tbl-1"/> provides a
+ quick summary of the three typical server deployments.</para>
<table id="svn.serverconfig.overview.tbl-1">
- <title>Comparison of Subversion Server Options</title>
+ <title>Comparison of subversion server options</title>
<tgroup cols="4">
<thead>
<row>
@@ -95,52 +95,52 @@
<row>
<entry>User account options</entry>
- <entry>private 'users' file, or other mechanisms
+ <entry>Private 'users' file, or other mechanisms
available to Apache httpd (LDAP, SQL, etc.)</entry>
- <entry>private 'users' file, or other mechanisms available
+ <entry>Private 'users' file, or other mechanisms available
to SASL (LDAP, SQL, etc.)</entry>
- <entry>system accounts</entry>
+ <entry>System accounts</entry>
</row>
<row>
<entry>Authorization options</entry>
- <entry>read/write access can be granted over whole
- repository, or specified per-path.</entry>
- <entry>read/write access can be granted over whole
- repository, or specified per-path.</entry>
- <entry>read/write access only grantable over whole
+ <entry>Read/write access can be granted over the whole
+ repository, or specified per path</entry>
+ <entry>Read/write access can be granted over the whole
+ repository, or specified per path</entry>
+ <entry>Read/write access only grantable over the whole
repository</entry>
</row>
<row>
<entry>Encryption</entry>
- <entry>via optional SSL</entry>
- <entry>via optional SASL features</entry>
- <entry>SSH tunneled</entry>
+ <entry>Available via optional SSL</entry>
+ <entry>Available via optional SASL features</entry>
+ <entry>Inherent in SSH connection</entry>
</row>
<row>
<entry>Logging</entry>
- <entry>full Apache logs of each HTTP request, with
+ <entry>Full Apache logs of each HTTP request, with
optional <quote>high-level</quote> logging of general
client operations</entry>
- <entry>no logging</entry>
- <entry>no logging</entry>
+ <entry>No logging</entry>
+ <entry>No logging</entry>
</row>
<row>
<entry>Interoperability</entry>
- <entry>partially usable by other WebDAV clients</entry>
- <entry>only talks to svn clients</entry>
- <entry>only talks to svn clients</entry>
+ <entry>Accessible by other WebDAV clients</entry>
+ <entry>Talks only to svn clients</entry>
+ <entry>Talks only to svn clients</entry>
</row>
<row>
<entry>Web viewing</entry>
- <entry>limited built-in support, or via 3rd-party tools
+ <entry>Limited built-in support, or via third-party tools
such as ViewVC</entry>
- <entry>only via 3rd-party tools such as ViewVC</entry>
- <entry>only via 3rd-party tools such as ViewVC</entry>
+ <entry>Only via third-party tools such as ViewVC</entry>
+ <entry>Only via third-party tools such as ViewVC</entry>
</row>
<row>
@@ -153,16 +153,16 @@
<row>
<entry>Speed</entry>
- <entry>somewhat slower</entry>
- <entry>somewhat faster</entry>
- <entry>somewhat faster</entry>
+ <entry>Somewhat slower</entry>
+ <entry>Somewhat faster</entry>
+ <entry>Somewhat faster</entry>
</row>
<row>
<entry>Initial setup</entry>
- <entry>somewhat complex</entry>
- <entry>extremely simple</entry>
- <entry>moderately simple </entry>
+ <entry>Somewhat complex</entry>
+ <entry>Extremely simple</entry>
+ <entry>Moderately simple</entry>
</row>
</tbody>
@@ -179,7 +179,7 @@
<para>Obviously, there's no right answer to that question. Every
team has different needs, and the different servers all
- represent different sets of tradeoffs. The Subversion project
+ represent different sets of trade-offs. The Subversion project
itself doesn't endorse one server or another, or consider either
server more <quote>official</quote> than another.</para>
@@ -189,7 +189,7 @@
<sect2 id="svn.serverconfig.choosing.svnserve">
- <title>The <command>svnserve</command> Server</title>
+ <title>The svnserve Server</title>
<variablelist>
<varlistentry>
@@ -220,7 +220,7 @@
<listitem><para>By default, only one authentication method
is available, the network protocol is not encrypted,
- and the server stores cleartext passwords. (All these
+ and the server stores clear text passwords. (All these
things can be changed by configuring SASL, but it's a
bit more work to do.)</para></listitem>
@@ -228,7 +228,7 @@
errors.</para></listitem>
<listitem><para>No built-in web browsing. (You'd have to
- install a separate web server and some CGI software to
+ install a separate web server and repository browsing software to
add this.)</para></listitem>
</itemizedlist>
@@ -241,7 +241,7 @@
<sect2 id="svn.serverconfig.choosing.svn-ssh">
- <title><command>svnserve</command> over SSH</title>
+ <title>svnserve over SSH</title>
<variablelist>
<varlistentry>
@@ -249,10 +249,10 @@
<listitem>
<itemizedlist>
- <listitem><para>Network protocol is stateful and
+ <listitem><para>The network protocol is stateful and
noticeably faster than WebDAV.</para></listitem>
- <listitem><para>You can take advantage of existing ssh
+ <listitem><para>You can take advantage of existing SSH
accounts and user infrastructure.</para></listitem>
<listitem><para>All network traffic is
@@ -268,15 +268,15 @@
<itemizedlist>
<listitem><para>Only one choice of authentication
- method.</para></listitem>
+ method is available.</para></listitem>
- <listitem><para>No logging of any kind, not even
+ <listitem><para>There is no logging of any kind, not even
errors.</para></listitem>
- <listitem><para>Requires users to be in same system group, or
- use a shared ssh key.</para></listitem>
+ <listitem><para>It requires users to be in the same system group, or
+ use a shared SSH key.</para></listitem>
- <listitem><para>If used improperly, can lead to file permissions
+ <listitem><para>If used improperly, it can lead to file permission
problems.</para></listitem>
</itemizedlist>
@@ -297,14 +297,14 @@
<listitem>
<itemizedlist>
- <listitem><para>Allows Subversion to use any of the
+ <listitem><para>It allows Subversion to use any of the
numerous authentication systems already integrated
with Apache.</para></listitem>
- <listitem><para>No need to create system accounts on
- server.</para></listitem>
+ <listitem><para>There is no need to create system accounts on
+ the server.</para></listitem>
- <listitem><para>Full Apache logging.</para></listitem>
+ <listitem><para>Full Apache logging is available.</para></listitem>
<listitem><para>Network traffic can be encrypted via
SSL.</para></listitem>
@@ -312,13 +312,13 @@
<listitem><para>HTTP(S) can usually go through corporate
firewalls.</para></listitem>
- <listitem><para>Built-in repository browsing via web
- browser.</para></listitem>
+ <listitem><para>Built-in repository browsing is
+ available via web browser.</para></listitem>
- <listitem><para>Repository can be mounted as a network
- drive for transparent version control. (See
+ <listitem><para>The repository can be mounted as a network
+ drive for transparent version control (see
<xref
- linkend="svn.webdav.autoversioning"/>.)</para></listitem>
+ linkend="svn.webdav.autoversioning"/>).</para></listitem>
</itemizedlist>
</listitem>
@@ -329,8 +329,9 @@
<listitem>
<itemizedlist>
- <listitem><para>Noticeably slower than svnserve, because
- HTTP is a stateless protocol and requires more
+ <listitem><para>Noticeably slower than
+ <command>svnserve</command>, because HTTP is a
+ stateless protocol and requires more network
turnarounds.</para></listitem>
<listitem><para>Initial setup can be complex.</para></listitem>
@@ -350,7 +351,7 @@
<para>In general, the authors of this book recommend a vanilla
<command>svnserve</command> installation for small teams just
trying to get started with a Subversion server; it's the
- simplest to set up, and has the fewest maintenance issues.
+ simplest to set up and has the fewest maintenance issues.
You can always switch to a more complex server
deployment as your needs change.</para>
@@ -360,78 +361,75 @@
<itemizedlist>
<listitem>
<para>If you're trying to set up the simplest possible
- server for your group, then a
+ server for your group, a
vanilla <command>svnserve</command> installation is the
easiest, fastest route. Note, however, that your
repository data will be transmitted in the clear over the
network. If your deployment is entirely within your
company's LAN or VPN, this isn't an issue. If the
- repository is exposed to the wide-open internet, then you
+ repository is exposed to the wide-open Internet, you
might want to make sure that either the repository's
- contents aren't sensitive (e.g. it contains only
- open-source code), or that you go the extra mile in
+ contents aren't sensitive (e.g., it contains only
+ open source code), or that you go the extra mile in
configuring SASL to encrypt network communications.</para>
</listitem>
<listitem>
<para>If you need to integrate with existing legacy identity
- systems (LDAP, Active Directory, NTLM, X.509, etc.), then
+ systems (LDAP, Active Directory, NTLM, X.509, etc.),
you must use either the Apache-based server
or <command>svnserve</command> configured with SASL. If
you absolutely need server-side logs of either server
- errors or client activities, then an Apache-based server
+ errors or client activities, an Apache-based server
is your only option.</para>
</listitem>
<listitem>
<para>If you've decided to use either Apache or stock
- <command>svnserve</command>, create a
- single <literal>svn</literal> user on your system and run
- the server process as that user. Be sure to make the
- repository directory wholly owned by
- the <literal>svn</literal> user as well. From a security
+ <command>svnserve</command>, create a single
+ <command>svn</command> user on your system and run the
+ server process as that user. Be sure to make the
+ repository directory wholly owned by the
+ <command>svn</command> user as well. From a security
point of view, this keeps the repository data nicely
siloed and protected by operating system filesystem
permissions, changeable by only the Subversion server
- process itself.</para>
- </listitem>
+ process itself.</para> </listitem>
<listitem>
- <para>If you have an existing infrastructure heavily based
+ <para>If you have an existing infrastructure that is heavily based
on SSH accounts, and if your users already have system
- accounts on your server machine, then it makes sense to
- deploy an svnserve-over-ssh solution. Otherwise, we don't
- widely recommend this option to the public. It's
- generally considered safer to have your users access the
- repository via (imaginary) accounts managed
- by <command>svnserve</command> or Apache, rather than by
- full-blown system accounts. If your deep desire for
- encrypted communication still draws you to this option, we
- recommend using Apache with SSL
- or <command>svnserve</command> with SASL encryption
- instead.</para>
- </listitem>
+ accounts on your server machine, it makes sense to
+ deploy an <command>svnserve</command>-over-SSH solution.
+ Otherwise, we don't widely recommend this option to the
+ public. It's generally considered safer to have your
+ users access the repository via (imaginary) accounts
+ managed by <command>svnserve</command> or Apache, rather
+ than by full-blown system accounts. If your deep desire
+ for encrypted communication still draws you to this
+ option, we recommend using Apache with SSL or
+ <command>svnserve</command> with SASL encryption
+ instead.</para> </listitem>
<listitem>
<para>Do <emphasis>not</emphasis> be seduced by the simple
idea of having all of your users access a repository
- directly via <literal>file://</literal> URLs. Even if
- the repository is readily available to everyone via
- network share, this is a bad idea. It removes any layers
- of protection between the users and the repository: users
- can accidentally (or intentionally) corrupt the repository
+ directly via <literal>file://</literal> URLs. Even if the
+ repository is readily available to everyone via a network
+ share, this is a bad idea. It removes any layers of
+ protection between the users and the repository: users can
+ accidentally (or intentionally) corrupt the repository
database, it becomes hard to take the repository offline
for inspection or upgrade, and it can lead to a mess of
- file-permissions problems (see
- <xref linkend="svn.serverconfig.multimethod"/>.) Note
- that this is also one of the reasons we warn against
- accessing repositories via <literal>svn+ssh://</literal>
+ file permission problems (see <xref
+ linkend="svn.serverconfig.multimethod"/>). Note that this
+ is also one of the reasons we warn against accessing
+ repositories via <literal>svn+ssh://</literal>
URLs—from a security standpoint, it's effectively
- the same as local users accessing
- via <literal>file://</literal>, and can entail all the
- same problems if the administrator isn't careful.</para>
- </listitem>
- </itemizedlist>
+ the same as local users accessing via
+ <literal>file://</literal>, and it can entail all the same
+ problems if the administrator isn't careful.</para>
+ </listitem> </itemizedlist>
</sect2>
@@ -442,7 +440,7 @@
<!-- ================================================================= -->
<sect1 id="svn.serverconfig.svnserve">
- <title><command>svnserve</command>, a Custom Server</title>
+ <title>svnserve, a Custom Server</title>
<para>The <command>svnserve</command> program is a lightweight
server, capable of speaking to clients over TCP/IP using a
@@ -477,7 +475,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.svnserve.invoking.daemon">
- <title><command>svnserve</command> as Daemon</title>
+ <title>svnserve as daemon</title>
<para>The easiest option is to run <command>svnserve</command>
as a standalone <quote>daemon</quote> process. Use the
@@ -494,11 +492,11 @@
exact port and hostname to <quote>bind</quote> to.</para>
<para>Once we successfully start <command>svnserve</command> as
- above, it makes every repository on your system available to
- the network. A client needs to specify an
+ explained previously, it makes every repository on your system
+ available to the network. A client needs to specify an
<emphasis>absolute</emphasis> path in the repository URL. For
example, if a repository is located at
- <filename>/var/svn/project1</filename>, then a client would
+ <filename>/var/svn/project1</filename>, a client would
reach it via
<uri>svn://host.example.com/var/svn/project1</uri>. To
increase security, you can pass the <option>-r</option> option
@@ -526,16 +524,17 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.svnserve.invoking.inetd">
- <title><command>svnserve</command> via <command>inetd</command></title>
+ <title>svnserve via inetd</title>
<para>If you want <command>inetd</command> to launch the
- process, then you need to pass the <option>-i</option>
- (<option>--inetd</option>) option. In the example, we've shown the
- output from running <literal>svnserve -i</literal> at the
- command line, but note that isn't how you actually start the
- daemon; see the paragraphs following the example for how to
- configure <command>inetd</command> to
- start <command>svnserve</command>.</para>
+ process, you need to pass the <option>-i</option>
+ (<option>--inetd</option>) option. In the following
+ example, we've shown the output from running
+ <literal>svnserve -i</literal> at the command line, but note
+ that this isn't how you actually start the daemon; see the
+ paragraphs following the example for how to configure
+ <command>inetd</command> to start
+ <command>svnserve</command>.</para>
<screen>
$ svnserve -i
@@ -544,12 +543,12 @@
<para>When invoked with the <option>--inetd</option> option,
<command>svnserve</command> attempts to speak with a
- Subversion client via <emphasis>stdin</emphasis> and
- <emphasis>stdout</emphasis> using a custom protocol. This is
+ Subversion client via <filename>stdin</filename> and
+ <filename>stdout</filename> using a custom protocol. This is
the standard behavior for a program being run via
- <command>inetd</command>. The IANA has reserved port 3690
- for the Subversion protocol, so on a Unix-like system you can
- add lines to <filename>/etc/services</filename> like these (if
+ <command>inetd</command>. The IANA has reserved port 3690 for
+ the Subversion protocol, so on a Unix-like system you can add
+ lines to <filename>/etc/services</filename> such as these (if
they don't already exist):</para>
<screen>
@@ -557,7 +556,7 @@
svn 3690/udp # Subversion
</screen>
- <para>And if your system is using a classic Unix-like
+ <para>If your system is using a classic Unix-like
<command>inetd</command> daemon, you can add this line to
<filename>/etc/inetd.conf</filename>:</para>
@@ -565,9 +564,9 @@
svn stream tcp nowait svnowner /usr/bin/svnserve svnserve -i
</screen>
- <para>Make sure <quote>svnowner</quote> is a user which has
- appropriate permissions to access your repositories. Now, when
- a client connection comes into your server on port 3690,
+ <para>Make sure <quote>svnowner</quote> is a user that has
+ appropriate permissions to access your repositories. Now,
+ when a client connection comes into your server on port 3690,
<command>inetd</command> will spawn an
<command>svnserve</command> process to service it. Of course,
you may also want to add <option>-r</option> to the
@@ -578,21 +577,21 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.svnserve.invoking.tunnel">
- <title><command>svnserve</command> over a Tunnel</title>
+ <title>svnserve over a tunnel</title>
<para>A third way to invoke <command>svnserve</command> is in
- <quote>tunnel mode</quote>, with the <option>-t</option>
- option. This mode assumes that a remote-service program
- such as <command>RSH</command> or <command>SSH</command> has
+ tunnel mode, using the <option>-t</option> option. This
+ mode assumes that a remote-service program such as
+ <command>rsh</command> or <command>ssh</command> has
successfully authenticated a user and is now invoking a
private <command>svnserve</command> process <emphasis>as
that user</emphasis>. (Note that you, the user, will
rarely, if ever, have reason to invoke
<command>svnserve</command> with the <option>-t</option> at
- the command line; instead, the <command>SSH</command> daemon
+ the command line; instead, the SSH daemon
does so for you.) The <command>svnserve</command> program
behaves normally (communicating via
- <emphasis>stdin</emphasis> and <emphasis>stdout</emphasis>),
+ <filename>stdin</filename> and <filename>stdout</filename>)
and assumes that the traffic is being automatically
redirected over some sort of tunnel back to the client.
When <command>svnserve</command> is invoked by a tunnel
@@ -601,21 +600,22 @@
It's essentially the same as a local user accessing the
repository via <literal>file://</literal> URLs.</para>
- <para>This option is described in much more detail in
- <xref linkend="svn.serverconfig.svnserve.sshauth"/>.</para>
+ <para>This option is described in much more detail later in
+ this chapter in <xref
+ linkend="svn.serverconfig.svnserve.sshauth"/>.</para>
</sect3>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.svnserve.invoking.winservice">
- <title><command>svnserve</command> as Windows Service</title>
+ <title>svnserve as Windows service</title>
<para>If your Windows system is a descendant of Windows NT
- (2000, 2003, XP, Vista), then you can
+ (2000, 2003, XP, or Vista), you can
run <command>svnserve</command> as a standard Windows
service. This is typically a much nicer experience than
running it as a standalone daemon with the <option>--daemon
- (-d)</option> option. Using daemon-mode requires launching
+ (-d)</option> option. Using daemon mode requires launching
a console, typing a command, and then leaving the console
window running indefinitely. A Windows service, however,
runs in the background, can start at boot time
@@ -627,7 +627,7 @@
command-line tool <command>SC.EXE</command>. Much like
the <command>inetd</command> configuration line, you must
specify an exact invocation of <command>svnserve</command>
- for Windows to run at start-up time:</para>
+ for Windows to run at startup time:</para>
<screen>
C:\> sc create svn
@@ -637,31 +637,30 @@
start= auto
</screen>
- <para>This defines a new Windows service
- named <quote>svn</quote>, and which executes a
- particular <command>svnserve.exe</command> command when
- started (in this case, rooted
- at <filename>C:\repos</filename>.) There are a number of
- caveats in the prior example, however.</para>
+ <para>This defines a new Windows service named
+ <quote>svn,</quote> which executes a particular
+ <command>svnserve.exe</command> command when started (in
+ this case, rooted at <filename>C:\repos</filename>). There
+ are a number of caveats in the prior example,
+ however.</para>
<para>First, notice that the <command>svnserve.exe</command>
- program must always be invoked with
- the <option>--service</option> option. Any other options to
+ program must always be invoked with the
+ <option>--service</option> option. Any other options to
<command>svnserve</command> must then be specified on the
- same line, but you cannot add conflicting options such
- as <option>--daemon
- (-d)</option>, <option>--tunnel</option>, or <option>--inetd
- (-i)</option>. Options such as <option>-r</option>
- or <option>--listen-port</option> are fine, though. Second, be
- careful about spaces when invoking
- the <command>SC.EXE</command> command: the
- <literal>key= value</literal> patterns must have no
- spaces between <literal>key=</literal> and exactly one
- space before the <literal>value</literal>. Lastly, be
- careful about spaces in your command-line to be invoked. If
- a directory name contains spaces (or other characters that
- need escaping), place the entire inner value
- of <literal>binpath</literal> in double-quotes, by escaping
+ same line, but you cannot add conflicting options such as
+ <option>--daemon (-d)</option>, <option>--tunnel</option>,
+ or <option>--inetd (-i)</option>. Options such as
+ <option>-r</option> or <option>--listen-port</option> are
+ fine, though. Second, be careful about spaces when invoking
+ the <command>SC.EXE</command> command: the <literal>key=
+ value</literal> patterns must have no spaces between
+ <literal>key=</literal> and must have exactly one space
+ before the <literal>value</literal>. Lastly, be careful
+ about spaces in your command line to be invoked. If a
+ directory name contains spaces (or other characters that
+ need escaping), place the entire inner value of
+ <literal>binpath</literal> in double quotes, by escaping
them:</para>
<screen>
@@ -675,24 +674,24 @@
<para>Also note that the word <literal>binpath</literal> is
misleading—its value is a <emphasis>command
line</emphasis>, not the path to an executable. That's why
- you need to surround it with quote marks if it contains
+ you need to surround it with quotes if it contains
embedded spaces.</para>
- <para>Once the service is defined, it can stopped, started, or
- queried using standard GUI tools (the Services
- administrative control panel), or at the command line as
- well:</para>
+ <para>Once the service is defined, it can be stopped, started,
+ or queried using standard GUI tools (the Services
+ administrative control panel), or at the command
+ line:</para>
<screen>
C:\> net stop svn
C:\> net start svn
</screen>
- <para>The service can also be uninstalled (i.e. undefined) by
- deleting its definition: <literal>sc delete svn</literal>.
+ <para>The service can also be uninstalled (i.e., undefined) by
+ deleting its definition: <userinput>sc delete svn</userinput>.
Just be sure to stop the service first!
The <command>SC.EXE</command> program has many other
- subcommands and options; run <literal>sc /?</literal> to
+ subcommands and options; run <userinput>sc /?</userinput> to
learn more about it.</para>
</sect3>
@@ -701,7 +700,7 @@
<!-- =============================================================== -->
<sect2 id="svn.serverconfig.svnserve.auth">
- <title>Built-in authentication and authorization</title>
+ <title>Built-in Authentication and Authorization</title>
<para>When a client connects to an <command>svnserve</command>
process, the following things happen:</para>
@@ -711,24 +710,24 @@
repository.</para></listitem>
<listitem><para>The server processes the repository's
- <filename>conf/svnserve.conf</filename> file, and begins to
+ <filename>conf/svnserve.conf</filename> file and begins to
enforce any authentication and authorization policies it
describes.</para></listitem>
- <listitem><para>Depending on the defined policies,</para>
+ <listitem><para>Depending on the defined policies, one of the
+ following may occur:</para>
<itemizedlist>
- <listitem><para>the client may be allowed to make requests
+ <listitem><para>The client may be allowed to make requests
anonymously, without ever receiving an authentication
- challenge, OR</para></listitem>
+ challenge.</para></listitem>
- <listitem><para>the client may be challenged for
- authentication at any time, OR</para></listitem>
+ <listitem><para>The client may be challenged for
+ authentication at any time.</para></listitem>
- <listitem><para>if operating in <quote>tunnel
- mode</quote>, the client will declare itself to be
- already externally authenticated (typically by
- SSH).</para></listitem>
+ <listitem><para>If operating in tunnel mode, the client
+ will declare itself to be already externally
+ authenticated (typically by SSH).</para></listitem>
</itemizedlist>
</listitem>
@@ -738,51 +737,53 @@
only how to send a CRAM-MD5
<footnote>
<para>See RFC 2195.</para>
- </footnote>
+ </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
- a response. The server performs the same computation with the
- stored password to verify that the result is
- identical. <emphasis>At no point does the actual password
- travel over the network.</emphasis></para>
+ the data and password combined, and then sends the fingerprint
+ as a response. The server performs the same computation with
+ the stored password to verify that the result is identical.
+ <emphasis>At no point does the actual password travel over the
+ network.</emphasis></para>
<para>If your <command>svnserve</command> server was built with
- SASL, then it not only knows how to send CRAM-MD5 challenges,
- but likely knows a whole host of other authentication
- mechanisms. See
- <xref linkend="svn.serverconfig.svnserve.sasl"/> to configure
- SASL authentication and encryption.</para>
+ SASL support, it not only knows how to send CRAM-MD5 challenges,
+ but also likely knows a whole host of other authentication
+ mechanisms. See <xref
+ linkend="svn.serverconfig.svnserve.sasl"/> later in this
+ chapter to learn how to configure SASL authentication and
+ encryption.</para>
<para>It's also possible, of course, for the client to be
externally authenticated via a tunnel agent, such as
- <command>SSH</command>. In that case, the server simply
- examines the user it's running as, and uses it as the
- authenticated username. For more on this, see <xref
+ <command>ssh</command>. In that case, the server simply
+ examines the user it's running as, and uses this name as the
+ authenticated username. For more on this, see the later
+ section, <xref
linkend="svn.serverconfig.svnserve.sshauth"/>.</para>
<para>As you've already guessed, a repository's
<filename>svnserve.conf</filename> file is the central
mechanism for controlling authentication and authorization
policies. The file has the same format as other configuration
- files (see <xref linkend="svn.advanced.confarea"/>): section names
- are marked by square brackets (<literal>[</literal> and
- <literal>]</literal>), comments begin with hashes
- (<literal>#</literal>), and each section contains
- specific variables that can be set (<literal>variable =
- value</literal>). Let's walk through these files and learn how
- to use them.</para>
+ files (see <xref linkend="svn.advanced.confarea"/>):
+ section names are marked by square brackets
+ (<literal>[</literal> and <literal>]</literal>), comments
+ begin with hashes (<literal>#</literal>), and each section
+ contains specific variables that can be set (<literal>variable
+ = value</literal>). Let's walk through these files and learn
+ how to use them.</para>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.svnserve.auth.users">
- <title>Create a 'users' file and realm</title>
+ <title>Create a users file and realm</title>
- <para>For now, the <literal>[general]</literal> section of the
+ <para>For now, the <literal>[general]</literal> section of
<filename>svnserve.conf</filename> has all the variables you
need. Begin by changing the values of those variables:
- choose a name for a file which will contain your usernames
- and passwords, and choose an authentication realm:</para>
+ choose a name for a file that will contain your usernames
+ and passwords and choose an authentication realm:</para>
<screen>
[general]
@@ -793,7 +794,7 @@
<para>The <literal>realm</literal> is a name that you define.
It tells clients which sort of <quote>authentication
namespace</quote> they're connecting to; the Subversion
- client displays it in the authentication prompt, and uses it
+ client displays it in the authentication prompt and uses it
as a key (along with the server's hostname and port) for
caching credentials on disk (see <xref
linkend="svn.serverconfig.netmodel.credcache"/>). The
@@ -820,7 +821,7 @@
authentication realm. Wherever the file lives, be sure to
set the file's read and write permissions appropriately. If
you know which user(s) <command>svnserve</command> will run
- as, restrict read access to the user file as necessary.</para>
+ as, restrict read access to the users file as necessary.</para>
</sect3>
@@ -832,7 +833,7 @@
<filename>svnserve.conf</filename> file: they determine what
unauthenticated (anonymous) and authenticated users are
allowed to do. The variables <literal>anon-access</literal>
- and <literal>auth-access</literal> can be set to the values
+ and <literal>auth-access</literal> can be set to the value
<literal>none</literal>, <literal>read</literal>, or
<literal>write</literal>. Setting the value to
<literal>none</literal> prohibits both reading and writing;
@@ -869,7 +870,7 @@
auth-access = write
</screen>
- <para>The server process not only understands
+ <para>The server process understands not only
these <quote>blanket</quote> access controls to the
repository, but also finer-grained access restrictions placed
on specific files and directories within the repository. To
@@ -886,13 +887,13 @@
authz-db = authzfile
</screen>
- <para>The syntax of the <filename>authzfile</filename> file is
- discussed in detail in
+ <para>We discuss the syntax of the <filename>authzfile</filename> file
+ in detail later in this chapter, in
<xref linkend="svn.serverconfig.pathbasedauthz"/>. Note
that the <literal>authz-db</literal> variable isn't mutually
exclusive with the <literal>anon-access</literal>
and <literal>auth-access</literal> variables; if all the
- variables are defined at once, then <emphasis>all</emphasis>
+ variables are defined at once, <emphasis>all</emphasis>
of the rules must be satisfied before access is allowed.</para>
</sect3>
@@ -906,7 +907,7 @@
all they need from <command>svnserve</command>. However, if
your server (and your Subversion clients) were built with the
Cyrus Simple Authentication and Security Layer (SASL) library,
- then you have a number of authentication and encryption
+ you have a number of authentication and encryption
options available to you.</para>
<sidebar>
@@ -948,7 +949,7 @@
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
+ and client were linked against SASL, 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>
@@ -993,7 +994,7 @@
<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
+ beyond the scope of this book) to try to 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
@@ -1012,7 +1013,7 @@
mech_list: DIGEST-MD5
</screen>
- <para>then you've told SASL to advertise the DIGEST-MD5
+ <para>you've told SASL to advertise the DIGEST-MD5
mechanism to clients and to check user passwords against a
private password database located
at <filename>/etc/my_sasldb</filename>. A system
@@ -1024,7 +1025,7 @@
$ saslpasswd2 -c -f /etc/my_sasldb -u realm username
</screen>
- <para>A few words of warning: first, make sure that the
+ <para>A few words of warning: first, make sure the
<quote>realm</quote> argument
to <command>saslpasswd2</command> matches the same realm
you've defined in your
@@ -1032,7 +1033,7 @@
they don't match, authentication will fail. Also, due to a
shortcoming in SASL, the common realm must be a string with
no space characters. Finally, if you decide to go with the
- standard SASL password database, make sure that
+ standard SASL password database, make sure
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>
@@ -1049,7 +1050,7 @@
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 may be exactly what you
- want (<quote>my clients must all use Kerberos!</quote>).
+ want (<quote>My clients must all use Kerberos!</quote>).
However, if you still want non-SASL clients to be able to
authenticate, be sure to advertise the CRAM-MD5 mechanism as
an option. All clients are able to use CRAM-MD5, whether
@@ -1083,7 +1084,7 @@
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
+ the maximum value to some bit length. To require encryption
unconditionally, set both values to numbers greater than 1.
In our previous example, we require clients to do at least
128-bit encryption, but no more than 256-bit
@@ -1171,23 +1172,28 @@
place them into a common group, and you'll need to be careful
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>
+ chapter). But even in the case of tunneling, you can still use the
+ <filename>svnserve.conf</filename> file 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 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
+ <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>
@@ -1200,11 +1206,11 @@
URL scheme that matches the name of your new variable:
<literal>svn+rsh://host/path</literal>. When using the new
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,
+ command <userinput>rsh host svnserve -t</userinput> behind the
+ scenes. If you include a username in the URL (e.g.,
<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
+ will also include that in its command (<userinput>rsh
+ username at host svnserve -t</userinput>). But you can define new
tunneling schemes to be much more clever than that:</para>
<screen>
@@ -1216,7 +1222,7 @@
shows how to make the Subversion client launch a very specific
tunneling binary (the one located at
<filename>/opt/alternate/ssh</filename>) with specific
- options. In this case, accessing a
+ options. In this case, accessing an
<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
@@ -1233,8 +1239,8 @@
the <literal>JOESSH</literal> environment variable, its value
would override the entire value of the tunnel
variable—<command>$JOESSH</command> would be executed
- instead of <command>/opt/alternate/ssh -p
- 29934</command>.</para>
+ instead of <userinput>/opt/alternate/ssh -p
+ 29934</userinput>.</para>
</sect2>
@@ -1242,7 +1248,7 @@
<sect2 id="svn.serverconfig.svnserve.sshtricks">
<title>SSH configuration tricks</title>
- <para>It's not only possible to control the way in which the
+ <para>It's possible to control not only the way in which the
client invokes <command>ssh</command>, but also to control
the behavior of <command>sshd</command> on your server
machine. In this section, we'll show how to control the
@@ -1285,7 +1291,7 @@
<para>When the <literal>command</literal> field is set, the
SSH daemon will run the named program instead of the
- typical <command>svnserve -t</command> invocation that the
+ typical tunnel-mode <command>svnserve</command> invocation that the
Subversion client asks for. This opens the door to a number
of server-side tricks. In the following examples, we
abbreviate the lines of the file as:</para>
@@ -1322,7 +1328,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 key-pair 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>
@@ -1334,10 +1340,10 @@
</screen>
<para>This example allows both Harry and Sally to connect to
- the same account via public-key authentication. Each of
+ the same account via public key authentication. Each of
them has a custom command that will be executed;
the <option>--tunnel-user</option> option
- tells <command>svnserve -t</command> to assume that the named
+ tells <command>svnserve</command> to assume that the named
argument is the authenticated user. Without
<option>--tunnel-user</option>, it would appear as though
all commits were coming from the one shared system
@@ -1349,27 +1355,22 @@
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
- perform X11 or general port-forwarding through your server.
+ 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
after the <literal>command</literal>:</para>
<screen>
- command="svnserve -t --tunnel-user=harry",no-port-forwarding,
- no-agent-forwarding,no-X11-forwarding,no-pty TYPE1 KEY1 harry at example.com
+ command="svnserve -t --tunnel-user=harry",no-port-forwarding,no-agent-forw
+arding,no-X11-forwarding,no-pty TYPE1 KEY1 harry at example.com
</screen>
- <para>(Note that this all must be on one line—truly on
- one line, since SSH <filename>authorized_keys</filename> files
- do not even allow the
- conventional <quote><literal>\</literal></quote> for line
- continuation. Thus, there should be no line break and no
- space
- between <quote><literal>no-port-forwarding,</literal></quote>
- and
- <quote><literal>no-agent-forwarding,</literal></quote> in the
- example above; the only reason we've formatted it with a line
- break is to fit it on the physical page of a book.)</para>
+ <para>Note that this all must be on one line—truly on
+ one line—since SSH <filename>authorized_keys</filename>
+ files do not even allow the conventional backslash character
+ (<literal>\</literal>) for line continuation. The only
+ reason we've formatted it with a line break is to fit it on
+ the physical page of a book.</para>
</sect3>
@@ -1385,7 +1386,7 @@
<title>httpd, the Apache HTTP Server</title>
- <para>The Apache HTTP Server is a <quote>heavy duty</quote>
+ <para>The Apache HTTP Server is a <quote>heavy-duty</quote>
network server that Subversion can leverage. Via a custom
module, <command>httpd</command> makes Subversion repositories
available to clients via the WebDAV/DeltaV protocol, which is an
@@ -1397,9 +1398,11 @@
robust system that is conveniently packaged as part of the
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>
@@ -1431,13 +1434,13 @@
<para>If you're a system administrator, it's very likely that
you're already running the Apache web server and have some
- prior experience with it. At the time of writing, Apache 1.3
- is by far the most popular version of Apache. The world has
- been somewhat slow to upgrade to the Apache 2.X series for
+ prior experience with it. At the time of this writing, Apache 1.3
+ is the more popular version of Apache. The world has
+ 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 work only against the Apache 1.3 API, and
- they are waiting for a 2.X port. Whatever the reason, many
+ 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>
@@ -1474,7 +1477,7 @@
the <command>mod_dav</command> module</para>
</listitem>
<listitem>
- <para>Installing the <command>mod_dav_svn</command> back end
+ <para>Installing the <command>mod_dav_svn</command> backend
to <command>mod_dav</command>, which uses Subversion's
libraries to access the repository</para>
</listitem>
@@ -1586,8 +1589,7 @@
are actually Subversion repositories. This is a particularly
convenient syntax in that, unlike the use of the
<literal>SVNPath</literal> directive, you don't have to
- restart Apache in order to create and network new
- repositories.</para>
+ restart Apache to create and network new repositories.</para>
<para>Be sure that when you define your new
<literal>Location</literal>, it doesn't overlap with other
@@ -1625,7 +1627,7 @@
<para>If you are using Apache's virtual hosting support via
the <literal>NameVirtualHost</literal> directive, you may
need to use the <literal>ServerAlias</literal> directive to
- specify additional names that your server is known by.
+ specify additional names by which your server is known.
Again, refer to the Apache documentation for full
details.</para>
</sidebar>
@@ -1664,7 +1666,7 @@
<title>Authentication Options</title>
<para>At this point, if you configured
- <filename>httpd.conf</filename> to contain something like the
+ <filename>httpd.conf</filename> to contain something such as the
following:</para>
<screen>
@@ -1674,7 +1676,7 @@
</Location>
</screen>
- <para>then your repository is <quote>anonymously</quote>
+ <para>your repository is <quote>anonymously</quote>
accessible to the world. Until you configure some
authentication and authorization policies, the Subversion
repositories that you make available via the
@@ -1700,7 +1702,7 @@
<para>Of course, you might have already set up
a <filename>pre-commit</filename> hook script to prevent
commits (see <xref linkend="svn.reposadmin.create.hooks"/>).
- But as you read on, you'll see that it's also possible use
+ But as you read on, you'll see that it's also possible to use
Apache's built-in methods to restrict access in specific
ways.</para>
@@ -1741,7 +1743,7 @@
<literal>AuthName</literal> is an arbitrary name that you
give for the authentication domain. Most browsers will
display this name in the pop-up dialog box when the browser
- is querying the user for his name and password. Finally,
+ is querying the user for her name and password. Finally,
use the <literal>AuthUserFile</literal> directive to specify
the location of the password file you created using
<command>htpasswd</command>.</para>
@@ -1789,10 +1791,10 @@
authorization policies.</para>
<para>One word of warning: HTTP Basic Auth passwords pass in
- very nearly plain-text over the network, and thus are
+ very nearly plain text over the network, and thus are
extremely insecure.</para>
- <para>Another option is to not use Basic authentication but to
+ <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
@@ -1802,7 +1804,7 @@
function to a one-time bit of information. The server sends
a small random-ish string to the client; the client uses the
user's password to hash the string; the server then looks to
- see if the hashed value is what it expected.</para>
+ see whether the hashed value is what it expected.</para>
<para>Configuring Apache for Digest authentication is also
fairly easy, and only a small variation on our prior
@@ -1821,7 +1823,7 @@
</Location>
</screen>
- <para>If you're looking for maximum security, then public-key
+ <para>If you're looking for maximum security, public key
cryptography is the best solution. It may be best to use
some sort of SSL encryption, so that clients authenticate
via <literal>https://</literal> instead
@@ -1851,7 +1853,7 @@
that kind of unwanted attention less likely to result in
sensitive data leaks.</para>
- <para>If a Subversion client is compiled to use OpenSSL, then
+ <para>If a Subversion client is compiled to use OpenSSL,
it gains the ability to speak to an Apache server via
<literal>https://</literal> URLs. The Neon library used by
the Subversion client is not only able to verify server
@@ -1863,8 +1865,8 @@
<para>It's beyond the scope of this book to describe 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
+ Apache's own documentation, describe this task. But what we
+ <emphasis>can</emphasis> cover here is how to manage
server and client certificates from an ordinary Subversion
client.</para>
@@ -1881,7 +1883,7 @@
verify that it trusts the certificate: is the server really
who it claims to be? The OpenSSL library does this by
examining the signer of the server certificate, or
- <firstterm>certifying authority</firstterm> (CA). If
+ <firstterm>certificate authority</firstterm> (CA). If
OpenSSL is unable to automatically trust the CA, or if some
other problem occurs (such as an expired certificate or
hostname mismatch), the Subversion command-line client will
@@ -1906,7 +1908,7 @@
<para>This dialogue should look familiar; it's essentially the
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
+ If you choose the <literal>(p)</literal>ermanent option, the server certificate
will be cached in your private runtime
<filename>auth/</filename> area in just the same way your
username and password are cached (see <xref
@@ -1941,7 +1943,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 for the password that
+ a path to the certificate and the password that
protects it:</para>
<screen>
@@ -2137,7 +2139,7 @@
<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>
+ <title>A sample configuration for anonymous access</title>
<programlisting>
<Location /repos>
DAV svn
@@ -2158,7 +2160,7 @@
<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>
+ <title>A sample configuration for authenticated access</title>
<programlisting>
<Location /repos>
DAV svn
@@ -2218,8 +2220,8 @@
<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 later in
- this chapter in
+ paths within the repository. We describe this later in
+ this chapter, in
<xref linkend="svn.serverconfig.pathbasedauthz"/>.</para>
</sect3>
@@ -2231,14 +2233,14 @@
<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
+ This means it needs to closely monitor all of the paths
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
+ checkout</command> and <command>svn update</command>.
+ If these commands encounter a path that isn't
+ readable according to some authorization policy, the
path is typically omitted altogether. In the case of
- history or rename tracing—e.g., running a command such
- as <command>svn cat -r OLD foo.c</command> on a file that
+ history or rename tracing—for example, running a command such
+ as <userinput>svn cat -r OLD foo.c</userinput> 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>
@@ -2248,7 +2250,7 @@
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
+ discovered, 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
@@ -2267,7 +2269,7 @@
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
- <command>mod_authz_svn</command> or similar module), then
+ <command>mod_authz_svn</command> or similar module),
you can disable all of this path checking. In your
<filename>httpd.conf</filename> file, use the
<literal>SVNPathAuthz</literal> directive as shown in
@@ -2288,7 +2290,7 @@
<para>The <literal>SVNPathAuthz</literal> directive
is <quote>on</quote> by default. When
- set <quote>off,</quote> all path-based authorization
+ set to <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>
@@ -2351,7 +2353,7 @@
PROPFIND requests and understanding DeltaV concepts. This
is something your web browser simply can't do.</para>
- <para>So to answer the question, one obvious way to see
+ <para>So, to answer the question, one obvious way to see
older revisions of files and directories is by passing the
<option>--revision</option> (<option>-r</option>) argument
to the <command>svn list</command> and <command>svn
@@ -2361,7 +2363,7 @@
url="http://viewvc.tigris.org/"/>). ViewVC was originally
written to display CVS repositories through the Web,
<footnote>
- <para>Back then, it was called <quote>ViewCVS</quote>.</para>
+ <para>Back then, it was called ViewCVS.</para>
</footnote>
and the latest releases are able to understand Subversion
repositories as well.</para>
@@ -2387,8 +2389,8 @@
<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
+ proper <literal>svn:mime-type</literal> set. We discuss this
+ 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
@@ -2398,10 +2400,10 @@
<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
+ file <filename>foo.html</filename>, 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 image files and ultimately get an
+ 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
@@ -2446,7 +2448,7 @@
Keep in mind that the path provided to the
<literal>SVNIndexXSLT</literal> directory is actually a URL
path—browsers need to be able to read your
- stylesheets in order to make use of them!</para>
+ stylesheets to make use of them!</para>
</sect4>
@@ -2486,7 +2488,7 @@
<para>Because Apache is an HTTP server at heart, it contains
fantastically flexible logging features. It's beyond the
- scope of this book to discuss all ways logging can be
+ scope of this book to discuss all of the ways logging can be
configured, but we should point out that even the most
generic <filename>httpd.conf</filename> file will cause
Apache to produce two logs:
@@ -2528,7 +2530,7 @@
Apache's <literal>CustomLog</literal> directive (which is
explained in more detail in Apache's own documentation).
Be sure to invoke this
- directive <emphasis>outside</emphasis> of your
+ directive <emphasis>outside</emphasis> your
Subversion <literal>Location</literal> block:</para>
<screen>
@@ -2541,18 +2543,18 @@
</screen>
<para>In this example, we're asking Apache to create a special
- logfile <filename>svn_logfile</filename> in the standard
+ logfile, <filename>svn_logfile</filename>, in the standard
Apache <filename>logs</filename> directory.
The <literal>%t</literal> and <literal>%u</literal>
variables are replaced by the time and username of the
- request, respectively. The really important part are the
+ request, respectively. The really important parts are the
two instances of <literal>SVN-ACTION</literal>.
When Apache sees that variable, it substitutes the value of
the <literal>SVN-ACTION</literal> environment variable,
which is automatically set by <command>mod_dav_svn</command>
whenever it detects a high-level client action.</para>
- <para>So instead of having to interpret a
+ <para>So, instead of having to interpret a
traditional <filename>access_log</filename> like
this:</para>
@@ -2566,7 +2568,7 @@
…
</screen>
- <para>you can instead peruse a much more
+ <para>you can peruse a much more
intelligible <filename>svn_logfile</filename> like
this:</para>
@@ -2590,7 +2592,7 @@
Subversion server is that it can be set up for simple
replication. For example, suppose that your team is
distributed across four offices around the globe. The
- Subversion repository can only exist in one of those
+ Subversion repository can exist only in one of those
offices, which means the other three offices will not enjoy
accessing it—they're likely to experience
significantly slower traffic and response times when
@@ -2598,7 +2600,7 @@
up a system consisting of one <firstterm>master</firstterm>
Apache server and several <firstterm>slave</firstterm>
Apache servers. If you place a slave server in each office,
- then users can check out a working copy from whichever slave
+ users can check out a working copy from whichever slave
is closest to them. All read requests go to their local
slave. Write requests get automatically routed to the
single master server. When the commit completes, the master
@@ -2613,7 +2615,7 @@
server, it's a huge win.</para>
<para>In this section, we'll walk you through a standard setup
- of this single-master/multiple slave system. However, keep
+ of this single-master/multiple-slave system. However, keep
in mind that your servers must be running at least Apache
2.2.0 (with <command>mod_proxy</command> loaded) and
Subversion 1.5 (<command>mod_dav_svn</command>).</para>
@@ -2698,7 +2700,7 @@
standard procedure for being on the receiving end of
<command>svnsync</command>.) Then log into the master
server and configure each of the slave repository URIs to
- receive data from the master repository on local
+ receive data from the master repository on the local
disk:</para>
<screen>
@@ -2754,11 +2756,11 @@
<para>The extra bits on the end of each line aren't
necessary, but they're a sneaky way to allow the sync
- commands to run in the background, so that the Subversion
+ commands to run in the background so that the Subversion
client isn't left waiting forever for the commit to
finish. In addition to this
<filename>post-commit</filename> hook, you'll need a
- <filename>post-revprop-change</filename> hook as well, so
+ <filename>post-revprop-change</filename> hook as well so
that when a user, say, modifies a log message, the slave
servers get that change also:</para>
@@ -2780,7 +2782,7 @@
nonissue for you. However, if lock changes aren't
replicated from master to slaves, it means that clients
won't be able to query the status of locks
- (e.g., <command>svn status -u</command> will show no
+ (e.g., <userinput>svn status -u</userinput> will show no
information about repository locks). If this bothers you,
you can write <filename>post-lock</filename> and
<filename>post-unlock</filename> hook scripts that run
@@ -2795,7 +2797,7 @@
<title>Caveats</title>
<para>Your master/slave replication system should now be
- ready to use. A couple words of warning are in order,
+ ready to use. A couple of words of warning are in order,
however. Remember that this replication isn't entirely
robust in the face of computer or network crashes. For
example, if one of the automated
@@ -2803,7 +2805,7 @@
some reason, the slaves will begin to fall behind. For
example, your remote users will see that they've committed
revision 100, but then when they run <command>svn
- update</command>, their local server will tell them than
+ update</command>, their local server will tell them that
revision 100 doesn't yet exist! Of course, the problem
will be automatically fixed the next time another commit
happens and the subsequent <command>svnsync</command> is
@@ -2814,15 +2816,14 @@
wrong.</para>
<sidebar>
- <title>Can We Set up Replication with
- <command>svnserve</command>?</title>
+ <title>Can We Set Up Replication with svnserve?</title>
<para>If you're using <command>svnserve</command> instead
of Apache as your server, you can certainly configure
your repository's hook scripts to invoke
<command>svnsync</command> as we've shown here, thereby
causing automatic replication from master to slaves.
- Unfortunately, at the time of writing there is no way to
+ Unfortunately, at the time of this writing there is no way to
make slave <command>svnserve</command> servers
automatically proxy write requests back to the master
server. This means your users would only be able to
@@ -2844,9 +2845,9 @@
<para>Several of the features already provided by Apache in
its role as a robust web server can be leveraged for
increased functionality or security in Subversion as well.
- The Subversion client is able to use SSL (the Secure Socket
+ The Subversion client is able to use SSL (the Secure Sockets
Layer, discussed earlier). If your Subversion client is
- built to support SSL, then it can access your Apache server
+ built to support SSL, it can access your Apache server
using <literal>https://</literal> and enjoy a high-quality
encrypted network session.</para>
@@ -2866,7 +2867,7 @@
complicated topic, but also wondrous when implemented. For
details, read <xref linkend="svn.webdav"/>.</para>
- <para>Note that there are number of other small tweaks one can
+ <para>Note that there are a number of other small tweaks one can
make to <command>mod_dav_svn</command> that are too obscure
to mention in this chapter. For a complete list of
all <filename>httpd.conf</filename> directives
@@ -2903,13 +2904,13 @@
the <filename>httpd.conf</filename> file) pointing to your own
rules file. (For a full explanation, see
<xref linkend="svn.serverconfig.httpd.authz.perdir"/>.) If
- you're using <command>svnserve</command>, then you need to make
+ you're using <command>svnserve</command>, you need to make
the <literal>authz-db</literal> variable
(within <filename>svnserve.conf</filename>) point to your
rules file.</para>
<sidebar>
- <title>Do You Really Need Path-based Access Control?</title>
+ <title>Do You Really Need Path-Based Access Control?</title>
<para>A lot of administrators setting up Subversion for the
first time tend to jump into path-based access control without
@@ -2940,17 +2941,17 @@
maintain.</para>
<para>Remember that this is a version control system! Even if
- somebody accidentally commits a change to something they
+ somebody accidentally commits a change to something she
shouldn't, it's easy to undo the change. And if a user
- commits to the wrong place with deliberate malice, then it's a
+ commits to the wrong place with deliberate malice, it's a
social problem anyway, and that the problem needs to be dealt
- with outside of Subversion.</para>
+ with outside Subversion.</para>
- <para>So before you begin restricting users' access rights, ask
- yourself if there's a real, honest need for this, or if it's
+ <para>So, before you begin restricting users' access rights, ask
+ yourself whether there's a real, honest need for this, or whether it's
just something that <quote>sounds good</quote> to an
administrator. Decide whether it's worth sacrificing some
- server speed for, and remember that there's very little risk
+ server speed, and remember that there's very little risk
involved; it's bad to become dependent on technology as a
crutch for social problems.
<footnote>
@@ -2974,7 +2975,7 @@
time to define the rules.</para>
<para>The syntax of the file is the same familiar one used
- by <command>svnserve.conf</command> and the runtime
+ by <filename>svnserve.conf</filename> and the runtime
configuration files. Lines that start with a hash
(<literal>#</literal>) are ignored. In its simplest form, each
section names a repository and path within it, as well as the
@@ -2982,19 +2983,19 @@
section. The value of each option describes the user's level of
access to the repository path: either
<literal>r</literal> (read-only) or <literal>rw</literal>
- (read-write). If the user is not mentioned at all, no access is
+ (read/write). If the user is not mentioned at all, no access is
allowed.</para>
- <para>To be more specific: the value of the section names are
- either of the form <literal>[repos-name:path]</literal> or the
+ <para>To be more specific: the value of the section names is
+ either of the form <literal>[repos-name:path]</literal> or of the
form <literal>[path]</literal>. If you're using the
- <literal>SVNParentPath</literal> directive, then it's important
+ <literal>SVNParentPath</literal> directive, it's important
to specify the repository names in your sections. If you omit
- them, then a section such as
+ them, a section such as
<literal>[/some/dir]</literal> will match the path
<filename>/some/dir</filename> in <emphasis>every</emphasis>
repository. If you're using the <literal>SVNPath</literal>
- directive, however, then it's fine to only define paths in your
+ directive, however, it's fine to only define paths in your
sections—after all, there's only one repository.</para>
<screen>
@@ -3011,7 +3012,7 @@
are blocked from accessing this directory.</para>
<para>Of course, permissions are inherited from parent to child
- directory. That means that we can specify a subdirectory with a
+ directory. That means we can specify a subdirectory with a
different access policy for Sally:</para>
<screen>
@@ -3026,7 +3027,7 @@
<para>Now Sally can write to the <filename>testing</filename>
subdirectory of the branch, but can still only read other parts.
- Harry, meanwhile, continues to have complete read-write access
+ Harry, meanwhile, continues to have complete read/write access
to the whole branch.</para>
<para>It's also possible to explicitly deny permission to someone
@@ -3042,7 +3043,7 @@
harry =
</screen>
- <para>In this example, Harry has read-write access to the
+ <para>In this example, Harry has read/write access to the
entire <filename>bug-142</filename> tree, but has absolutely no
access at all to the <filename>secret</filename> subdirectory
within it.</para>
@@ -3052,7 +3053,7 @@
always matches first. The server tries to match the path
itself, and then the parent of the path, then the parent of
that, and so on. The net effect is that mentioning a specific
- path in the accessfile will always override any permissions
+ path in the access file will always override any permissions
inherited from parent directories.</para>
</tip>
@@ -3068,9 +3069,9 @@
* = r
</screen>
- <para>This is a common setup; notice that there's no repository
- name mentioned in the section name. This makes all repositories
- world-readable to all users. Once all users have read-access to
+ <para>This is a common setup; notice that no repository
+ name is mentioned in the section name. This makes all repositories
+ world-readable to all users. Once all users have read access to
the repositories, you can give explicit
<literal>rw</literal> permission to certain users on specific
subdirectories within specific repositories.</para>
@@ -3082,7 +3083,7 @@
of anonymous and authenticated access, all users start out
accessing anonymously. The server looks for a
<literal>*</literal> value defined for the path being accessed;
- if it can't find one, then it demands real authentication from
+ if it can't find one, it demands real authentication from
the client.</para>
<para>The access file also allows you to define whole groups of
@@ -3113,7 +3114,7 @@
the <emphasis>first</emphasis> matching rule is the one which gets
applied to a user. In the prior example, even though Jane is a
member of the <literal>paint-developers</literal> group (which has
- read-write access), the <literal>jane = r</literal> rule will be
+ read/write access), the <literal>jane = r</literal> rule will be
discovered and matched before the group rule, thus denying Jane
write access.</para>
@@ -3126,15 +3127,58 @@
everyone = @calc-developers, @paint-developers
</screen>
- <!-- TODO(sussman): this sidebar needs to be changed for svn 1.5,
- making it clear that it's a neon behavior, and ??probably?? not the
- case when using serf... -->
+ <para>Subversion 1.5 brings another useful feature to the access
+ file syntax: username aliases. Some authentication systems
+ expect and carry relatively short usernames of the sorts we've
+ been describing here—<literal>harry</literal>,
+ <literal>sally</literal>, <literal>joe</literal>, and so on. But
+ other authentication systems—such as those which use LDAP
+ stores or SSL client certificates—may carry much more
+ complex usernames. For example, Harry's username in an
+ LDAP-protected system might be <literal>CN=Harold
+ Hacker,OU=Engineers,DC=red-bean,DC=com</literal>. With
+ usernames like that, the access file can become quite bloated
+ with long or obscure usernames that are easy to mistype.
+ Fortunately, username aliases allow you to have to type the
+ correct complex username only once, in a statement which assigns to
+ it a more easily digestable alias.</para>
+
+ <screen>
+[aliases]
+harry = CN=Harold Hacker,OU=Engineers,DC=red-bean,DC=com
+sally = CN=Sally Swatterbug,OU=Engineers,DC=red-bean,DC=com
+joe = CN=Gerald I. Joseph,OU=Engineers,DC=red-bean,DC=com
+…
+</screen>
+
+ <para>Once you've defined a set of aliases, you can refer to the
+ users elsewhere in the access file via their aliases in all the
+ same places you could have instead used their actual usernames.
+ Simply prepend an ampersand to the alias to distinguish it from
+ a regular username:</para>
+
+ <screen>
+[groups]
+calc-developers = &harry, &sally, &joe
+paint-developers = &frank, &sally, &jane
+everyone = @calc-developers, @paint-developers
+</screen>
+
+ <para>You might also choose to use aliases if your users'
+ usernames change frequently. Doing so allows you to need to
+ update only the aliases table when these username changes occur,
+ instead of doing global-search-and-replace operations on the
+ whole access file.</para>
+
+ <!-- TODO(sussman): Once serf becomes officially support, this
+ sidebar will need to be revisited. -->
+
<sidebar>
<title>Partial Readability and Checkouts</title>
<para>If you're using Apache as your Subversion server and have
made certain subdirectories of your repository unreadable to
- certain users, then you need to be aware of a possible
+ certain users, you need to be aware of a possible
nonoptimal behavior with <command>svn checkout</command>.</para>
<para>When the client requests a checkout or update over HTTP, it
@@ -3142,16 +3186,16 @@
large) server response. When the server receives the request,
that is the <emphasis>only</emphasis> opportunity Apache has to
demand user authentication. This has some odd side effects.
- For example, if a certain subdirectory of the repository is only
- readable by user Sally, and user Harry checks out a parent
+ For example, if a certain subdirectory of the repository is
+ readable only by user Sally, and user Harry checks out a parent
directory, his client will respond to the initial authentication
challenge as Harry. As the server generates the large response,
- there's no way it can re-send an authentication challenge when
+ there's no way it can resend an authentication challenge when
it reaches the special subdirectory; thus the subdirectory is
skipped altogether, rather than asking the user to
- re-authenticate as Sally at the right moment. In a similar way,
+ reauthenticate as Sally at the right moment. In a similar way,
if the root of the repository is anonymously world-readable,
- then the entire checkout will be done without
+ the entire checkout will be done without
authentication—again, skipping the unreadable directory,
rather than asking for authentication partway through.</para>
</sidebar>
@@ -3198,7 +3242,7 @@
<para>The most common problem administrators run into is
repository ownership and permissions. Does every process (or
- user) in the previous list have the rights to read and write the
+ user) in the preceding list have the rights to read and write the
repository's underlying data files? Assuming you have a
Unix-like operating system, a straightforward approach might be
to place every potential repository user into a
@@ -3211,11 +3255,11 @@
repository users is to force every repository-accessing process
to use a sane umask. For users accessing the repository
directly, you can make the <command>svn</command> program into a
- wrapper script that first sets <command>umask 002</command> and
+ wrapper script that first runs <userinput>umask 002</userinput> and
then runs the real <command>svn</command> client program. You
can write a similar wrapper script for the
- <command>svnserve</command> program, and add a <command>umask
- 002</command> command to Apache's own startup script,
+ <command>svnserve</command> program, and add a <userinput>umask
+ 002</userinput> command to Apache's own startup script,
<filename>apachectl</filename>. For example:</para>
<screen>
@@ -3243,7 +3287,7 @@
<para>Once you've jumped through these hoops, your repository
should be accessible by all the necessary processes. It may
seem a bit messy and complicated, but the problems of having
- multiple users sharing write-access to common files are classic
+ multiple users sharing write access to common files are classic
ones that are not often elegantly solved.</para>
<para>Fortunately, most repository administrators will never
@@ -3253,10 +3297,10 @@
access URLs—they can typically contact the Apache HTTP
server or <command>svnserve</command> using
<literal>localhost</literal> for the server name in their
- <literal>http://</literal> or <literal>svn://</literal> URLs.
+ <literal>http://</literal> or <literal>svn://</literal> URL.
And maintaining multiple server processes for your Subversion
repositories is likely to be more of a headache than necessary.
- We recommend you choose a single server that best meets your
+ We recommend that you choose a single server that best meets your
needs and stick with it!</para>
<sidebar>
@@ -3266,7 +3310,7 @@
existing SSH accounts to share a repository without
permissions problems. If you're confused about all the things
that you (as an administrator) need to do on a Unix-like
- system, here's a quick checklist that resummarizes some of
+ system, here's a quick checklist that resummarizes some of the
topics discussed in this section:</para>
<itemizedlist>
@@ -3286,10 +3330,10 @@
</listitem>
<listitem>
<para>Your users need to use a sane umask when accessing the
- repository, so make sure that <command>svnserve</command>
+ repository, so make sure <command>svnserve</command>
(<filename>/usr/bin/svnserve</filename>, or wherever it
lives in <literal>$PATH</literal>) is actually a wrapper
- script that sets <command>umask 002</command> and
+ script that runs <userinput>umask 002</userinput> and
executes the real <command>svnserve</command>
binary.</para>
</listitem>
Modified: trunk/src/de/book/ch07-customizing-svn.xml
==============================================================================
--- trunk/src/de/book/ch07-customizing-svn.xml (original)
+++ trunk/src/de/book/ch07-customizing-svn.xml Tue Aug 12 11:40:38 2008
@@ -23,8 +23,8 @@
<sect1 id="svn.advanced.confarea">
<title>Runtime Configuration Area</title>
- <para>Subversion provides many optional behaviors that can be
- controlled by the user. Many of these options are of the kind
+ <para>Subversion provides many optional behaviors that the user can
+ control. Many of these options are of the kind
that a user would wish to apply to all Subversion operations.
So, rather than forcing users to remember command-line arguments
for specifying these options and to use them for every
@@ -36,9 +36,9 @@
Usually, this boils down to a special directory that contains
<firstterm>configuration files</firstterm> (the first tier),
which are just text files in standard INI format (with
- <quote>sections</quote> providing the second tier). These files
- can be easily edited using your favorite text editor (such as
- Emacs or vi), and that contain directives read by the client to
+ <quote>sections</quote> providing the second tier). You can
+ easily edit these files using your favorite text editor (such as
+ Emacs or vi), and they contain directives read by the client to
determine which of several optional behaviors the user
prefers.</para>
@@ -46,7 +46,7 @@
<sect2 id="svn.advanced.confarea.layout">
<title>Configuration Area Layout</title>
- <para>The first time that the <command>svn</command>
+ <para>The first time the <command>svn</command>
command-line client is executed, it creates a per-user
configuration area. On Unix-like systems, this area appears
as a directory named <filename>.subversion</filename> in the
@@ -56,7 +56,7 @@
profile directory (which, by the way, is usually a hidden
directory). However, on this platform, the exact location
differs from system to system and is dictated by the Windows
- registry.
+ Registry.
<footnote>
<para>The <literal>APPDATA</literal> environment variable
points to the <filename>Application Data</filename> area,
@@ -70,7 +70,7 @@
also recognizes the existence of a system-wide configuration
area. This gives system administrators the ability to
establish defaults for all users on a given machine. Note
- that the system-wide configuration area does not alone dictate
+ that the system-wide configuration area alone does not dictate
mandatory policy—the settings in the per-user
configuration area override those in the system-wide one, and
command-line arguments supplied to the <command>svn</command>
@@ -97,7 +97,7 @@
any time you wish to have the default configuration settings
restored, you can simply remove (or rename) your configuration
directory and then run some innocuous <command>svn</command>
- command, such as <command>svn --version</command>. A new
+ command, such as <userinput>svn --version</userinput>. A new
configuration directory with the default contents will be
created.</para>
@@ -117,12 +117,12 @@
<para>In addition to the usual INI-based configuration area,
Subversion clients running on Windows platforms may also use
- the Windows registry to hold the configuration data. The
+ the Windows Registry to hold the configuration data. The
option names and their values are the same as in the INI
files. The <quote>file/section</quote> hierarchy is
preserved as well, though addressed in a slightly different
fashion—in this schema, files and sections are just
- levels in the registry key tree.</para>
+ levels in the Registry key tree.</para>
<para>Subversion looks for system-wide configuration values
under the
@@ -137,7 +137,7 @@
<para>Registry-based configuration options are parsed
<emphasis>before</emphasis> their file-based counterparts, so
- are overridden by values found in the configuration files. In
+ they are overridden by values found in the configuration files. In
other words, Subversion looks for configuration information in
the following locations on a Windows system; lower-numbered
locations take precedence over higher-numbered locations:</para>
@@ -177,10 +177,10 @@
linkend="svn.advanced.confarea.windows-registry.ex-1" />), and
then double-click on that file's icon in the Explorer shell,
which will cause the data to be merged into your
- registry.</para>
+ Registry.</para>
<example id="svn.advanced.confarea.windows-registry.ex-1">
- <title>Sample registration entries (.reg) file.</title>
+ <title>Sample registration entries (.reg) file</title>
<programlisting>
REGEDIT4
@@ -244,8 +244,8 @@
<!-- TODO(cmpilato): Rework and move this section to the Reference -->
<para>In this section, we will discuss the specific
- runtime configuration options that are currently supported
- by Subversion.</para>
+ runtime configuration options that Subversion currently
+ supports.</para>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.advanced.confarea.opts.servers">
@@ -352,10 +352,10 @@
<varlistentry>
<term><literal>http-compression</literal></term>
<listitem>
- <para>This specifies whether or not Subversion should
+ <para>This specifies whether Subversion should
attempt to compress network requests made to DAV-ready
servers. The default value is <literal>yes</literal>
- (though compression will only occur if that capability
+ (though compression will occur only if that capability
is compiled into the network layer). Set this to
<literal>no</literal> to disable compression, such as
when debugging network transmissions.</para>
@@ -446,7 +446,7 @@
passphrase whenever the certificate is used. If you
find this annoying (and don't mind storing the
password in the <filename>servers</filename> file),
- then you can set this variable to the certificate's
+ you can set this variable to the certificate's
passphrase. You won't be prompted anymore.</para>
</listitem>
</varlistentry>
@@ -491,7 +491,7 @@
<listitem>
<para>This setting is the same as
<literal>store-passwords</literal>, except that it
- enables or disables disk-caching of
+ enables or disables on-disk caching of
<emphasis>all</emphasis> authentication information:
usernames, passwords, server certificates, and any
other types of cacheable credentials.</para>
@@ -586,7 +586,7 @@
command, Subversion lists unversioned files and
directories along with the versioned ones, annotating
them with a <literal>?</literal> character (see <xref
- linkend="svn.tour.cycle.examine.status" />). Sometimes, it can
+ linkend="svn.tour.cycle.examine.status" />). Sometimes it can
be annoying to see uninteresting, unversioned
items—for example, object files that result from
a program's compilation—in this display. The
@@ -605,7 +605,7 @@
by explicitly specifying the filename, or by using
the <option>--no-ignore</option> command-line flag.</para>
- <para>For information on more fine-grained control of
+ <para>For information on finer-grained control of
ignored items, see
<xref linkend="svn.advanced.props.special.ignore" />.</para>
</listitem>
@@ -643,7 +643,7 @@
<listitem>
<para>Normally your working copy files have timestamps
that reflect the last time they were touched by any
- process, whether that be your own editor or by some
+ process, whether your own editor or some
<command>svn</command> subcommand. This is generally
convenient for people developing software, because
build systems often look at timestamps as a way of
@@ -689,7 +689,7 @@
1.5.</para>
<para>When Subversion detects conflicting file content
- changes, it defers resolution of that conflict to the
+ changes, it defers resolution of those conflicts to the
user. To assist in the resolution, Subversion keeps
pristine copies of the various competing versions of
the file in the working copy. By default, those
@@ -719,15 +719,15 @@
configuration option, though. For files with one of
the specified extensions, Subversion will append to
the conflict file names the custom extension just as
- before, but then also re-append the file's original
+ before, but then also reappend the file's original
extension. Using the previous example, and assuming
- that <filename>pdf</filename> is one of the extensions
+ that <literal>pdf</literal> is one of the extensions
configured in this list thereof, the conflict files
generated for <filename>ReleaseNotes.pdf</filename>
would instead be named
<filename>ReleaseNotes.pdf.mine.pdf</filename> and
<filename>ReleaseNotes.pdf.r4231.pdf</filename>.
- Because each of these files end in
+ Because each file ends in
<filename>.pdf</filename>, the correct default
application will be used to view them.</para>
</listitem>
@@ -736,7 +736,7 @@
<varlistentry>
<term><literal>interactive-conflicts</literal></term>
<listitem>
- <para>This is a boolean option that specifies whether
+ <para>This is a Boolean option that specifies whether
Subversion should try to resolve conflicts
interactively. If its value is <literal>yes</literal>
(which is the default value), Subversion will prompt
@@ -751,7 +751,7 @@
<varlistentry>
<term><literal>no-unlock</literal></term>
<listitem>
- <para>This boolean option corresponds to <command>svn
+ <para>This Boolean option corresponds to <command>svn
commit</command>'s <option>--no-unlock</option>
option, which tells Subversion not to release locks on
files you've just committed. If this runtime option
@@ -801,7 +801,7 @@
world or prints messages (or accepts input) in your native
language, the program is said to
be <firstterm>localized</firstterm>. This section describes
- steps Subversion has made towards localization.</para>
+ steps Subversion has made toward localization.</para>
<!-- =============================================================== -->
<sect2 id="svn.advanced.l10n.understanding">
@@ -838,18 +838,18 @@
locale, but users can set these variables to specific
country/language code combinations. For example, if one were
to set the <literal>LC_TIME</literal> variable to
- <literal>fr_CA</literal>, then programs would know to present
- time and date information formatted according a
+ <literal>fr_CA</literal>, programs would know to present
+ time and date information formatted according to a
French-speaking Canadian's expectations. And if one were to
set the <literal>LC_MESSAGES</literal> variable to
- <literal>zh_TW</literal>, then programs would know to present
+ <literal>zh_TW</literal>, programs would know to present
human-readable messages in Traditional Chinese. Setting the
<literal>LC_ALL</literal> variable has the effect of changing
every locale variable to the same value. The value of
<literal>LANG</literal> is used as a default value for any
locale variable that is unset. To see the list of available
- locales on a Unix system, run the command <command>locale
- -a</command>.</para>
+ locales on a Unix system, run the command <userinput>locale
+ -a</userinput>.</para>
<para>On Windows, locale configuration is done via the
<quote>Regional and Language Options</quote> control panel
@@ -893,7 +893,7 @@
on Windows they're often found in the
<filename>\share\locale\</filename> folder in Subversion's
installation area. Once installed, a module is named after
- the program it provides translations for. For example, the
+ the program for which it provides translations. For example, the
<filename>de.mo</filename> file may ultimately end up
installed as
<filename>/usr/share/locale/de/LC_MESSAGES/subversion.mo</filename>.
@@ -909,13 +909,13 @@
repository is ready to accept input in any human language.
This means, however, that the Subversion client is responsible
for sending only UTF-8 filenames and log messages into the
- repository. In order to do this, it must convert the data
+ repository. To do this, it must convert the data
from the native locale into UTF-8.</para>
<para>For example, suppose you create a file named
<filename>caffè.txt</filename>, and then when committing the
file, you write the log message as <quote>Adesso il caffè è
- più forte.</quote> Both the filename and log message contain
+ più forte.</quote> Both the filename and the log message contain
non-ASCII characters, but because your locale is set to
<literal>it_IT</literal>, the Subversion client knows to
interpret them as Italian. It uses an Italian character set
@@ -942,7 +942,7 @@
…
</screen>
- <para>Errors like this typically occur when the Subversion
+ <para>Errors such as this typically occur when the Subversion
client has received a UTF-8 string from the repository, but
not all of the characters in that string can be represented
using the encoding of the current locale. For example, if
@@ -956,7 +956,7 @@
data, or to change the filename or log message in the
repository. (And don't forget to slap your collaborator's
hand—projects should decide on common languages ahead of
- time, so that all participants are using the same
+ time so that all participants are using the same
locale.)</para>
</sidebar>
@@ -972,8 +972,8 @@
<para>The most obvious way to get data into Subversion is through
the addition of files to version control, committing changes to
- those files, and so on. But there are other pieces of
- information besides merely versioned file data that live in your
+ those files, and so on. But other pieces of
+ information besides merely versioned file data live in your
Subversion repository. Some of these bits of
information—commit log messages, lock comments, and some
property values—tend to be textual in nature and are
@@ -995,7 +995,7 @@
on demand.</para>
<para>Subversion supports this by allowing you to specify an
- external text editor that it will launch as necessary in order
+ external text editor that it will launch as necessary
to give you a more powerful input mechanism for this textual
metadata. There are several ways to tell Subversion which
editor you'd like use. Subversion checks the following things,
@@ -1027,7 +1027,7 @@
<para>The value of any of these options or variables is the
beginning of a command line to be executed by the shell.
Subversion appends to that command line a space and the pathname
- of a temporary file to be edited. So, in order to be used with
+ of a temporary file to be edited. So, to be used with
Subversion, the configured or specified editor needs to support
an invocation in which its last command-line parameter is a file
to be edited, and it should be able to save the file in place
@@ -1037,7 +1037,7 @@
messages to any of the committing subcommands (such as
<command>svn commit</command> or <command>import</command>,
<command>svn mkdir</command> or <command>delete</command> when
- provided a URL target, and so on), and Subversion will try to
+ provided a URL target, etc.), and Subversion will try to
launch the editor automatically if you don't specify either of
the <option>--message</option> (<option>-m</option>) or
<option>--file</option> (<option>-F</option>) options. The
@@ -1068,7 +1068,7 @@
later, Subversion grew its own internal differencing library,
and as a failover mechanism, the <option>--diff-cmd</option> and
<option>--diff3-cmd</option> options were added to the
- Subversion command-line client so users could more easily
+ Subversion command-line client so that users could more easily
indicate that they preferred to use the GNU diff and diff3
utilities instead of the newfangled internal diff library. If
those options were used, Subversion would simply ignore the
@@ -1085,8 +1085,8 @@
members of the GNU diffutils toolchain. But the only
configurable aspect of using those external tools is their
location on the system—not the option set, parameter
- order, etc. Subversion continues throwing all those GNU utility
- options at your external diff tool regardless of whether or not
+ order, and so on. Subversion continues to throw all those GNU utility
+ options at your external diff tool regardless of whether
that program can understand those options. And that's where
things get unintuitive for most users.</para>
@@ -1103,11 +1103,11 @@
<para>The decision on when to fire off a contextual two- or three-way
diff as part of a larger Subversion operation is made entirely
by Subversion and is affected by, among other things, whether
- or not the files being operated on are human-readable as
+ the files being operated on are human-readable as
determined by their <literal>svn:mime-type</literal> property.
This means, for example, that even if you had the niftiest
Microsoft Word-aware differencing or merging tool in the
- Universe, it would never be invoked by Subversion so long as
+ universe, it would never be invoked by Subversion as long as
your versioned Word documents had a configured MIME type that
denoted that they were not human-readable (such as
<literal>application/msword</literal>). For more about MIME
@@ -1117,17 +1117,17 @@
<para>Subversion 1.5 introduces interactive resolution of
conflicts (described in <xref linkend="svn.tour.cycle.resolve"
- />), and one of the options provided to users is the ability
+ />), and one of the options provided to users is the ability to
launch a third-party merge tool. If this action is taken,
Subversion will consult the <literal>merge-tool-cmd</literal>
runtime configuration option to find the name of an external
- merge tool and, upon finding one, launch that tool with the
+ merge tool and, upon finding one, will launch that tool with the
appropriate input files. This differs from the configurable
three-way differencing tool in a couple of ways. First, the
differencing tool is always used to handle three-way
- differences, whereas the merge tool is only employed when
+ differences, whereas the merge tool is employed only when
three-way difference application has detected a conflict.
- Secondly, the interface is much cleaner—your configured
+ Second, the interface is much cleaner—your configured
merge tool need only accept as command-line parameters four path
specifications: the base file, the <quote>theirs</quote> file
(which contains upstream changes), the <quote>mine</quote> file
@@ -1140,13 +1140,13 @@
<para>Subversion calls external diff programs with parameters
suitable for the GNU diff utility, and expects only that the
- external program return with a successful error code. For
+ external program will return with a successful error code. For
most alternative diff programs, only the sixth and seventh
arguments—the paths of the files that represent the left and
right sides of the diff, respectively—are of interest. Note
that Subversion runs the diff program once per modified file
covered by the Subversion operation, so if your program runs
- in an asynchronous fashion (or <quote>backgrounded</quote>),
+ in an asynchronous fashion (or is <quote>backgrounded</quote>),
you might have several instances of it all running
simultaneously. Finally, Subversion expects that your program
return an error code of 1 if your program detected differences,
@@ -1174,7 +1174,7 @@
# Configure your favorite diff program here.
DIFF = "/usr/local/bin/my-diff-tool"
-# Subversion provides the paths we need as last two parameters.
+# Subversion provides the paths we need as the last two parameters.
LEFT = sys.argv[-2]
RIGHT = sys.argv[-1]
@@ -1196,7 +1196,7 @@
REM Configure your favorite diff program here.
SET DIFF="C:\Program Files\Funky Stuff\My Diff Tool.exe"
-REM Subversion provides the paths we need as last two parameters.
+REM Subversion provides the paths we need as the last two parameters.
REM These are parameters 6 and 7 (unless you use svn diff -x, in
REM which case, all bets are off).
SET LEFT=%6
@@ -1218,11 +1218,11 @@
<para>Subversion calls external merge programs with parameters
suitable for the GNU diff3 utility, expecting that the
- external program return with a successful error code and that
+ external program will return with a successful error code and that
the full file contents that result from the completed merge
operation are printed on the standard output stream (so that
- Subversion can redirect them into the appropriate version
- controlled file). For most alternative merge programs, only
+ Subversion can redirect them into the appropriate version-controlled
+ file). For most alternative merge programs, only
the ninth, tenth, and eleventh arguments, the paths of the
files which represent the <quote>mine,</quote>
<quote>older,</quote> and <quote>yours</quote> inputs,
@@ -1249,7 +1249,7 @@
# Configure your favorite diff program here.
DIFF3 = "/usr/local/bin/my-merge-tool"
-# Subversion provides the paths we need as last three parameters.
+# Subversion provides the paths we need as the last three parameters.
MINE = sys.argv[-3]
OLDER = sys.argv[-2]
YOURS = sys.argv[-1]
@@ -1274,8 +1274,8 @@
REM Configure your favorite diff3/merge program here.
SET DIFF3="C:\Program Files\Funky Stuff\My Merge Tool.exe"
-REM Subversion provides the paths we need as last three parameters.
-REM These are parameters 9, 10, and 11. But we only have access to
+REM Subversion provides the paths we need as the last three parameters.
+REM These are parameters 9, 10, and 11. But we have access to only
REM nine parameters at a time, so we shift our nine-parameter window
REM twice to let us get to what we need.
SHIFT
@@ -1298,6 +1298,30 @@
</sect2>
</sect1>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.customization.summary">
+ <title>Summary</title>
+
+ <para>Sometimes there's a single right way to do things; sometimes
+ there are many. Subversion's developers understand that while
+ the majority of its exact behaviors are acceptable to most of
+ its users, there are some corners of its functionality where
+ such a universally pleasing approach doesn't exist. In those
+ places, Subversion offers users the opportunity to tell it how
+ <emphasis>they</emphasis> want it to behave.</para>
+
+ <para>In this chapter, we explored Subversion's runtime
+ configuration system and other mechanisms by which users can
+ control those configurable behaviors. If you are a developer,
+ though, the next chapter will take you one step further. It
+ describes how you can further customize your Subversion
+ experience by writing your own software against Subversion's
+ libraries.</para>
+
+ </sect1>
+
</chapter>
<!--
Modified: trunk/src/de/book/ch08-embedding-svn.xml
==============================================================================
--- trunk/src/de/book/ch08-embedding-svn.xml (original)
+++ trunk/src/de/book/ch08-embedding-svn.xml Tue Aug 12 11:40:38 2008
@@ -3,13 +3,13 @@
<para>Subversion has a modular design: it's implemented as a
collection of libraries written in C. Each library has a
- well-defined purpose and Application Programming Interface (API),
+ well-defined purpose and application programming interface (API),
and that interface is available not only for Subversion itself to
use, but for any software that wishes to embed or otherwise
programmatically control Subversion. Additionally, Subversion's
API is available not only to other C programs, but also to
programs written in higher-level languages such as Python, Perl,
- Java, or Ruby.</para>
+ Java, and Ruby.</para>
<para>This chapter is for those who wish to interact with Subversion
through its public API or its various language bindings. If you
@@ -30,9 +30,9 @@
<title>Layered Library Design</title>
<para>Each of Subversion's core libraries can be said to exist in
- one of three main layers—the Repository Layer, the
- Repository Access (RA) Layer, or the Client Layer (see <xref
- linkend="svn.intro.architecture.dia-1" />). We will examine
+ one of three main layers—the Repository layer, the
+ Repository Access (RA) layer, or the Client layer (see <xref
+ linkend="svn.intro.architecture.dia-1" /> in the Preface). We will examine
these layers shortly, but first, let's briefly summarize
Subversion's various libraries. For the sake of consistency, we
will refer to the libraries by their extensionless Unix library
@@ -76,13 +76,13 @@
loader</para></listitem>
</varlistentry>
<varlistentry>
- <term>libsvn_ra_neon</term>
- <listitem><para>The WebDAV Repository Access
+ <term>libsvn_ra_local</term>
+ <listitem><para>The local Repository Access
module</para></listitem>
</varlistentry>
<varlistentry>
- <term>libsvn_ra_local</term>
- <listitem><para>The local Repository Access
+ <term>libsvn_ra_neon</term>
+ <listitem><para>The WebDAV Repository Access
module</para></listitem>
</varlistentry>
<varlistentry>
@@ -135,13 +135,13 @@
given module with a whole new library that implements the same
API without affecting the rest of the code base. In some sense,
this happens within Subversion already. The
- <filename>libsvn_ra_neon</filename>,
<filename>libsvn_ra_local</filename>,
+ <filename>libsvn_ra_neon</filename>,
<filename>libsvn_ra_serf</filename>, and
<filename>libsvn_ra_svn</filename> libraries each implement the
same interface, all working as plug-ins to
<filename>libsvn_ra</filename>. And all four communicate with
- the Repository Layer—libsvn_ra_local connects to the
+ the Repository layer—<filename>libsvn_ra_local</filename> connects to the
repository directly; the other three do so over a network. The
<filename>libsvn_fs_base</filename> and
<filename>libsvn_fs_fs</filename> libraries are another pair of
@@ -156,8 +156,8 @@
Subversion client (see <xref
linkend="svn.developer.layerlib.client"/>). So while the
Subversion distribution provides only the <command>svn</command>
- command-line client program, there are several third-party
- programs that provide various forms of graphical client UIs.
+ command-line client program, several third-party
+ programs provide various forms of graphical client UIs.
These GUIs use the same APIs that the stock command-line client
does. This type of modularity has played a large role in the
proliferation of available Subversion clients and IDE
@@ -168,7 +168,7 @@
<sect2 id="svn.developer.layerlib.repos">
<title>Repository Layer</title>
- <para>When referring to Subversion's Repository Layer, we're
+ <para>When referring to Subversion's Repository layer, we're
generally talking about two basic concepts—the versioned
filesystem implementation (accessed via
<filename>libsvn_fs</filename>, and supported by its
@@ -178,13 +178,13 @@
<filename>libsvn_repos</filename>). These libraries provide
the storage and reporting mechanisms for the various revisions
of your version-controlled data. This layer is connected to
- the Client Layer via the Repository Access Layer, and is, from
+ the Client layer via the Repository Access layer, and is, from
the perspective of the Subversion user, the stuff at the
<quote>other end of the line.</quote></para>
- <para>The Subversion Filesystem is not a kernel-level filesystem
+ <para>The Subversion filesystem is not a kernel-level filesystem
that one would install in an operating system (such as the
- Linux ext2 or NTFS), but instead is a a virtual filesystem.
+ Linux ext2 or NTFS), but instead is a virtual filesystem.
Rather than storing <quote>files</quote> and
<quote>directories</quote> as real files and directories (the
kind you can navigate through using your favorite shell
@@ -200,7 +200,7 @@
something similar to this before launching the Google Code
Project Hosting service: they announced in mid-2006 that
members of its open source team had written a new proprietary
- Subversion filesystem plug-in that used their ultra-scalable
+ Subversion filesystem plug-in that used Google's ultra-scalable
Bigtable database for its storage.</para>
<para>The filesystem API exported by
@@ -211,7 +211,7 @@
It also has features that are not quite as common, such as the
ability to add, modify, and remove metadata
(<quote>properties</quote>) on each file or directory.
- Furthermore, the Subversion Filesystem is a versioning
+ Furthermore, the Subversion filesystem is a versioning
filesystem, which means that as you make changes to your
directory tree, Subversion remembers what your tree looked
like before those changes. And before the previous changes.
@@ -255,7 +255,7 @@
other words, transactions give you the ability to perform a
set of actions in an all-or-nothing fashion—either all
the actions in the set complete with success, or they all
- get treated as if <emphasis>none</emphasis> of them ever
+ get treated as though <emphasis>none</emphasis> of them ever
happened—and in a way that does not interfere with
other processes acting on the data.</para>
@@ -269,8 +269,8 @@
tree. If that isn't confusing enough, consider the fact
that Subversion uses a database transaction during the
creation of a Subversion transaction (so that if the
- creation of Subversion transaction fails, the database will
- look as if we had never attempted that creation in the first
+ creation of a Subversion transaction fails, the database will
+ look as though we had never attempted that creation in the first
place)!</para>
<para>Fortunately for users of the filesystem API, the
@@ -283,12 +283,12 @@
</sidebar>
- <para>Most of the functionality provided by the filesystem
- interface deals with actions that occur on individual
- filesystem paths. That is, from outside of the filesystem, the
+ <para>Most of the functionality the filesystem
+ interface provides deals with actions that occur on individual
+ filesystem paths. That is, from outside the filesystem, the
primary mechanism for describing and accessing the individual
revisions of files and directories comes through the use of
- path strings such as <filename>/foo/bar</filename>, just as if
+ path strings such as <filename>/foo/bar</filename>, just as though
you were addressing files and directories through your
favorite shell program. You add new files and directories by
passing their paths-to-be to the right API functions. You
@@ -323,8 +323,8 @@
<parameter>root</parameter> argument. This
<literal>svn_fs_root_t</literal> argument describes
either a revision or a Subversion transaction (which is simply
- a revision in the making) and provides that third-dimensional
- context needed to understand the difference between
+ a revision in the making) and provides that third dimension
+ of context needed to understand the difference between
<filename>/foo/bar</filename> in revision 32, and the same
path as it exists in revision 98. <xref
linkend="svn.developer.layerlib.repos.dia-2"/> shows revision
@@ -404,8 +404,8 @@
<sect2 id="svn.developer.layerlib.ra">
<title>Repository Access Layer</title>
- <para>If the Subversion Repository Layer is at <quote>the other
- end of the line,</quote> the Repository Access (RA) Layer is
+ <para>If the Subversion Repository layer is at <quote>the other
+ end of the line,</quote> the Repository Access (RA) layer is
the line itself. Charged with marshaling data between the
client libraries and the repository, this layer includes the
<filename>libsvn_ra</filename> module loader library, the RA
@@ -430,7 +430,7 @@
to use for the task at hand. You can determine which RA
modules are available to the Subversion command-line client,
and what protocols they claim to support, by running
- <command>svn --version</command>:</para>
+ <userinput>svn --version</userinput>:</para>
<screen>
$ svn --version
@@ -457,7 +457,7 @@
$
</screen>
- <para>The public API exported by the RA Layer contains
+ <para>The public API exported by the RA layer contains
functionality necessary for sending and receiving versioned
data to and from the repository. And each of the available RA
plug-ins is able to perform that task using a specific
@@ -471,7 +471,7 @@
<para>For those who wish to access a Subversion repository
using still another protocol, that is precisely why the
- Repository Access Layer is modularized! Developers can simply
+ Repository Access layer is modularized! Developers can simply
write a new library that implements the RA interface on one
side and communicates with the repository on the other. Your
new library can use existing network protocols or you can
@@ -514,7 +514,7 @@
<para>The Subversion client library,
<filename>libsvn_client</filename>, has the broadest
responsibility; its job is to mingle the functionality of the
- working copy library with that of the Repository Access Layer,
+ working copy library with that of the Repository Access layer,
and then to provide the highest-level API to any application
that wishes to perform general revision control actions. For
example, the function
@@ -536,7 +536,7 @@
<filename>libsvn_client</filename> API to the same functionality,
data, and callback mechanisms that the command-line client
uses. In fact, the Subversion source code tree contains a
- small C program (which can be found at
+ small C program (which you can find at
<filename>tools/examples/minimal_client.c</filename>) that
exemplifies how to wield the Subversion API to create a simple
client program.</para>
@@ -596,25 +596,25 @@
working copy contains a special subdirectory called
<filename>.svn</filename> that houses administrative data about
that working copy directory. Subversion uses the information in
- <filename>.svn</filename> to keep track of things like:</para>
+ <filename>.svn</filename> to keep track of things such as:</para>
<itemizedlist>
<listitem>
<para>Which repository location(s) are represented by the
files and subdirectories in the working copy
- directory.</para>
+ directory</para>
</listitem>
<listitem>
- <para>What revision of each of those files and directories are
- currently present in the working copy.</para>
+ <para>What revision of each of those files and directories is
+ currently present in the working copy</para>
</listitem>
<listitem>
<para>Any user-defined properties that might be attached
- to those files and directories.</para>
+ to those files and directories</para>
</listitem>
<listitem>
<para>Pristine (unedited) copies of the working copy
- files.</para>
+ files</para>
</listitem>
</itemizedlist>
@@ -639,7 +639,7 @@
<filename>entries</filename> file. It
contains the bulk of the administrative
information about the versioned items in a working copy
- directory. It is this one file that tracks the repository
+ directory. This one file tracks the repository
URLs, pristine revision, file checksums, pristine text and
property timestamps, scheduling and conflict state
information, last-known commit information (author, revision,
@@ -678,28 +678,28 @@
<para>As mentioned before, the <filename>.svn</filename>
directory also holds the pristine <quote>text-base</quote>
- versions of files. Those can be found in
+ versions of files. You can find those in
<filename>.svn/text-base</filename>. The benefits of these
pristine copies are multiple—network-free checks for
local modifications and difference reporting, network-free
reversion of modified or missing files, more efficient
- transmission of changes to the server—but comes at the
+ transmission of changes to the server—but they come at the
cost of having each versioned file stored at least twice on
disk. These days, this seems to be a negligible penalty for
most files. However, the situation gets uglier as the size of
your versioned files grows. Some attention is being given to
making the presence of the <quote>text-base</quote> an option.
- Ironically though, it is as your versioned files' sizes get
+ Ironically, though, it is as your versioned files' sizes get
larger that the existence of the <quote>text-base</quote>
becomes more crucial—who wants to transmit a huge file
- across a network just because they want to commit a tiny
+ across a network just because she wants to commit a tiny
change to it?</para>
<para>Similar in purpose to the <quote>text-base</quote> files
are the property files and their pristine
<quote>prop-base</quote> copies, located in
<filename>.svn/props</filename> and
- <filename>.svn/prop-base</filename> respectively. Since
+ <filename>.svn/prop-base</filename>, respectively. Since
directories can have properties too, there are also
<filename>.svn/dir-props</filename> and
<filename>.svn/dir-prop-base</filename> files.</para>
@@ -719,12 +719,12 @@
libraries, with header (<filename>.h</filename>) files that live
in the <filename>subversion/include</filename> directory of the
source tree. These headers are copied into your system
- locations (for example, <filename>/usr/local/include</filename>)
+ locations (e.g., <filename>/usr/local/include</filename>)
when you build and install Subversion itself from source. These
headers represent the entirety of the functions and types meant
to be accessible by users of the Subversion libraries. The
Subversion developer community is meticulous about ensuring that
- the public API is well-documented—refer directly to the
+ the public API is well documented—refer directly to the
header files for that documentation.</para>
<para>When examining the public header files, the first thing you
@@ -735,7 +735,7 @@
<literal>wc</literal>, <literal>client</literal>,
<literal>fs</literal>, etc.), followed by a single underscore
(<literal>_</literal>), and then the rest of the symbol name.
- Semi-public functions (used among source files of a given
+ Semipublic functions (used among source files of a given
library but not by code outside that library, and found inside
the library directories themselves) differ from this naming
scheme in that instead of a single underscore after the library
@@ -748,7 +748,7 @@
<para>Another good source of information about programming against
the Subversion APIs is the project's own hacking guidelines,
- which can be found at <ulink
+ which you can find at <ulink
url="http://subversion.tigris.org/hacking.html" />. This
document contains useful information, which, while aimed at
developers and would-be developers of Subversion itself, is
@@ -777,8 +777,8 @@
developers immediately recognized the value of using APR as
well. This means that there is practically no OS-specific
code in Subversion itself. Also, it means that the Subversion
- client compiles and runs anywhere that Apache HTTP Server
- does. Currently this list includes all flavors of Unix,
+ client compiles and runs anywhere that the Apache HTTP Server
+ does. Currently, this list includes all flavors of Unix,
Win32, BeOS, OS/2, and Mac OS X.</para>
<para>In addition to providing consistent implementations of
@@ -800,7 +800,7 @@
<para>Neon and Berkeley DB are examples of such libraries.</para>
</footnote>
and while a person coding against the Subversion APIs is not
- required to do the same, they <emphasis>are</emphasis>
+ required to do the same, she <emphasis>is</emphasis>
required to provide pools to the API functions that need them.
This means that users of the Subversion API must also link
against APR, must call <function>apr_initialize()</function>
@@ -870,12 +870,12 @@
<filename>libsvn_client</filename> interface needs to first
convert paths from the locale-specific encoding to UTF-8
before passing those paths to the Subversion libraries, and
- then re-convert any resultant output paths from Subversion
+ then reconvert any resultant output paths from Subversion
back into the locale's encoding before using those paths for
non-Subversion purposes. Fortunately, Subversion provides a
suite of functions (see
- <filename>subversion/include/svn_utf.h</filename>) that can be
- used by any program to do these conversions.</para>
+ <filename>subversion/include/svn_utf.h</filename>) that
+ any program can use to do these conversions.</para>
<para>Also, Subversion APIs require all URL parameters to be
properly URI-encoded. So, instead of passing
@@ -889,10 +889,10 @@
<!-- =============================================================== -->
<sect2 id="svn.developer.usingapi.otherlangs">
- <title>Using Languages Other than C and C++</title>
+ <title>Using Languages Other Than C and C++</title>
<para>If you are interested in using the Subversion libraries in
- conjunction with something other than a C program—say a
+ conjunction with something other than a C program—say, a
Python or Perl script—Subversion has some support for this
via the Simplified Wrapper and Interface Generator (SWIG). The
SWIG bindings for Subversion are located in
@@ -902,7 +902,7 @@
translate the datatypes native to your scripting language into
the datatypes needed by Subversion's C libraries.</para>
- <para>Significant efforts have been made towards creating
+ <para>Significant efforts have been made toward creating
functional SWIG-generated bindings for Python, Perl, and Ruby.
To some extent, the work done preparing the SWIG interface
files for these languages is reusable in efforts to generate
@@ -945,11 +945,11 @@
interface than the more C-like APIs provided by Subversion's
own Python bindings. And if you're looking for a pure Java
implementation of Subversion, check out SVNKit (<ulink
- url="http://svnkit.com/" />), which is Subversion re-written
+ url="http://svnkit.com/" />), which is Subversion rewritten
from the ground up in Java.</para>
<sidebar>
- <title>SVNKit versus javahl</title>
+ <title>SVNKit Versus javahl</title>
<para>In 2005, a small company called TMate announced the
1.0.0 release of JavaSVN—a pure Java implementation of
@@ -976,13 +976,13 @@
already happened once—SVNKit cannot access BDB-backed
Subversion repositories via the <literal>file://</literal>
protocol because there's no pure Java implementation of
- Berkeley DB that is file format-compatible with the native
+ Berkeley DB that is file-format-compatible with the native
implementation of that library.</para>
<para>That said, SVNKit has a well-established track record of
reliability. And a pure Java solution is much more robust
in the face of programming errors—a bug in SVNKit
- might raise an Exception, but a bug in the Subversion core
+ might raise a catchable Java Exception, but a bug in the Subversion core
libraries as accessed via javahl can bring down your entire
Java Runtime Environment. So, weigh the costs when choosing
a Java-based Subversion implementation.</para>
@@ -1124,7 +1124,7 @@
API knows nothing about the repository library's hook
mechanism. If you want your Subversion repository to
automatically perform some set of non-Subversion tasks every
- time you commit a transaction (for example, sending an
+ time you commit a transaction (e.g., sending an
email that describes all the changes made in that transaction
to your developer mailing list), you need to use the
<filename>libsvn_repos</filename>-wrapped version of that
@@ -1141,7 +1141,7 @@
print the various paths reached during the crawl.</para>
<example id="svn.developer.usingapi.otherlangs.ex-1">
- <title>Using the Repository Layer with Python</title>
+ <title>Using the Repository layer with Python</title>
<programlisting>
#!/usr/bin/python
@@ -1231,7 +1231,7 @@
simplifying the process of writing a Subversion client. <xref
linkend="svn.developer.usingapi.otherlangs.ex-2" /> is a brief
example of how that library can be accessed via the SWIG
- Python bindings to recreate a scaled-down version of the
+ Python bindings to re-create a scaled-down version of the
<command>svn status</command> command.</para>
<example id="svn.developer.usingapi.otherlangs.ex-2">
@@ -1327,7 +1327,7 @@
<para>As was the case in <xref
linkend="svn.developer.usingapi.otherlangs.ex-1" />, this
program is pool-free and uses, for the most part, normal
- Python data types. The call to
+ Python datatypes. The call to
<function>svn_client_ctx_t()</function> is deceiving because
the public Subversion API has no such function—this just
happens to be a case where SWIG's automatic language
@@ -1344,6 +1344,31 @@
</sect2>
</sect1>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.developer.summary">
+ <title>Summary</title>
+
+ <para>One of Subversion's greatest features isn't something you
+ get from running its command-line client or other tools. It's
+ the fact that Subversion was designed modularly and provides a
+ stable, public API so that others—like yourself,
+ perhaps—can write custom software that drives Subversion's
+ core logic.</para>
+
+ <para>In this chapter, we took a closer look at Subversion's
+ architecture, examining its logical layers and describing that
+ public API, the very same API that Subversion's own layers use
+ to communicate with each other. Many developers have found
+ interesting uses for the Subversion API, from simple repository
+ hook scripts, to integrations between Subversion and some other
+ application, to completely different version control systems.
+ What unique itch will <emphasis>you</emphasis> scratch with
+ it?</para>
+
+ </sect1>
+
</chapter>
<!--
Modified: trunk/src/de/book/ch09-reference.xml
==============================================================================
--- trunk/src/de/book/ch09-reference.xml (original)
+++ trunk/src/de/book/ch09-reference.xml Tue Aug 12 11:40:38 2008
@@ -16,15 +16,15 @@
<title>The Subversion Command-Line Client: <command>svn</command></title>
<para>To use the command-line client, type
- <command>svn</command>, the subcommand you wish to use, and
+ <command>svn</command>, the subcommand you wish to use,
<footnote>
<para>Well, you don't need a subcommand to use the
<option>--version</option> option, but we'll get to that in
just a minute.</para>
</footnote>
- any options or targets that you wish to operate on—there
- is no specific order that the subcommand and the options must
- appear in. For example, all of the following are valid ways to
+ and any options or targets that you wish to operate on—the
+ subcommand and the options need not appear in a specific order.
+ For example, all of the following are valid ways to
use <command>svn status</command>:</para>
<screen>
@@ -39,7 +39,7 @@
<!-- =============================================================== -->
<sect2 id="svn.ref.svn.sw">
- <title><command>svn</command> Options</title>
+ <title>svn Options</title>
<para>While Subversion has different options for its
subcommands, all options exist in a single
@@ -55,7 +55,7 @@
Subversion 1.5, several of the options which apply to
all—or nearly all—of the subcommands have been
deemed acceptable by all subcommands, even if they have no
- effect upon some of them. They appear grouped together in the
+ effect on some of them. They appear grouped together in the
command-line client's usage messages as global options. This
was done to assist folks who write scripts which wrap the
command-line client. These global options are as
@@ -90,7 +90,7 @@
of interactive prompting include requests for
authentication credentials and conflict resolution
decisions. This is useful if you're running Subversion
- inside of an automated script and it's more appropriate
+ inside an automated script and it's more appropriate
to have Subversion fail than to prompt for more
information.</para>
</listitem>
@@ -129,11 +129,11 @@
<term><option>--accept</option>
<replaceable>ACTION</replaceable></term>
<listitem>
- <para>Specify action for automatic conflict resolution.
+ <para>Specifies an action for automatic conflict resolution.
Possible actions are <literal>postpone</literal>,
- <literal>base</literal>, <literal>mine</literal>,
- <literal>theirs</literal>, <literal>edit</literal>, and
- <literal>launch.</literal></para>
+ <literal>base</literal>, <literal>mine-full</literal>,
+ <literal>theirs-full</literal>, <literal>edit</literal>, and
+ <literal>launch</literal>.</para>
</listitem>
</varlistentry>
@@ -151,7 +151,7 @@
<replaceable>ARG</replaceable></term>
<listitem>
<para>Used as a means to refer to a specific
- <quote>change</quote> (aka a revision), this option is
+ <quote>change</quote> (a.k.a. a revision). This option is
syntactic sugar for <quote>-r ARG-1:ARG</quote>.</para>
</listitem>
</varlistentry>
@@ -160,8 +160,8 @@
<term><option>--changelist</option>
<replaceable>ARG</replaceable></term>
<listitem>
- <para>Operate only on members of the changelist named
- <replaceable>ARG</replaceable>. This option can be used
+ <para>Instructs Subversion to operate only on members of the changelist named
+ <replaceable>ARG</replaceable>. You can use this option
multiple times to specify sets of changelists.</para>
</listitem>
</varlistentry>
@@ -170,7 +170,7 @@
<term><option>--cl</option>
<replaceable>ARG</replaceable></term>
<listitem>
- <para>This is an alias for the
+ <para>An alias for the
<option>--changelist</option> option.</para>
</listitem>
</varlistentry>
@@ -179,7 +179,7 @@
<term><option>--depth</option>
<replaceable>ARG</replaceable></term>
<listitem>
- <para>Limit the scope of an operation to a particular tree
+ <para>Instructs Subversion to limit the scope of an operation to a particular tree
depth. <replaceable>ARG</replaceable> is one of
<literal>empty</literal>, <literal>files</literal>,
<literal>immediates</literal>, or
@@ -253,9 +253,9 @@
with the
<option>--diff-cmd</option> option.
If you wish to pass multiple
- arguments, you must enclose all of them in quotes (for
- example, <command>svn diff --diff-cmd /usr/bin/diff -x
- "-b -E"</command>).</para>
+ arguments, you must enclose all of them in quotes (e.g.,
+ <userinput>svn diff --diff-cmd /usr/bin/diff -x
+ "-b -E"</userinput>).</para>
</listitem>
<!-- TODO(fitz): Document -u -b -w and - -ignore-eol-style -->
@@ -280,8 +280,8 @@
<term><option>--force</option></term>
<listitem>
<para>Forces a particular command or operation to run.
- There are some operations that Subversion will prevent
- you from doing in normal usage, but you can pass the
+ Subversion will prevent you from performing some operations
+ in normal usage, but you can pass the
force option to tell Subversion <quote>I know what I'm
doing as well as the possible repercussions of doing it,
so let me at 'em.</quote> This option is the
@@ -296,7 +296,7 @@
<listitem>
<para>Forces a suspicious parameter passed to the
<option>--message</option> (<option>-m</option>) or
- <option>--file</option> (<option>-F</option>) options to
+ <option>--file</option> (<option>-F</option>) option to
be accepted as valid. By default, Subversion will
produce an error if parameters to these options look
like they might instead be targets of the subcommand.
@@ -334,7 +334,7 @@
<varlistentry>
<term><option>--ignore-externals</option></term>
<listitem>
- <para>Tells Subversion to ignore external definitions and
+ <para>Tells Subversion to ignore externals definitions and
the external working copies managed by them.</para>
</listitem>
</varlistentry>
@@ -350,14 +350,14 @@
<varlistentry>
<term><option>--keep-changelists</option></term>
<listitem>
- <para>Don't delete changelists after committing.</para>
+ <para>Tells Subversion not to delete changelists after committing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--keep-local</option></term>
<listitem>
- <para>Keep the local copy of a file or directory (used
+ <para>Keeps the local copy of a file or directory (used
with the <command>svn delete</command> command).</para>
</listitem>
</varlistentry>
@@ -366,7 +366,7 @@
<term><option>--limit</option> (<option>-l</option>)
<replaceable>NUM</replaceable></term>
<listitem>
- <para>Show only the first <replaceable>NUM</replaceable>
+ <para>Shows only the first <replaceable>NUM</replaceable>
log messages.</para>
</listitem>
</varlistentry>
@@ -430,7 +430,7 @@
<varlistentry>
<term><option>--no-unlock</option></term>
<listitem>
- <para>Don't automatically unlock files (the default commit
+ <para>Tells Subversion not to automatically unlock files (the default commit
behavior is to unlock all files listed as part of the
commit). See <xref linkend="svn.advanced.locking"/> for
more information.</para>
@@ -451,7 +451,7 @@
<varlistentry>
<term><option>--notice-ancestry</option></term>
<listitem>
- <para>Pay attention to ancestry when calculating
+ <para>Pays attention to ancestry when calculating
differences.</para>
</listitem>
</varlistentry>
@@ -467,7 +467,7 @@
<varlistentry>
<term><option>--parents</option></term>
<listitem>
- <para>Create and add nonexistent or nonversioned parent
+ <para>Creates and adds nonexistent or nonversioned parent
subdirectories to the working copy or repository as part
of an operation. This is useful for automatically
creating multiple subdirectories where none currently
@@ -487,8 +487,8 @@
<varlistentry>
<term><option>--record-only</option></term>
<listitem>
- <para>Mark revisions as merged (for use with
- <option>--revision</option>)</para>
+ <para>Marks revisions as merged (for use with
+ <option>--revision</option>).</para>
</listitem>
</varlistentry>
@@ -529,7 +529,7 @@
<term><option>--remove</option>
<replaceable>ARG</replaceable></term>
<listitem>
- <para>Disassociate <replaceable>ARG</replaceable> from a
+ <para>Disassociates <replaceable>ARG</replaceable> from a
changelist</para>
</listitem>
</varlistentry>
@@ -575,7 +575,7 @@
<term><option>--set-depth</option>
<replaceable>ARG</replaceable></term>
<listitem>
- <para>Set the sticky depth on a directory in a working
+ <para>Sets the sticky depth on a directory in a working
copy to one of <literal>empty</literal>,
<literal>files</literal>, <literal>immediates</literal>,
or <literal>infinity</literal>.</para>
@@ -598,7 +598,7 @@
which files in your working copy are out of date.
This doesn't actually update any of your
files—it just shows you which files will be
- updated if you run <command>svn update</command>.
+ updated if you then use <command>svn update</command>.
</para>
</listitem>
</varlistentry>
@@ -639,7 +639,7 @@
<term><option>--use-merge-history</option>
(<option>-g</option>)</term>
<listitem>
- <para>Use or display additional information from merge
+ <para>Uses or displays additional information from merge
history.</para>
</listitem>
</varlistentry>
@@ -659,7 +659,7 @@
<term><option>--version</option></term>
<listitem>
<para>Prints the client version info. This information
- not only includes the version number of the client, but
+ includes not only the version number of the client, but
also a listing of all repository access modules that the
client can use to access a Subversion repository.
With <option>--quiet</option> (<option>-q</option>) it
@@ -668,23 +668,10 @@
</varlistentry>
<varlistentry>
- <term><option>--version</option></term>
- <listitem>
- <para>Prints the client version info. This information
- not only includes the version number of the client,
- but also a listing of all repository access modules
- that the client can use to access a Subversion
- repository. With <option>--quiet</option>
- (<option>-q</option>) it prints only the version number
- in a compact form.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><option>--with-all-revprops</option></term>
<listitem>
- <para>Used with <command>svn log --xml</command>, this
- option will retrieve and display all revision
+ <para>Used with the <option>--xml</option> option to <command>svn log</command>,
+ will retrieve and display all revision
properties in the log output.</para>
</listitem>
</varlistentry>
@@ -694,11 +681,11 @@
<replaceable>ARG</replaceable></term>
<listitem>
<para>When used with any command that writes to the
- repository, this sets the revision property, using the
+ repository, sets the revision property, using the
<replaceable>NAME=VALUE</replaceable> format,
<replaceable>NAME</replaceable> to
<replaceable>VALUE</replaceable>. When used with
- <command>svn log --xml</command>, this displays the value of
+ <command>svn log</command> in <option>--xml</option> mode, this displays the value of
<replaceable>ARG</replaceable> in the log output.</para>
</listitem>
</varlistentry>
@@ -716,9 +703,9 @@
<!-- =============================================================== -->
<sect2 id="svn.ref.svn.c">
- <title><command>svn</command> Subcommands</title>
+ <title>svn Subcommands</title>
- <para>Here are the various subcommands. For the sake of
+ <para>Here are the various subcommands for the <command>svn</command> program. For the sake of
brevity, we omit the global options (described in <xref
linkend="svn.ref.svn.sw" />) from the subcommand descriptions
which follow.</para>
@@ -753,17 +740,17 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
<refsect1>
<title>Changes</title>
- <para>Working Copy</para>
+ <para>Working copy</para>
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>No</para>
</refsect1>
@@ -812,11 +799,11 @@
A otherdir
</screen>
- <para>Normally, the command <command>svn add *</command>
+ <para>Normally, the command <userinput>svn add *</userinput>
will skip over any directories that are already under
version control. Sometimes, however, you may want to add
every unversioned object in your working copy, including
- those hiding deeper down. Passing the
+ those hiding deeper. Passing the
<option>--force</option> option makes <command>svn
add</command> recurse into versioned directories:
</para>
@@ -859,8 +846,8 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para><command>praise, annotate, ann</command></para>
+ <title>Alternate names</title>
+ <para><command>praise</command>, <command>annotate</command>, <command>ann</command></para>
</refsect1>
<refsect1>
@@ -869,7 +856,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -918,7 +905,7 @@
<refsect1>
<title>Examples</title>
- <para>If you want to see blame annotated source for
+ <para>If you want to see blame-annotated source for
<filename>readme.txt</filename> in your test
repository:</para>
<screen>
@@ -932,11 +919,11 @@
5, you'll have to examine exactly what the revision
changed to be sure that Harry changed
the <emphasis>context</emphasis> of the line—he may
- have just adjusted the whitespace.
+ have adjusted just the whitespace.
</para>
<para>If you use the <option>--xml</option> option, you can
- get xml output describing the blame annotations, but not
+ get XML output describing the blame annotations, but not
the contents of the lines themselves:</para>
<screen>
@@ -990,11 +977,11 @@
<para>Output the contents of the specified files or URLs.
For listing the contents of directories, see <command>svn
- list</command> later.</para>
+ list</command> later in this chapter.</para>
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -1004,7 +991,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -1017,7 +1004,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>If you want to view <filename>readme.txt</filename> in
your repository without checking it out:</para>
@@ -1031,9 +1018,9 @@
<para>If your working copy is out of date (or you have
local modifications) and you want to see the
<literal>HEAD</literal> revision of a file in your
- working copy, <command>svn cat -r HEAD</command> will
+ working copy, <command>svn cat -r HEAD <replaceable>FILENAME</replaceable></command> will
automatically fetch the <literal>HEAD</literal> revision
- when you give it a path:</para>
+ of the specified path:</para>
</tip>
<screen>
@@ -1077,7 +1064,7 @@
</refsect1>
<refsect1>
- <title>Alternate Name</title>
+ <title>Alternate names</title>
<para><command>cl</command></para>
</refsect1>
@@ -1087,7 +1074,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>No</para>
</refsect1>
@@ -1174,17 +1161,17 @@
</refsect1>
<refsect1>
- <title>Alternate Name</title>
+ <title>Alternate names</title>
<para><command>co</command></para>
</refsect1>
<refsect1>
<title>Changes</title>
- <para>Creates a working copy.</para>
+ <para>Creates a working copy</para>
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -1210,7 +1197,9 @@
$ svn checkout file:///var/svn/repos/test mine
A mine/a
A mine/b
-Checked out revision 2.
+A mine/c
+A mine/d
+Checked out revision 20.
$ ls
mine
</screen>
@@ -1222,10 +1211,12 @@
$ svn checkout file:///var/svn/repos/test file:///var/svn/repos/quiz
A test/a
A test/b
-Checked out revision 2.
+A test/c
+A test/d
+Checked out revision 20.
A quiz/l
A quiz/m
-Checked out revision 2.
+Checked out revision 13.
$ ls
quiz test
</screen>
@@ -1238,10 +1229,12 @@
$ svn checkout file:///var/svn/repos/test file:///var/svn/repos/quiz working-copies
A working-copies/test/a
A working-copies/test/b
-Checked out revision 2.
+A working-copies/test/c
+A working-copies/test/d
+Checked out revision 20.
A working-copies/quiz/l
A working-copies/quiz/m
-Checked out revision 2.
+Checked out revision 13.
$ ls
working-copies
</screen>
@@ -1253,25 +1246,33 @@
working copy:</para>
<screen>
-$ svn checkout file:///var/svn/repos/test test
-A test/a
-A test/b
+$ svn checkout file:///var/svn/repos/test mine
+A mine/a
+A mine/b
^C
svn: The operation was interrupted
svn: caught SIGINT
-$ svn checkout file:///var/svn/repos/test test
-A test/c
-A test/d
+$ svn checkout file:///var/svn/repos/test mine
+A mine/c
^C
svn: The operation was interrupted
svn: caught SIGINT
-$ cd test
-$ svn update
-A test/e
-A test/f
-Updated to revision 3.
+$ svn update mine
+A mine/d
+Updated to revision 20.
+</screen>
+
+ <para>If you wish to check out some revision other than the
+ most recent one, you can do so by providing the
+ <option>--revision</option> (<option>-r</option>) option
+ to the <command>svn checkout</command> command:</para>
+
+ <screen>
+$ svn checkout -r 2 file:///var/svn/repos/test mine
+A mine/a
+Checked out revision 2.
</screen>
</refsect1>
@@ -1287,7 +1288,7 @@
<refnamediv>
<refname>svn cleanup</refname>
- <refpurpose>Recursively clean up the working copy.</refpurpose>
+ <refpurpose>Recursively clean up the working copy</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
@@ -1314,7 +1315,7 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -1324,7 +1325,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>No</para>
</refsect1>
@@ -1338,12 +1339,12 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>Well, there's not much to the examples here, as
<command>svn cleanup</command> generates no output. If
you pass no <replaceable>PATH</replaceable>, then
- <quote><filename>.</filename></quote> is used.</para>
+ <quote><filename>.</filename></quote> is used:</para>
<screen>
$ svn cleanup
@@ -1379,12 +1380,12 @@
<option>--message</option> option,
<command>svn</command> will launch your editor for you
to compose a commit message. See the
- <literal>editor-cmd</literal> section in <xref
+ <literal>editor-cmd</literal> list entry in <xref
linkend="svn.advanced.confarea.opts.config"/>.</para>
<para><command>svn commit</command> will send any lock
tokens that it finds and will release locks on all
- <replaceable>PATHS</replaceable> committed (recursively)
+ <replaceable>PATH</replaceable>s committed (recursively)
unless <option>--no-unlock</option> is passed.</para>
<tip>
@@ -1402,10 +1403,10 @@
<refsect1>
- <title>Alternate Name</title>
- <para><command>ci</command> (short for <command>check in</command>; not
- <command>co</command>, which is short for
- <command>checkout</command>)</para>
+ <title>Alternate names</title>
+ <para><command>ci</command> (short for <quote>check in</quote>; not
+ <command>co</command>, which is an alias for the
+ <command>checkout</command> subcommand)</para>
</refsect1>
<refsect1>
@@ -1414,7 +1415,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -1455,7 +1456,7 @@
<para>Commit a modification to the file
<filename>foo.c</filename> (explicitly specified on the
command line) with the commit message in a file named
- <literal>msg</literal>:</para>
+ <filename>msg</filename>:</para>
<screen>
$ svn commit -F msg foo.c
@@ -1516,7 +1517,7 @@
<para>Copy one or more files in a working copy or in the
repository. When copying multiple sources, they will be
- added as children of DST, which must be a directory.
+ added as children of <replaceable>DST</replaceable>, which must be a directory.
<replaceable>SRC</replaceable> and
<replaceable>DST</replaceable> can each be either a
working copy (WC) path or URL:</para>
@@ -1561,7 +1562,7 @@
a directory.</para>
<para>If no peg revision (i.e.,
- <replaceable>@REV</replaceable>) is supplied, by default,
+ <replaceable>@REV</replaceable>) is supplied, by default
the <literal>BASE</literal> revision will be used for
files copied from the working copy, while the
<literal>HEAD</literal> revision will be used for files
@@ -1575,18 +1576,17 @@
</refsect1>
<refsect1>
- <title>Alternate Name</title>
+ <title>Alternate names</title>
<para><command>cp</command></para>
</refsect1>
<refsect1>
<title>Changes</title>
- <para>Repository if destination is a URL.</para>
- <para>Working copy if destination is a WC path.</para>
+ <para>Repository if destination is a URL; working copy if destination is a WC path</para>
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes, if source or destination is in the repository, or if needed
to look up the source revision number.</para>
</refsect1>
@@ -1610,7 +1610,7 @@
<refsect1>
<title>Examples</title>
- <para>Copy an item within your working copy (just
+ <para>Copy an item within your working copy (this
schedules the copy—nothing goes into the repository
until you commit):</para>
@@ -1631,7 +1631,7 @@
A src/qux.c
</screen>
- <para>Copy revision 8 of <literal>bat.c</literal> into your
+ <para>Copy revision 8 of <filename>bat.c</filename> into your
working copy under a different name:</para>
<screen>
@@ -1640,7 +1640,7 @@
</screen>
<para>Copy an item in your working copy to a URL in the
- repository (an immediate commit, so you must supply a
+ repository (this is an immediate commit, so you must supply a
commit message):</para>
<screen>
@@ -1650,7 +1650,7 @@
</screen>
<para>Copy an item from the repository to your working
- copy (just schedules the copy—nothing goes into the
+ copy (this just schedules the copy—nothing goes into the
repository until you commit):</para>
<screen>
@@ -1683,7 +1683,7 @@
<para>This is the easiest way to <quote>tag</quote> a
revision in your repository—just <command>svn
copy</command> that revision (usually
- <literal>HEAD</literal>) into your tags directory.</para>
+ <literal>HEAD</literal>) into your <filename>tags</filename> directory.</para>
</tip>
<para>And don't worry if you forgot to tag—you can
@@ -1735,8 +1735,8 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>del, remove, rm</para>
+ <title>Alternate names</title>
+ <para><command>del</command>, <command>remove</command>, <command>rm</command></para>
</refsect1>
<refsect1>
@@ -1746,7 +1746,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if operating on URLs</para>
</refsect1>
@@ -1822,7 +1822,7 @@
<refnamediv>
<refname>svn diff</refname>
- <refpurpose>Display the differences between two revisions or paths.</refpurpose>
+ <refpurpose>This displays the differences between two revisions or paths.</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
@@ -1842,7 +1842,7 @@
</listitem>
<listitem>
- <para>Use just <command>svn diff</command>to display local
+ <para>Use just <command>svn diff</command> to display local
modifications in a working copy.</para>
</listitem>
@@ -1883,7 +1883,7 @@
<replaceable>OLD-TGT</replaceable> if not specified.
<literal>-r N</literal>
makes <replaceable>OLDREV</replaceable> default to
- N; <literal>-r N:M</literal>
+ <literal>N</literal>; <literal>-r N:M</literal>
makes <replaceable>OLDREV</replaceable> default to
<replaceable>N</replaceable> and
<replaceable>NEWREV</replaceable> default to
@@ -1892,7 +1892,7 @@
</itemizedlist>
- <para><command>diff OLD-URL[@OLDREV]
+ <para><command>svn diff OLD-URL[@OLDREV]
NEW-URL[@NEWREV]</command> is shorthand for <command>svn
diff --old=OLD-URL[@OLDREV]
--new=NEW-URL[@NEWREV].</command></para>
@@ -1906,12 +1906,12 @@
N[:M]] --old=URL1 --new=URL2</command>.</para>
<para>If <replaceable>TARGET</replaceable> is a URL, then
- revs N and M can be given either via the
+ revs <literal>N</literal> and <literal>M</literal> can be given either via the
<option>--revision</option> option or by using the
<quote>@</quote> notation as described earlier.</para>
<para>If <replaceable>TARGET</replaceable> is a working copy
- path, then the <option>--revision</option> option
+ path, the <option>--revision</option> option
means:</para>
<variablelist>
@@ -1931,7 +1931,7 @@
<listitem>
<para>The client compares
<replaceable>TARGET at N</replaceable>
- against working copy.</para>
+ against the working copy.</para>
</listitem>
</varlistentry>
@@ -1949,9 +1949,9 @@
<replaceable>URL1</replaceable> and
<replaceable>URL2</replaceable> at revisions
<replaceable>N</replaceable> and
- <replaceable>M</replaceable> respectively. If either
+ <replaceable>M</replaceable>, respectively. If either
<replaceable>N</replaceable> or
- <replaceable>M</replaceable> are omitted, a value of
+ <replaceable>M</replaceable> is omitted, a value of
<literal>HEAD</literal> is assumed.</para>
<para>By default, <command>svn diff</command> ignores the
@@ -1959,14 +1959,14 @@
two files being compared. If you use
<option>--notice-ancestry</option>, the ancestry of the
paths in question will be taken into consideration when
- comparing revisions (that is, if you run <command>svn
+ comparing revisions (i.e., if you run <command>svn
diff</command> on two files with identical contents but
different ancestry, you will see the entire contents of
the file as having been removed and added again).</para>
</refsect1>
<refsect1>
- <title>Alternate Name</title>
+ <title>Alternate names</title>
<para><command>di</command></para>
</refsect1>
@@ -1976,7 +1976,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>For obtaining differences against anything but
<literal>BASE</literal> revision in your working copy</para>
</refsect1>
@@ -2017,7 +2017,7 @@
</screen>
<para>See what changed in the file
- <literal>COMMITTERS</literal> revision 9115:</para>
+ <filename>COMMITTERS</filename> revision 9115:</para>
<screen>
$ svn diff -c 9115 COMMITTERS
@@ -2109,7 +2109,7 @@
<para>Lastly, you can use the <option>--xml</option> option
along with the <option>--summarize</option> option to view
- xml describing the changes that occurred between
+ XML describing the changes that occurred between
revisions, but not the contents of the diff itself:</para>
<screen>
@@ -2158,8 +2158,8 @@
<title>Description</title>
<para>The first form exports a clean directory tree from the
- repository specified by URL—at revision
- <replaceable>REV</replaceable> if it is given, otherwise
+ repository specified by <replaceable>URL</replaceable>—at revision
+ <replaceable>REV</replaceable> if it is given; otherwise,
at <literal>HEAD</literal>, into
<replaceable>PATH</replaceable>. If
<replaceable>PATH</replaceable> is omitted, the last
@@ -2175,7 +2175,7 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -2185,7 +2185,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if exporting from a URL</para>
</refsect1>
@@ -2224,14 +2224,14 @@
Exported revision 15.
</screen>
- <para>When rolling operating system-specific release
+ <para>When rolling operating-system-specific release
packages, it can be useful to export a tree that uses a
specific EOL character for line endings. The
<option>--native-eol</option> option will do this, but it
affects only files that have <literal>svn:eol-style =
native</literal> properties attached to them. For
example, to export a tree with all CRLF line endings
- (possibly for a Windows <literal>.zip</literal> file
+ (possibly for a Windows <filename>.zip</filename> file
distribution):</para>
<screen>
@@ -2276,8 +2276,8 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>?, h</para>
+ <title>Alternate names</title>
+ <para><command>?</command>, <command>h</command></para>
<para>The options <option>-?</option>, <option>-h</option>,
and <option>--help</option> have the same effect as using the
<command>help</command> subcommand.</para>
@@ -2289,7 +2289,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>No</para>
</refsect1>
@@ -2333,7 +2333,7 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -2343,7 +2343,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -2467,7 +2467,7 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -2477,7 +2477,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if operating on URLs</para>
</refsect1>
@@ -2563,7 +2563,7 @@
</screen>
<para>Lastly, <command>svn info</command> output is
- available in xml format by passing
+ available in XML format by passing
the<option>--xml</option> option:</para>
<screen>
@@ -2635,7 +2635,7 @@
<listitem><para>Author of the last commit</para></listitem>
- <listitem><para>If locked, the letter <quote>O</quote> (See <xref
+ <listitem><para>If locked, the letter <quote>O</quote> (see the preceding section on <xref
linkend="svn.ref.svn.c.info"/> for details).</para></listitem>
<listitem><para>Size (in bytes)</para></listitem>
@@ -2652,8 +2652,8 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>ls</para>
+ <title>Alternate names</title>
+ <para><command>ls</command></para>
</refsect1>
<refsect1>
@@ -2662,7 +2662,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -2706,7 +2706,7 @@
</screen>
<para>You can also get <command>svn list</command> output in
- xml format with the <option>--xml</option> option:</para>
+ XML format with the <option>--xml</option> option:</para>
<screen>
$ svn list --xml http://svn.red-bean.com/repos/test
@@ -2747,7 +2747,7 @@
<refnamediv>
<refname>svn lock</refname>
<refpurpose>Lock working copy paths or URLs in the
- repository, so that no other user can commit changes to
+ repository so that no other user can commit changes to
them.</refpurpose>
</refnamediv>
<refsect1>
@@ -2767,7 +2767,7 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -2777,7 +2777,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -2854,14 +2854,14 @@
<para>Shows log messages from the repository.
If no arguments are supplied, <command>svn
log</command> shows the log messages for all files and
- directories inside of (and including) the current working
+ directories inside (and including) the current working
directory of your working copy. You can refine the
results by specifying a path, one or more revisions, or
any combination of the two. The default revision range
for a local path is <literal>BASE:1</literal>.</para>
- <para>If you specify a URL alone, then it prints log
- messages for everything that the URL contains. If you
+ <para>If you specify a URL alone, it prints log
+ messages for everything the URL contains. If you
add paths past the URL, only messages for those paths
under that URL will be printed. The default revision range
for a URL is <literal>HEAD:1</literal>.</para>
@@ -2881,7 +2881,7 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -2891,7 +2891,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -2918,8 +2918,8 @@
<title>Examples</title>
<para>You can see the log messages for all the paths that
- changed in your working copy by running <command>svn
- log</command> from the top:</para>
+ changed in your working copy by running <userinput>svn
+ log</userinput> from the top:</para>
<screen>
$ svn log
@@ -3005,10 +3005,10 @@
…
</screen>
- <para>There are just a handful of action codes used by
- <command>svn log</command>, and they are similar to the
- ones used by the <command>svn update</command>
- command:</para>
+ <para><command>svn log</command> uses just a handful of action codes,
+ and they are similar to the
+ ones the <command>svn update</command>
+ command uses:</para>
<variablelist>
<varlistentry>
@@ -3032,8 +3032,8 @@
</variablelist>
<para>In addition to the action codes which precede the
- changed paths, <command>svn log --verbose</command> will
- note a path was added or replaced as the result of a copy
+ changed paths, <command>svn log</command> with the <option>--verbose</option> option will
+ note whether a path was added or replaced as the result of a copy
operation. It does so by printing <literal>(from
<replaceable>COPY-FROM-PATH</replaceable>:<replaceable>COPY-FROM-REV</replaceable>)</literal>
after such paths.</para>
@@ -3116,14 +3116,14 @@
<tip>
<para>If you run <command>svn log</command> on a specific
path and provide a specific revision and get no output
- at all as in the following:</para>
+ at all, as in the following:</para>
<screen>
$ svn log -r 20 http://svn.red-bean.com/untouched.txt
------------------------------------------------------------------------
</screen>
- <para>That just means that the path was not modified in
+ <para>that just means the path was not modified in
that revision. If you log from the top of the
repository or know the file that changed in that
revision, you can specify it explicitly:</para>
@@ -3164,7 +3164,7 @@
<title>Description</title>
<para>In the first form, the source URLs are specified at
- revisions <literal>N</literal> and <literal>M</literal>.
+ revisions <replaceable>N</replaceable> and <replaceable>M</replaceable>.
These are the two sources to be compared. The revisions
default to <literal>HEAD</literal> if omitted.</para>
@@ -3204,10 +3204,10 @@
this case, the differences will be applied to that
file.</para>
- <para>Subversion will only internally track metadata about
- the merge operation if the two sources are ancestrally
+ <para>Subversion will internally track metadata about
+ the merge operation only if the two sources are ancestrally
related—if the first source is an ancestor of the
- second or vice-versa. This is guaranteed to be the case
+ second or vice versa. This is guaranteed to be the case
when using the third form. Unlike <command>svn
diff</command>, the merge command takes the ancestry of a
file into consideration when performing a merge operation.
@@ -3217,7 +3217,7 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -3227,7 +3227,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if working with URLs</para>
</refsect1>
@@ -3254,7 +3254,7 @@
<title>Examples</title>
<para>Merge a branch back into the trunk (assuming that
- you have an up to date working copy of the trunk).</para>
+ you have an up-to-date working copy of the trunk):</para>
<screen>
$ svn merge --reintegrate \
@@ -3321,7 +3321,7 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -3331,7 +3331,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -3344,11 +3344,11 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>Find out which changesets your trunk directory has
already received as well as what changesets it's still
- eligible to receive.</para>
+ eligible to receive:</para>
<screen>
$ svn mergeinfo branches/test
@@ -3383,7 +3383,7 @@
<title>Description</title>
<para>Create a directory with a name given by the final
- component of the <replaceable>PATH</replaceable> or URL.
+ component of the <replaceable>PATH</replaceable> or <replaceable>URL</replaceable>.
A directory specified by a working copy
<replaceable>PATH</replaceable> is scheduled for addition
in the working copy. A directory specified by a URL is
@@ -3395,7 +3395,7 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -3405,7 +3405,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if operating on a URL</para>
</refsect1>
@@ -3434,7 +3434,7 @@
A newdir
</screen>
- <para>Create one in the repository (instant commit, so a
+ <para>Create one in the repository (this is an instant commit, so a
log message is required):</para>
<screen>
@@ -3482,7 +3482,8 @@
<para>Subversion does not support moving between working
copies and URLs. In addition, you can only move files
within a single repository—Subversion does not
- support cross-repository moving.</para>
+ support cross-repository moving. Subversion supports
+ the following types of moves within a single repository:</para>
</note>
<variablelist>
@@ -3506,8 +3507,8 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>mv, rename, ren</para>
+ <title>Alternate names</title>
+ <para><command>mv</command>, <command>rename</command>, <command>ren</command></para>
</refsect1>
<refsect1>
@@ -3516,7 +3517,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if operating on a URL</para>
</refsect1>
@@ -3561,7 +3562,7 @@
D qux.c
</screen>
- <para>Move a file in the repository (an immediate commit,
+ <para>Move a file in the repository (this is an immediate commit,
so it requires a commit message):</para>
<screen>
@@ -3596,15 +3597,15 @@
<para>This removes properties from files, directories, or
revisions. The first form removes versioned properties in
- your working copy, while the second removes unversioned
+ your working copy, and the second removes unversioned
remote properties on a repository revision
(<replaceable>TARGET</replaceable> determines only which
repository to access).</para>
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>pdel, pd</para>
+ <title>Alternate names</title>
+ <para><command>pdel</command>, <command>pd</command></para>
</refsect1>
<refsect1>
@@ -3613,7 +3614,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if operating on a URL</para>
</refsect1>
@@ -3637,7 +3638,7 @@
copy:</para>
<screen>
-$ svn propdel svn:mime-type some-script
+$ svn propdel svn:mime-type some-script
property 'svn:mime-type' deleted from 'some-script'.
</screen>
@@ -3663,7 +3664,7 @@
<refname>svn propedit</refname>
<refpurpose>Edit the property of one or more items under
version control. See <xref
- linkend="svn.ref.svn.c.propset"/>.</refpurpose>
+ linkend="svn.ref.svn.c.propset"/> later in this chapter.</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
@@ -3675,15 +3676,15 @@
<para>Edit one or more properties using your favorite
editor. The first form edits versioned properties in
- your working copy, while the second edits unversioned
+ your working copy, and the second edits unversioned
remote properties on a repository revision
(<replaceable>TARGET</replaceable> determines only which
repository to access).</para>
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>pedit, pe</para>
+ <title>Alternate names</title>
+ <para><command>pedit</command>, <command>pe</command></para>
</refsect1>
<refsect1>
@@ -3692,7 +3693,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if operating on a URL</para>
</refsect1>
@@ -3713,7 +3714,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para><command>svn propedit</command> makes it easy to
modify properties that have multiple values:</para>
@@ -3753,15 +3754,15 @@
<para>Print the value of a property on files,
directories, or revisions. The first form prints the
versioned property of an item or items in your working
- copy, while the second prints unversioned remote
- property on a repository revision. See <xref
+ copy, and the second prints unversioned remote
+ properties on a repository revision. See <xref
linkend="svn.advanced.props"/> for more information on
properties.</para>
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>pget, pg</para>
+ <title>Alternate names</title>
+ <para><command>pget</command>, <command>pg</command></para>
</refsect1>
<refsect1>
@@ -3770,7 +3771,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if operating on a URL</para>
</refsect1>
@@ -3809,7 +3810,7 @@
</screen>
<para>Lastly, you can get <command>svn propget</command>
- output in xml format with the <option>--xml</option>
+ output in XML format with the <option>--xml</option>
option:</para>
<screen>
@@ -3850,15 +3851,15 @@
<para>List all properties on files, directories, or
revisions. The first form lists versioned properties in
- your working copy, while the second lists unversioned remote
+ your working copy, and the second lists unversioned remote
properties on a repository revision
(<replaceable>TARGET</replaceable> determines only which
repository to access).</para>
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>plist, pl</para>
+ <title>Alternate names</title>
+ <para><command>plist</command>, <command>pl</command></para>
</refsect1>
<refsect1>
@@ -3867,7 +3868,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if operating on a URL</para>
</refsect1>
@@ -3889,7 +3890,7 @@
<refsect1>
<title>Examples</title>
- <para>You can use proplist to see the properties on an
+ <para>You can use <command>proplist</command> to see the properties on an
item in your working copy:</para>
<screen>
@@ -3900,8 +3901,8 @@
owner
</screen>
- <para>But with the <option>--verbose</option> flag, svn
- proplist is extremely handy as it also shows you the
+ <para>But with the <option>--verbose</option> flag, <command>svn
+ proplist</command> is extremely handy as it also shows you the
values for the properties:</para>
<screen>
@@ -3941,7 +3942,7 @@
<refnamediv>
<refname>svn propset</refname>
- <refpurpose>Set PROPNAME to PROPVAL on files, directories, or revisions.</refpurpose>
+ <refpurpose>Set <replaceable>PROPNAME</replaceable> to <replaceable>PROPVAL</replaceable> on files, directories, or revisions.</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
@@ -3964,14 +3965,14 @@
<tip>
<para>Subversion has a number of <quote>special</quote>
properties that affect its behavior. See <xref
- linkend="svn.ref.properties"/> for more on these
+ linkend="svn.ref.properties"/> later in this chapter for more on these
properties.</para>
</tip>
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>pset, ps</para>
+ <title>Alternate names</title>
+ <para><replaceable>pset</replaceable>, <replaceable>ps</replaceable></para>
</refsect1>
<refsect1>
@@ -3980,7 +3981,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if operating on a URL</para>
</refsect1>
@@ -4004,7 +4005,7 @@
<refsect1>
<title>Examples</title>
- <para>Set the mime type on a file:</para>
+ <para>Set the MIME type for a file:</para>
<screen>
$ svn propset svn:mime-type image/jpeg foo.jpg
@@ -4046,7 +4047,7 @@
property 'svn:log' set on repository revision '25'
</screen>
- <para>Lastly, you can tell propset to take its input from
+ <para>Lastly, you can tell <command>propset</command> to take its input from
a file. You could even use this to set the contents of a
property to something binary:</para>
@@ -4090,7 +4091,7 @@
<para>Resolve <quote>conflicted</quote> state on working
copy files or directories. This routine does not
- semantically resolve conflict markers, however, it
+ semantically resolve conflict markers; however, it
replaces <replaceable>PATH</replaceable> with the version
specified by the <option>--accept</option> argument and
then removes conflict-related artifact files. This allows
@@ -4104,7 +4105,7 @@
<variablelist>
<varlistentry>
- <term>base</term>
+ <term><literal>base</literal></term>
<listitem>
<para>Choose the file that was the
<literal>BASE</literal> revision before you updated
@@ -4115,7 +4116,7 @@
</varlistentry>
<varlistentry>
- <term>working</term>
+ <term><literal>working</literal></term>
<listitem>
<para>Assuming that you've manually handled the
conflict resolution, choose the version of the file as
@@ -4124,7 +4125,7 @@
</varlistentry>
<varlistentry>
- <term>mine-full</term>
+ <term><literal>mine-full</literal></term>
<listitem>
<para>Resolve all conflicted files with copies of the
files as they stood immediately before you
@@ -4133,7 +4134,7 @@
</varlistentry>
<varlistentry>
- <term>theirs-full</term>
+ <term><literal>theirs-full</literal></term>
<listitem>
<para>Resolve all conflicted files with copies of the
files that were fetched from the server when you
@@ -4150,7 +4151,7 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -4160,7 +4161,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>No</para>
</refsect1>
@@ -4177,12 +4178,12 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>Here's an example where, after a postponed conflict
resolution during update, <command>svn resolve</command>
replaces the all conflicts in
- file <literal>foo.c</literal> with your edits:</para>
+ file <filename>foo.c</filename> with your edits:</para>
<screen>
$ svn up
@@ -4221,8 +4222,8 @@
<title>Description</title>
<para>This command has been deprecated in favor of
- running <command>svn resolve --accept working</command>.
- See <xref linkend="svn.ref.svn.c.resolve"/> for
+ running <userinput>svn resolve --accept working <replaceable>PATH</replaceable></userinput>.
+ See <xref linkend="svn.ref.svn.c.resolve"/> in the preceding section for
details.</para>
<para>Remove <quote>conflicted</quote> state on working copy
@@ -4236,7 +4237,7 @@
resolving conflicts.</para> </refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -4246,7 +4247,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>No</para>
</refsect1>
@@ -4262,7 +4263,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>If you get a conflict on an update, your working
copy will sprout three new files:</para>
@@ -4316,16 +4317,16 @@
<para>Reverts any local changes to a file or directory and
resolves any conflicted states. <command>svn
- revert</command> will not only revert the contents of an
+ revert</command> will revert not only the contents of an
item in your working copy, but also any property
changes. Finally, you can use it to undo any scheduling
- operations that you may have done (e.g., files scheduled
+ operations that you may have performed (e.g., files scheduled
for addition or deletion can be
<quote>unscheduled</quote>).</para>
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
@@ -4335,7 +4336,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>No</para>
</refsect1>
@@ -4441,7 +4442,7 @@
about different aspects of each working copy item.</para>
<para>The first column indicates that an item
- was added, deleted, or otherwise changed.</para>
+ was added, deleted, or otherwise changed:</para>
<variablelist>
@@ -4517,7 +4518,7 @@
<varlistentry>
<term><literal>'!'</literal></term>
<listitem>
- <para>Item is missing (e.g. you moved or deleted it
+ <para>Item is missing (e.g., you moved or deleted it
without using <command>svn</command>). This also
indicates that a directory is incomplete (a checkout
or update was interrupted).</para>
@@ -4528,7 +4529,7 @@
<term><literal>'~'</literal></term>
<listitem>
<para>Item is versioned as one kind of object (file,
- directory, link), but has been replaced by different
+ directory, link), but has been replaced by a different
kind of object.</para>
</listitem>
</varlistentry>
@@ -4536,7 +4537,7 @@
</variablelist>
<para>The second column tells the status of a file's or
- directory's properties.</para>
+ directory's properties:</para>
<variablelist>
@@ -4567,8 +4568,8 @@
</variablelist>
<para>The third column is populated only if the
- working copy directory is locked. (See
- <xref linkend="svn.tour.cleanup"/>.)</para>
+ working copy directory is locked (see
+ <xref linkend="svn.tour.cleanup"/>):</para>
<variablelist>
@@ -4589,7 +4590,7 @@
</variablelist>
<para>The fourth column is populated only if the item is
- scheduled for addition-with-history.</para>
+ scheduled for addition-with-history:</para>
<variablelist>
@@ -4611,7 +4612,7 @@
<para>The fifth column is populated only if the item is
switched relative to its parent (see <xref
- linkend="svn.branchmerge.switchwc"/>).</para>
+ linkend="svn.branchmerge.switchwc"/>):</para>
<variablelist>
@@ -4631,7 +4632,7 @@
</variablelist>
- <para>The sixth column is populated with lock information.</para>
+ <para>The sixth column is populated with lock information:</para>
<variablelist>
@@ -4690,7 +4691,7 @@
<para>The out-of-date information appears in the seventh
column (only if you pass the
- <option>--show-updates</option> option).</para>
+ <option>--show-updates</option> option):</para>
<variablelist>
@@ -4714,7 +4715,7 @@
<para>The remaining fields are variable width and
delimited by spaces. The working revision is the next
field if the <option>--show-updates</option> or
- <option>--verbose</option> options are passed.</para>
+ <option>--verbose</option> option is passed.</para>
<para>If the <option>--verbose</option> option is passed,
the last committed revision and last committed author
@@ -4726,8 +4727,8 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>stat, st</para>
+ <title>Alternate names</title>
+ <para><command>stat</command>, <command>st</command></para>
</refsect1>
<refsect1>
@@ -4736,7 +4737,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Only if using <option>--show-updates</option></para>
</refsect1>
@@ -4769,7 +4770,7 @@
</screen>
<para>If you want to find out what files in your working
- copy are out-of-date, pass the
+ copy are out of date, pass the
<option>--show-updates</option> option (this will
<emphasis>not</emphasis> make any changes to your
working copy). Here you can see that
@@ -4788,8 +4789,8 @@
<note>
<para><option>--show-updates</option>
<emphasis>only</emphasis> places an asterisk next to
- items that are out of date (that is, items that will be
- updated from the repository if you run <command>svn
+ items that are out of date (i.e., items that will be
+ updated from the repository if you later use <command>svn
update</command>). <option>--show-updates</option> does
<emphasis>not</emphasis> cause the status listing to
reflect the repository's version of the item (although
@@ -4797,7 +4798,7 @@
passing the <option>--verbose</option> option).</para>
</note>
- <para>And finally, the most information you can get out of
+ <para>The most information you can get out of
the status subcommand is as follows:</para>
<screen>
@@ -4810,7 +4811,7 @@
</screen>
<para>Lastly, you can get <command>svn status</command>
- output in xml format with the <option>--xml</option>
+ output in XML format with the <option>--xml</option>
option:</para>
<screen>
@@ -4901,7 +4902,7 @@
<para>As with most subcommands, you can limit the scope of
the switch operation to a particular tree depth using the
<option>--depth</option> option. Alternatively, you can
- use the --set-depth option to set a new
+ use the <option>--set-depth</option> option to set a new
<quote>sticky</quote> working copy depth on the switch
target. Currently, the depth of a working copy directory
can only be increased (telescoped more deeply); you cannot
@@ -4918,8 +4919,8 @@
</refsect1>
<refsect1>
- <title>Alternate Name</title>
- <para>sw</para>
+ <title>Alternate names</title>
+ <para><command>sw</command></para>
</refsect1>
<refsect1>
@@ -4928,7 +4929,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -4965,7 +4966,7 @@
Updated to revision 31.
</screen>
- <para>And to switch back, just provide the URL to the
+ <para>To switch back, just provide the URL to the
location in the repository from which you originally
checked out your working copy:</para>
@@ -4979,7 +4980,7 @@
</screen>
<tip>
- <para>You can just switch part of your working copy to a
+ <para>You can switch just part of your working copy to a
branch if you don't want to switch your entire working
copy.</para>
</tip>
@@ -5033,13 +5034,13 @@
<itemizedlist>
<listitem><para>If the working copy needs to reflect a
new directory <emphasis>within</emphasis> the
- repository, then use just <command>svn
+ repository, use just <command>svn
switch</command>.</para></listitem>
<listitem><para>If the working copy still reflects the
same repository directory, but the location of the
- repository itself has changed, then use <command>svn
- switch --relocate</command>.</para></listitem>
+ repository itself has changed, use <command>svn
+ switch</command> with the <option>--relocate</option> option.</para></listitem>
</itemizedlist>
</warning>
@@ -5067,7 +5068,7 @@
<title>Description</title>
<para>Unlock each <replaceable>TARGET</replaceable>. If any
- <replaceable>TARGET</replaceable> is either locked by
+ <replaceable>TARGET</replaceable> is locked by
another user or no valid lock token exists in the working
copy, print a warning and continue unlocking the rest of
the <replaceable>TARGET</replaceable>s. Use
@@ -5077,17 +5078,17 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
+ <title>Alternate names</title>
<para>None</para>
</refsect1>
<refsect1>
<title>Changes</title>
- <para>Working Copy, Repository</para>
+ <para>Working copy, repository</para>
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -5181,7 +5182,7 @@
<varlistentry>
<term><literal>B</literal></term>
<listitem>
- <para>Broken Lock (third column only)</para>
+ <para>Broken lock (third column only)</para>
</listitem>
</varlistentry>
@@ -5223,14 +5224,14 @@
</variablelist>
<para>A character in the first column signifies an update to
- the actual file, while updates to the file's properties
+ the actual file, whereas updates to the file's properties
are shown in the second column. Lock information is
printed in the third column.</para>
<para>As with most subcommands, you can limit the scope of
the update operation to a particular tree depth using the
<option>--depth</option> option. Alternatively, you can
- use the --set-depth option to set a new
+ use the <option>--set-depth</option> option to set a new
<quote>sticky</quote> working copy depth on the update
target. Currently, the depth of a working copy directory
can only be increased (telescoped more deeply); you cannot
@@ -5238,7 +5239,7 @@
</refsect1>
<refsect1>
- <title>Alternate Name</title>
+ <title>Alternate names</title>
<para><command>up</command></para>
</refsect1>
@@ -5248,7 +5249,7 @@
</refsect1>
<refsect1>
- <title>Accesses Repository</title>
+ <title>Accesses repository</title>
<para>Yes</para>
</refsect1>
@@ -5270,7 +5271,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>Pick up repository changes that have happened since
your last update:</para>
@@ -5316,11 +5317,11 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.ref.svnadmin">
- <title><command>svnadmin</command></title>
+ <title>svnadmin</title>
<para><command>svnadmin</command> is the administrative tool for
monitoring and repairing your Subversion repository. For
- detailed information, see the maintenance section for <xref
+ detailed information on repository administration, see the maintenance section for <xref
linkend="svn.reposadmin.maint.tk.svnadmin"/>.</para>
<para>Since <command>svnadmin</command> works via direct repository access
@@ -5331,13 +5332,16 @@
<sect2 id="svn.ref.svnadmin.sw">
<title><command>svnadmin</command> Options</title>
+ <para>Options in <command>svmadin</command> are global, just
+ as they are in <command>svn</command>:</para>
+
<variablelist>
<varlistentry>
<term><option>--bdb-log-keep</option></term>
<listitem>
<para>(Berkeley DB-specific.) Disable automatic log removal
- of database log files. Having these log files around
+ of database logfiles. Having these logfiles around
can be convenient if you need to restore from a
catastrophic repository failure.</para>
</listitem>
@@ -5370,7 +5374,8 @@
</listitem>
</varlistentry>
- <!-- TODO config-dir? Is it really used? -->
+ <!-- TODO config-dir? Only 'svnadmin create' accepts it, and -->
+ <!-- the underlying logic doesn't even use it. -->
<varlistentry>
<term><option>--force-uuid</option></term>
@@ -5453,8 +5458,8 @@
<varlistentry>
<term><option>--use-post-commit-hook</option></term>
<listitem>
- <para>When loading a dump file, run the repository's
- post-commit hook after finalizing each newly loaded
+ <para>When loading a dump file, runs the repository's
+ <literal>post-commit</literal> hook after finalizing each newly loaded
revision.</para>
</listitem>
</varlistentry>
@@ -5462,8 +5467,8 @@
<varlistentry>
<term><option>--use-post-revprop-change-hook</option></term>
<listitem>
- <para>When changing a revision property, run the
- repository's post-revprop-change hook after changing the
+ <para>When changing a revision property, runs the
+ repository's <literal>post-revprop-change</literal> hook after changing the
revision property.</para>
</listitem>
</varlistentry>
@@ -5471,20 +5476,20 @@
<varlistentry>
<term><option>--use-pre-commit-hook</option></term>
<listitem>
- <para>When loading a dump file, run the repository's
- pre-commit hook before finalizing each newly loaded
- revision. If the hook fails, abort the commit and
- terminate the load process.</para>
+ <para>When loading a dump file, runs the repository's
+ <literal>pre-commit</literal> hook before finalizing each newly loaded
+ revision. If the hook fails, aborts the commit and
+ terminates the load process.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--use-pre-revprop-change-hook</option></term>
<listitem>
- <para>When changing a revision property, run the
- repository's pre-revprop-change hook before changing the
- revision property. If the hook fails, abort the
- modification and terminate.</para>
+ <para>When changing a revision property, runs the
+ repository's <literal>pre-revprop-change</literal> hook before changing the
+ revision property. If the hook fails, aborts the
+ modification and terminates.</para>
</listitem>
</varlistentry>
@@ -5493,7 +5498,10 @@
<!-- =============================================================== -->
<sect2 id="svn.ref.svnadmin.c">
- <title><command>svnadmin</command> Subcommands</title>
+ <title>svnadmin Subcommands</title>
+
+ <para>Here are the various subcommands
+ for the <command>svnadmin</command> program.</para>
<refentry id="svn.ref.svnadmin.c.crashtest">
@@ -5514,7 +5522,7 @@
<refsect1>
<title>Description</title>
- <para>Open the repository at REPOS_PATH, then abort, thus
+ <para>Open the repository at <replaceable>REPOS_PATH</replaceable>, then abort, thus
simulating a process that crashes while holding an open
repository handle. This is used for testing automatic
repository recovery (a new feature in Berkeley DB 4.4).
@@ -5572,7 +5580,7 @@
</footnote>
As of Subversion 1.2, <command>svnadmin</command>
creates new repositories with the
- <literal>fsfs</literal> filesystem backend by
+ <literal>FSFS</literal> filesystem backend by
default.</para>
<para>While <command>svnadmin create</command> will create
@@ -5603,7 +5611,7 @@
<refsect1>
<title>Examples</title>
- <para>Creating a new repository is just this easy:</para>
+ <para>Creating a new repository is this easy:</para>
<screen>
$ svnadmin create /var/svn/repos
@@ -5672,7 +5680,7 @@
<refnamediv>
<refname>svnadmin dump</refname>
- <refpurpose>Dump the contents of filesystem to stdout.</refpurpose>
+ <refpurpose>Dump the contents of the filesystem to <filename>stdout</filename>.</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
@@ -5681,9 +5689,9 @@
<refsect1>
<title>Description</title>
- <para>Dump the contents of filesystem to stdout in a
- <quote>dumpfile</quote> portable format, sending feedback
- to stderr. Dump revisions
+ <para>Dump the contents of the filesystem to <filename>stdout</filename> in a
+ <quote>dump file</quote> portable format, sending feedback
+ to <filename>stderr</filename>. Dump revisions
<replaceable>LOWER</replaceable> rev through
<replaceable>UPPER</replaceable> rev. If no revisions are
given, dump all revision trees. If only
@@ -5691,39 +5699,39 @@
revision tree. See <xref linkend="svn.reposadmin.maint.migrate"/>
for a practical use.</para>
- <para>By default, the Subversion dumpfile stream contains a
+ <para>By default, the Subversion dump stream contains a
single revision (the first revision in the requested
revision range) in which every file and directory in the
- repository in that revision is presented as if that whole
+ repository in that revision is presented as though that whole
tree was added at once, followed by other revisions (the
remainder of the revisions in the requested range), which
contain only the files and directories that were modified
in those revisions. For a modified file, the complete
- fulltext representation of its contents, as well as all of
- its properties, are presented in the dumpfile; for a
+ full-text representation of its contents, as well as all of
+ its properties, are presented in the dump file; for a
directory, all of its properties are presented.</para>
- <para>There are two useful options that modify the dumpfile
+ <para>Two useful options modify the dump file
generator's behavior. The first is the
<option>--incremental</option> option, which simply causes
- that first revision in the dumpfile stream to contain only
+ that first revision in the dump stream to contain only
the files and directories modified in that revision,
instead of being presented as the addition of a new tree,
and in exactly the same way that every other revision in
- the dumpfile is presented. This is useful for generating
- a relatively small dumpfile to be loaded into another
+ the dump file is presented. This is useful for generating
+ a relatively small dump file to be loaded into another
repository that already has the files and directories
that exist in the original repository.</para>
<para>The second useful option is <option>--deltas</option>.
This option causes <command>svnadmin dump</command> to,
- instead of emitting fulltext representations of file
+ instead of emitting full-text representations of file
contents and property lists, emit only deltas of those
items against their previous versions. This reduces (in
- some cases, drastically) the size of the dumpfile that
+ some cases, drastically) the size of the dump file that
<command>svnadmin dump</command> creates. There are, however,
disadvantages to using this option—deltified
- dumpfiles are more CPU-intensive to create, cannot be
+ dump files are more CPU-intensive to create, cannot be
operated on by <command>svndumpfilter</command>, and tend
not to compress as well as their nondeltified counterparts
when using third-party tools such as <command>gzip</command>
@@ -5784,13 +5792,13 @@
<title>Description</title>
<para>This subcommand is useful when you're trapped on a
- desert island with neither a net connection nor a copy of
+ desert island with neither a Net connection nor a copy of
this book.</para>
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>?, h</para>
+ <title>Alternate names</title>
+ <para><command>?</command>, <command>h</command></para>
</refsect1>
</refentry>
@@ -5819,7 +5827,7 @@
of your repository, including all hooks, configuration
files, and, of course, database files. If you pass the
<option>--clean-logs</option> option,
- <command>svnadmin</command> will perform a hotcopy of your
+ <command>svnadmin</command> will perform a hot copy of your
repository, and then remove unused Berkeley DB logs from
the original repository. You can run this command at any
time and make a safe copy of the repository, regardless of
@@ -5857,7 +5865,7 @@
<refnamediv>
<refname>svnadmin list-dblogs</refname>
- <refpurpose>Ask Berkeley DB which log files exist for a
+ <refpurpose>Ask Berkeley DB which logfiles exist for a
given Subversion repository (applies only to repositories
using the <literal>bdb</literal> backend).</refpurpose>
</refnamediv>
@@ -5871,7 +5879,7 @@
<para>Berkeley DB creates logs of all changes to the
repository, which allow it to recover in the face of
catastrophe. Unless you enable
- <literal>DB_LOG_AUTOREMOVE</literal>, the log files
+ <literal>DB_LOG_AUTOREMOVE</literal>, the logfiles
accumulate, although most are no longer used and can be
deleted to reclaim disk space. See <xref
linkend="svn.reposadmin.maint.diskspace"/> for more
@@ -5890,7 +5898,7 @@
<refnamediv>
<refname>svnadmin list-unused-dblogs</refname>
- <refpurpose>Ask Berkeley DB which log files can be safely
+ <refpurpose>Ask Berkeley DB which logfiles can be safely
deleted (applies only to repositories using the
<literal>bdb</literal> backend).</refpurpose>
</refnamediv>
@@ -5904,7 +5912,7 @@
<para>Berkeley DB creates logs of all changes to the
repository, which allow it to recover in the face of
catastrophe. Unless you enable
- <literal>DB_LOG_AUTOREMOVE</literal>, the log files
+ <literal>DB_LOG_AUTOREMOVE</literal>, the logfiles
accumulate, although most are no longer used and can be
deleted to reclaim disk space. See <xref
linkend="svn.reposadmin.maint.diskspace"/> for more
@@ -5912,9 +5920,9 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
- <para>Remove all unused log files from the repository:</para>
+ <para>Remove all unused logfiles from the repository:</para>
<screen>
$ svnadmin list-unused-dblogs /var/svn/repos
@@ -5939,8 +5947,8 @@
<refnamediv>
<refname>svnadmin load</refname> <refpurpose>Read a
- <quote>dumpfile</quote>-formatted stream from
- stdin.</refpurpose>
+ repository dump stream from
+ <filename>stdin</filename>.</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
@@ -5949,9 +5957,9 @@
<refsect1>
<title>Description</title>
- <para>Read a <quote>dumpfile</quote>-formatted stream from
- stdin, committing new revisions into the repository's
- filesystem. Send progress feedback to stdout.</para>
+ <para>Read a repository dump stream from
+ <filename>stdin</filename>, committing new revisions into the repository's
+ filesystem. Send progress feedback to <filename>stdout</filename>.</para>
</refsect1>
<refsect1>
@@ -6031,7 +6039,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This lists the one locked file in the repository at
@@ -6076,10 +6084,10 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>List all outstanding transactions in a
- repository.</para>
+ repository:</para>
<screen>
$ svnadmin lstxns /var/svn/repos/
@@ -6105,7 +6113,7 @@
consistent state (applies only to repositories using the
<literal>bdb</literal> backend). In addition, if
<filename>repos/conf/passwd</filename> does not exist, it
- will create a default password file .</refpurpose>
+ will create a default passwordfile .</refpurpose>
</refnamediv>
<refsect1>
@@ -6140,7 +6148,7 @@
<para>Recovering the database requires an exclusive lock on
the repository. (This is a <quote>database lock</quote>;
- see <xref linkend="svn.advanced.locking.meanings"/>.)
+ see the sidebar <xref linkend="svn.advanced.locking.meanings"/>.)
If another process is accessing the repository,
then <command>svnadmin recover</command> will error:</para>
<screen>
@@ -6192,7 +6200,7 @@
<refsect1>
<title>Description</title>
- <para>Remove lock from each <replaceable>LOCKED_PATH</replaceable>.</para>
+ <para>Remove one or more locks from each <replaceable>LOCKED_PATH</replaceable>.</para>
</refsect1>
<refsect1>
@@ -6202,7 +6210,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This deletes the locks on
<filename>tree.jpg</filename> and
@@ -6296,8 +6304,8 @@
revision <replaceable>REVISION</replaceable> to the
contents of <replaceable>FILE</replaceable>.</para>
- <para>This is similar to using <command>svn propset
- --revprop</command> to set the <literal>svn:log</literal> property
+ <para>This is similar to using <command>svn propset</command>
+ with the <option>--revprop</option> option to set the <literal>svn:log</literal> property
on a revision, except that you can also use the option
<option>--bypass-hooks</option> to avoid running any pre-
or post-commit hooks, which is useful if the modification
@@ -6322,7 +6330,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>Set the log message for revision 19 to the contents of
the file <filename>msg</filename>:</para>
@@ -6344,7 +6352,7 @@
<refnamediv>
<refname>svnadmin setrevprop</refname>
- <refpurpose>Set the property name on a revision.</refpurpose>
+ <refpurpose>Set a property on a revision.</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
@@ -6359,8 +6367,7 @@
<option>--use-pre-revprop-change-hook</option>
or <option>--use-post-revprop-change-hook</option> to
trigger the revision property-related hooks (e.g., if
- you want an email notification sent from your post
- revprop change hook).</para>
+ you want an email notification sent from your <literal>post-revprop-change-hook</literal>).</para>
</refsect1>
@@ -6379,7 +6386,7 @@
<para>The following sets the revision
property <literal>repository-photo</literal> to the contents
- of the file <literal>sandwich.png</literal>:</para>
+ of the file <filename>sandwich.png</filename>:</para>
<screen>
$svnadmin setrevprop /var/svn/repos -r 0 repository-photo sandwich.png
@@ -6414,7 +6421,7 @@
at <replaceable>REPOS_PATH</replaceable>.
If <replaceable>NEW_UUID</replaceable> is provided, use
that as the new repository UUID; otherwise, generate a
- brand new UUID for the repository.</para>
+ brand-new UUID for the repository.</para>
</refsect1>
@@ -6428,11 +6435,11 @@
<refsect1>
<title>Examples</title>
- <para>If you've <command>svnsync</command>ed /var/svn/repos
- to /var/svn/repos-new and intend to use repos-new as your
+ <para>If you've <command>svnsync</command>ed <filename>/var/svn/repos</filename>
+ to <filename>/var/svn/repos-new</filename> and intend to use <filename>repos-new</filename> as your
canonical repository, you may want to change the UUID for
- repos-new to the UUID of repos so that your users don't
- have to check out a new working copy to accomodate the
+ <filename>repos-new</filename> to the UUID of <filename>repos</filename> so that your users don't
+ have to check out a new working copy to accommodate the
change:</para>
<screen>
@@ -6476,12 +6483,12 @@
operation. As such, the upgrade performs only the
minimum amount of work needed to accomplish this while
still maintaining the integrity of the repository.
- While a dump and subsequent load guarantees the most
+ While a dump and subsequent load guarantee the most
optimized repository state, <command>svnadmin
upgrade</command> does not.</para>
<warning>
- <para>You should <emphasis>always</emphasis> backup your
+ <para>You should <emphasis>always</emphasis> back up your
repository before upgrading.</para>
</warning>
@@ -6498,7 +6505,7 @@
<title>Examples</title>
<para>Upgrade the repository at
- path <filename>/var/repos/svn</filename></para>
+ path <filename>/var/repos/svn</filename>:</para>
<screen>
$ svnadmin upgrade /var/repos/svn
@@ -6539,7 +6546,7 @@
to run this on a regular basis to guard against latent
hard disk failures and <quote>bitrot.</quote> If this
command fails—which it will do at the first sign of
- a problem—that means that your repository has at
+ a problem—that means your repository has at
least one corrupted revision, and you should restore the
corrupted revision from a backup (you did make a backup,
didn't you?).</para>
@@ -6556,7 +6563,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>Verify a hung repository:</para>
@@ -6576,7 +6583,7 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.ref.svnlook">
- <title><command>svnlook</command></title>
+ <title>svnlook</title>
<para><command>svnlook</command> is a command-line utility for
examining different aspects of a Subversion repository. It
@@ -6587,7 +6594,7 @@
useful for diagnostic purposes.</para>
<para>Since <command>svnlook</command> works via direct repository access
- (and thus can only be used on the machine that holds the
+ (and thus can be used only on the machine that holds the
repository), it refers to the repository with a path, not a URL.</para>
<para>If no revision or transaction is specified,
@@ -6596,18 +6603,26 @@
<!-- =============================================================== -->
<sect2 id="svn.ref.svnlook.sw">
- <title><command>svnlook</command> Options</title>
+ <title>svnlook Options</title>
<para>Options in <command>svnlook</command> are global, just
- like in <command>svn</command> and
+ as they are in <command>svn</command> and
<command>svnadmin</command>; however, most options apply
- only to one subcommand since the functionality of
+ to only one subcommand since the functionality of
<command>svnlook</command> is (intentionally) limited in
- scope.</para>
+ scope:</para>
<variablelist>
<varlistentry>
+ <term><option>--copy-info</option></term>
+ <listitem>
+ <para>Causes <command>svnlook changed</command> to show
+ detailed copy source information.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>--no-diff-deleted</option></term>
<listitem>
<para>Prevents <command>svnlook diff</command> from printing
@@ -6633,7 +6648,7 @@
<term><option>--revision</option>
(<option>-r</option>)</term>
<listitem>
- <para>Specify a particular revision number that you wish
+ <para>Specifies a particular revision number that you wish
to examine.</para>
</listitem>
</varlistentry>
@@ -6653,7 +6668,7 @@
<term><option>--transaction</option>
(<option>-t</option>)</term>
<listitem>
- <para>Specify a particular transaction ID that you wish to
+ <para>Specifies a particular transaction ID that you wish to
examine.</para>
</listitem>
</varlistentry>
@@ -6661,7 +6676,7 @@
<varlistentry>
<term><option>--show-ids</option></term>
<listitem>
- <para>Show the filesystem node revision IDs for each path in the filesystem
+ <para>Shows the filesystem node revision IDs for each path in the filesystem
tree.</para>
</listitem>
</varlistentry>
@@ -6672,7 +6687,10 @@
<!-- =============================================================== -->
<sect2 id="svn.ref.svnlook.c">
- <title><command>svnlook</command> Subcommands</title>
+ <title>svnlook Subcommands</title>
+
+ <para>Here are the various subcommands
+ for the <command>svnlook</command> program.</para>
<refentry id="svn.ref.svnlook.c.author">
@@ -6753,7 +6771,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This shows the contents of a file in transaction
<literal>ax8</literal>, located at
@@ -6859,7 +6877,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This shows a list of all the changed files and
directories in revision 39 of a test repository. Note
@@ -6887,7 +6905,7 @@
D trunk/vendors/baker/bread.txt
</screen>
- <para>Unfortunately, nothing in the previous output reveals
+ <para>Unfortunately, nothing in the preceding output reveals
the connection between the deleted and added files. Use
the <option>--copy-info</option> option to make this
relationship more apparent:</para>
@@ -6935,7 +6953,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This shows the date of revision 40 of a test
repository:</para>
@@ -6984,7 +7002,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This shows a newly added (empty) file, a deleted
file, and a copied file:</para>
@@ -7015,7 +7033,7 @@
</screen>
<para>If a file has a nontextual
- <literal>svn:mime-type</literal> property, then the
+ <literal>svn:mime-type</literal> property, the
differences are not explicitly shown.</para>
</refsect1>
</refentry>
@@ -7054,7 +7072,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This shows the directories that changed in
revision 40 in our sample repository:</para>
@@ -7087,7 +7105,7 @@
<para>Displays the help message
for <command>svnlook</command>. This command, like its
- brother <command>svn help</command>, is also your friend,
+ brother, <command>svn help</command>, is also your friend,
even though you never call it anymore and forgot to invite
it to your last party.</para>
</refsect1>
@@ -7098,8 +7116,8 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>?, h</para>
+ <title>Alternate names</title>
+ <para><command>?</command>, <command>h</command></para>
</refsect1>
</refentry>
@@ -7141,7 +7159,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This shows the history output for the path
<filename>/branches/bookstore</filename> as of revision 13 in our
@@ -7202,7 +7220,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This shows the info output for revision 40 in our
sample repository:</para>
@@ -7252,7 +7270,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This describes the lock on the file
<filename>tree.jpg</filename>:</para>
@@ -7304,7 +7322,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This shows the log output for revision 40 in our sample
repository:</para>
@@ -7343,8 +7361,8 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>pg, pget</para>
+ <title>Alternate names</title>
+ <para><command>pg</command>, <command>pget</command></para>
</refsect1>
<refsect1>
@@ -7358,7 +7376,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This shows the value of the <quote>seasonings</quote> property
on the file <filename>/trunk/sandwich</filename> in the
@@ -7398,8 +7416,8 @@
</refsect1>
<refsect1>
- <title>Alternate Names</title>
- <para>pl, plist</para>
+ <title>Alternate names</title>
+ <para><command>pl</command>, <command>plist</command></para>
</refsect1>
<refsect1>
@@ -7426,7 +7444,7 @@
svn:mime-type
</screen>
- <para>This is the same command as in the previous example,
+ <para>This is the same command as in the preceding example,
but this time showing the property values as well:</para>
<screen>
@@ -7530,7 +7548,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<screen>
$ svnlook uuid /var/svn/repos
@@ -7568,7 +7586,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>This shows the youngest revision of our sample
repository:</para>
@@ -7589,7 +7607,7 @@
<!-- ================================================================= -->
<sect1 id="svn.ref.svnsync">
- <title><command>svnsync</command></title>
+ <title>svnsync</title>
<para><command>svnsync</command> is the Subversion remote
repository mirroring tool. Put simply, it allows you to replay
@@ -7618,7 +7636,11 @@
<!-- =============================================================== -->
<sect2 id="svn.ref.svnsync.sw">
- <title><command>svnsync</command> Options</title>
+ <title>svnsync Options</title>
+
+ <para>Options in <command>svnsync</command> are global, just
+ as they are in <command>svn</command> and
+ <command>svnadmin</command>:</para>
<variablelist>
@@ -7648,13 +7670,21 @@
<para>In the case of an authentication failure or
insufficient credentials, prevents prompting for
credentials (e.g., username or password). This is useful
- if you're running Subversion inside of an automated
+ if you're running Subversion inside an automated
script and it's more appropriate to have Subversion fail
than to prompt for more information.</para>
</listitem>
</varlistentry>
<varlistentry>
+ <term><option>--quiet</option> (<option>-q</option>)</term>
+ <listitem>
+ <para>Requests that the client print only essential
+ information while performing an operation.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>--source-password</option>
<replaceable>PASSWD</replaceable></term>
<listitem>
@@ -7678,7 +7708,7 @@
<varlistentry>
<term><option>--sync-password</option>
- <replaceable>PASS</replaceable></term>
+ <replaceable>PASSWD</replaceable></term>
<listitem>
<para>Specifies the password for the Subversion server to
which you are syncing. If not provided, or if
@@ -7704,9 +7734,10 @@
<!-- =============================================================== -->
<sect2 id="svn.ref.svnsync.c">
- <title><command>svnsync</command> Subcommands</title>
+ <title>svnsync Subcommands</title>
- <para>The following lists the various subcommands.</para>
+ <para>Here are the various subcommands
+ for the <command>svnsync</command> program.</para>
<refentry id="svn.ref.svnsync.c.copy-revprops">
@@ -7745,10 +7776,14 @@
</refsect1>
<refsect1>
+ <title>Alternate name</title>
+ <para>None</para>
+ </refsect1>
+
+ <refsect1>
<title>Options</title>
<screen>
---config-dir ARG
--config-dir DIR
--no-auth-cache
--non-interactive
@@ -7761,7 +7796,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>Resynchronize revision properties for a single revision:</para>
@@ -7788,14 +7823,14 @@
<refsect1>
<title>Synopsis</title>
- <programlisting>svnsync SUBCOMMAND</programlisting>
+ <programlisting>svnsync help</programlisting>
</refsect1>
<refsect1>
<title>Description</title>
<para>This subcommand is useful when you're trapped in a
- foreign prison with neither a net connection nor a copy of
- this book, but you do have a local wifi network running
+ foreign prison with neither a Net connection nor a copy of
+ this book, but you do have a local Wi-Fi network running
and you'd like to sync a copy of your repository over to
the backup server that Ira The Knife is running over in
cell block D.</para>
@@ -7803,7 +7838,7 @@
</refsect1>
<refsect1>
- <title>Alternate Name</title>
+ <title>Alternate name</title>
<para>None</para>
</refsect1>
@@ -7824,12 +7859,12 @@
<refnamediv>
<refname>svnsync initialize</refname>
- <refpurpose>Initialize a destination repository for
- synchronization from another repository.</refpurpose>
+ <refpurpose>Initialize a mirror repository for
+ synchronization from the source repository.</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
- <programlisting>svnsync initialize DEST_URL SOURCE_URL</programlisting>
+ <programlisting>svnsync initialize MIRROR_URL SOURCE_URL</programlisting>
</refsect1>
<refsect1>
<title>Description</title>
@@ -7846,8 +7881,8 @@
</refsect1>
<refsect1>
- <title>Alternate Name</title>
- <para>init</para>
+ <title>Alternate name</title>
+ <para><command>init</command></para>
</refsect1>
<refsect1>
@@ -7857,6 +7892,7 @@
--config-dir DIR
--no-auth-cache
--non-interactive
+--quiet (-q)
--source-password ARG
--source-username ARG
--sync-password ARG
@@ -7914,16 +7950,22 @@
does all the heavy lifting of a repository mirroring
operation. After consulting with the mirror repository to
see which revisions have already been copied into it, it
- then begins copying any not-yet-mirrored revisions from
+ then begins to copy any not-yet-mirrored revisions from
the source repository.</para>
<para><command>svnsync synchronize</command> can be
- gracefully cancelled and restarted.</para>
+ gracefully canceled and restarted.</para>
+
+ <para>As of Subversion 1.5, you can limit <command>svnsync</command> to a
+ subdirectory of the source repository by specifying the
+ subdirectory as part of
+ the <replaceable>SOURCE_URL</replaceable>.</para>
+
</refsect1>
<refsect1>
- <title>Alternate Name</title>
- <para>sync</para>
+ <title>Alternate name</title>
+ <para><command>sync</command></para>
</refsect1>
<refsect1>
@@ -7933,6 +7975,7 @@
--config-dir DIR
--no-auth-cache
--non-interactive
+--quiet (-q)
--source-password ARG
--source-username ARG
--sync-password ARG
@@ -7941,7 +7984,7 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<para>Copy unsynchronized revisions from the source
repository to the mirror repository:</para>
@@ -7976,7 +8019,7 @@
<!-- ================================================================= -->
<sect1 id="svn.ref.svnserve">
- <title><command>svnserve</command></title>
+ <title>svnserve</title>
<para><command>svnserve</command> allows access to Subversion
repositories using Subversion's custom network protocol.</para>
@@ -8002,7 +8045,7 @@
<!-- =============================================================== -->
<sect2 id="svn.ref.svnserve.sw">
- <title><command>svnserve</command> Options</title>
+ <title>svnserve Options</title>
<para>Unlike the previous commands we've
described, <command>svnserve</command> has no
@@ -8025,8 +8068,8 @@
<varlistentry>
<term><option>--foreground</option></term>
<listitem>
- <para>When used together with <option>-d</option>, this
- option causes <command>svnserve</command> to stay in the
+ <para>When used together with <option>-d</option>,
+ causes <command>svnserve</command> to stay in the
foreground. This is mainly useful for debugging.</para>
</listitem>
</varlistentry>
@@ -8035,7 +8078,7 @@
<term><option>--inetd</option> (<option>-i</option>)</term>
<listitem>
<para>Causes <command>svnserve</command> to use the
- stdin/stdout file descriptors, as is appropriate for a
+ <filename>stdin</filename> and <filename>stdout</filename> file descriptors, as is appropriate for a
daemon running out of <command>inetd</command>.</para>
</listitem>
</varlistentry>
@@ -8069,7 +8112,7 @@
<varlistentry>
<term><option>--listen-port</option>=<replaceable>PORT</replaceable></term>
<listitem>
- <para>Causes svnserve to listen on
+ <para>Causes <command>svnserve</command> to listen on
<replaceable>PORT</replaceable> when run in daemon mode.
(FreeBSD daemons listen only on tcp6 by default—this
option tells them to also listen on tcp4.)</para>
@@ -8081,7 +8124,7 @@
<listitem>
<para>Causes <command>svnserve</command> to write its
process ID to <replaceable>FILENAME</replaceable>, which
- must be writeable by the user under
+ must be writable by the user under
which <command>svnserve</command> is running.</para>
</listitem>
</varlistentry>
@@ -8115,13 +8158,13 @@
<para>Causes <command>svnserve</command> to run in tunnel
mode, which is just like the <command>inetd</command>
mode of operation (both modes serve one connection over
- stdin/stdout, and then exit), except that the connection
+ <filename>stdin</filename>/<filename>stdout</filename>, and then exit), except that the connection
is considered to be preauthenticated with the username
of the current UID. This flag is automatically passed
for you by the client when running over a tunnel agent
such as <command>ssh</command>. That means there's
rarely any need for <emphasis>you</emphasis> to pass
- this option to <command>svnserve</command>. So if you
+ this option to <command>svnserve</command>. So, if you
find yourself
typing <literal>svnserve --tunnel</literal> on the
command line and wondering what to do next, see
@@ -8134,11 +8177,11 @@
<term><option>--tunnel-user NAME</option></term>
<listitem>
<para>Used in conjunction with the <option>--tunnel</option>
- option; tells svnserve to assume that
+ option, tells <command>svnserve</command> to assume that
<replaceable>NAME</replaceable> is the authenticated
- user, rather than the UID of the svnserve
- process. Useful for users wishing to share a single
- system account over SSH, but maintaining separate commit
+ user, rather than the UID of the <command>svnserve</command>
+ process. This is useful for users wishing to share a single
+ system account over SSH, but to maintain separate commit
identities.</para>
</listitem>
</varlistentry>
@@ -8161,21 +8204,21 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.ref.svndumpfilter">
- <title><command>svndumpfilter</command></title>
+ <title>svndumpfilter</title>
<para><command>svndumpfilter</command> is a command-line utility
- for removing history from a Subversion dumpfile by either
+ for removing history from a Subversion dump file by either
excluding or including paths beginning with one or more named
prefixes. For details, see
<xref linkend="svn.reposadmin.maint.tk.svndumpfilter"/>.</para>
<!-- =============================================================== -->
<sect2 id="svn.ref.svndumpfilter.options">
- <title><command>svndumpfilter</command> Options</title>
+ <title>svndumpfilter Options</title>
<para>Options in <command>svndumpfilter</command> are global, just
- like in <command>svn</command> and
- <command>svnadmin</command>.</para>
+ as they are in <command>svn</command> and
+ <command>svnadmin</command>:</para>
<variablelist>
@@ -8183,15 +8226,15 @@
<term><option>--drop-empty-revs</option></term>
<listitem>
<para>If filtering causes any revision to be empty (i.e.,
- cause no change to the repository), remove these
- revisions from the final dumpfile.</para>
+ causes no change to the repository), removes these
+ revisions from the final dump file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--renumber-revs</option></term>
<listitem>
- <para>Renumbering revisions that remain after
+ <para>Renumbers revisions that remain after
filtering.</para>
</listitem>
</varlistentry>
@@ -8199,7 +8242,7 @@
<varlistentry>
<term><option>--skip-missing-merge-sources</option></term>
<listitem>
- <para>Skip merge sources that have been removed as part of
+ <para>Skips merge sources that have been removed as part of
the filtering. Without this
option, <command>svndumpfilter</command> will exit with
an error if the merge source for a retained path is
@@ -8225,7 +8268,7 @@
<varlistentry>
<term><option>--quiet</option></term>
<listitem>
- <para>Do not display filtering statistics.</para>
+ <para>Does not display filtering statistics.</para>
</listitem>
</varlistentry>
@@ -8235,7 +8278,10 @@
<!-- =============================================================== -->
<sect2 id="svn.ref.svndumpfilter.c">
- <title><command>svndumpfilter</command> Subcommands</title>
+ <title>svndumpfilter Subcommands</title>
+
+ <para>Here are the various subcommands
+ for the <command>svndumpfilter</command> program.</para>
<refentry id="svn.ref.svndumpfilter.commands.c.exclude">
@@ -8247,7 +8293,7 @@
<refnamediv>
<refname>svndumpfilter exclude</refname>
- <refpurpose>Filter out nodes with given prefixes from dumpstream.</refpurpose>
+ <refpurpose>Filter out nodes with given prefixes from the dump stream.</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
@@ -8256,9 +8302,9 @@
<refsect1>
<title>Description</title>
- <para>Can be used to exclude nodes that begin with one or
+ <para>This can be used to exclude nodes that begin with one or
more <replaceable>PATH_PREFIX</replaceable>es from a
- filtered dumpfile.</para>
+ filtered dump file.</para>
</refsect1>
<refsect1>
@@ -8274,10 +8320,10 @@
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
- <para>If we have a dumpfile from a repository with a number of
- different picnic-related directories in it, but want to keep
+ <para>If we have a dump file from a repository with a number of
+ different picnic-related directories in it, but we want to keep
everything <emphasis>except</emphasis>
the <filename>sandwiches</filename> part of the repository,
we'll exclude only that path:</para>
@@ -8300,12 +8346,6 @@
</refsect1>
</refentry>
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.ref.svndumpfilter.c.include">
- <title><command>svndumpfilter</command> Subcommands</title>
-
<refentry id="svn.ref.svndumpfilter.commands.c.include">
<indexterm>
@@ -8317,7 +8357,7 @@
<refnamediv>
<refname>svndumpfilter include</refname>
<refpurpose>Filter out nodes without given prefixes from
- dumpstream.</refpurpose>
+ dump stream.</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
@@ -8328,7 +8368,7 @@
<para>Can be used to include nodes that begin with one or
more <replaceable>PATH_PREFIX</replaceable>es in a
- filtered dumpfile (thus excluding all other paths).</para>
+ filtered dump file (thus excluding all other paths).</para>
</refsect1>
<refsect1>
@@ -8346,9 +8386,9 @@
<refsect1>
<title>Example</title>
- <para>If we have a dumpfile from a repository with a number of
- different picnic-related directories in it, but only want to
- keep the <filename>sandwiches</filename> part of the
+ <para>If we have a dump file from a repository with a number of
+ different picnic-related directories in it, but want to
+ keep only the <filename>sandwiches</filename> part of the
repository, we'll include only that path:</para>
<screen>
@@ -8371,12 +8411,6 @@
</refsect1>
</refentry>
- </sect2>
-
- <!-- =============================================================== -->
- <sect2 id="svn.ref.svndumpfilter.c.help">
- <title><command>svndumpfilter</command> Subcommands</title>
-
<refentry id="svn.ref.svndumpfilter.commands.c.help">
<indexterm>
@@ -8418,7 +8452,7 @@
<!-- ================================================================= -->
<sect1 id="svn.ref.svnversion">
- <title><command>svnversion</command></title>
+ <title>svnversion</title>
<refentry id="svn.ref.svnversion.re">
@@ -8449,7 +8483,7 @@
when defining the version number of your program.</para>
<para><replaceable>TRAIL_URL</replaceable>, if present, is the
- trailing portion of the URL used to determine if
+ trailing portion of the URL used to determine whether
<replaceable>WC_PATH</replaceable> itself is switched
(detection of switches within
<replaceable>WC_PATH</replaceable> does not rely on
@@ -8468,21 +8502,21 @@
<para>Like <command>svnserve</command>,
<command>svnversion</command> has no subcommands—only
- options.</para>
+ options:</para>
<variablelist>
<varlistentry>
<term><option>--no-newline</option> (<option>-n</option>)</term>
<listitem>
- <para>Omit the usual trailing newline from the output.</para>
+ <para>Omits the usual trailing newline from the output.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--committed</option> (<option>-c</option>)</term>
<listitem>
- <para>Use the last-changed revisions rather than the
+ <para>Uses the last-changed revisions rather than the
current (i.e., highest locally available) revisions.</para>
</listitem>
</varlistentry>
@@ -8490,14 +8524,14 @@
<varlistentry>
<term><option>--help</option> (<option>-h</option>)</term>
<listitem>
- <para>Print a help summary.</para>
+ <para>Prints a help summary.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem>
- <para>Print the version of <command>svnversion</command>
+ <para>Prints the version of <command>svnversion</command>
and exit with no error.</para>
</listitem>
</varlistentry>
@@ -8508,8 +8542,8 @@
<refsect1 id="svn.ref.svnversion.re.examples">
<title>Examples</title>
- <para>If the working copy is all at the same revision (for
- example, immediately after an update), then that revision is
+ <para>If the working copy is all at the same revision (e.g.,
+ immediately after an update), then that revision is
printed out:</para>
<screen>
@@ -8518,7 +8552,7 @@
</screen>
<para>You can add <replaceable>TRAIL_URL</replaceable> to make
- sure that the working copy is not switched from what you
+ sure the working copy is not switched from what you
expect. Note that the <replaceable>WC_PATH</replaceable>
is required in this command:</para>
@@ -8578,13 +8612,13 @@
<!-- ================================================================= -->
<sect1 id="svn.ref.mod_dav_svn">
- <title><command>mod_dav_svn</command></title>
+ <title>mod_dav_svn</title>
<refentry id="svn.ref.mod_dav_svn.conf">
<refnamediv>
- <refname><literal>mod_dav_svn</literal> Configuration
- Directives</refname> <refpurpose>Apache configuration
+ <refname>mod_dav_svn Configuration Directives</refname>
+ <refpurpose>Apache configuration
directives for serving Subversion repositories through the
Apache HTTP Server.</refpurpose>
@@ -8593,8 +8627,8 @@
<refsect1 id="svn.ref.mod_dav_svn.conf.desc">
<title>Description</title>
- <para>This section briefly describes each of the Subversion
- Apache configuration directives. For an in-depth
+ <para>This section briefly describes each Subversion
+ Apache configuration directive. For an in-depth
description of configuring Apache with Subversion, see <xref
linkend="svn.serverconfig.httpd"/>.)</para>
@@ -8603,16 +8637,19 @@
<refsect1 id="svn.ref.mod_dav_svn.conf.directives">
<title>Directives</title>
+ <para>These are the <filename>httpd.conf</filename> directives
+ that apply to <command>mod_dav_svn</command>:</para>
+
<variablelist>
<varlistentry>
<term><literal>DAV svn</literal></term>
<listitem>
- <para>This directive must be included in any
+ <para>Must be included in any
<literal>Directory</literal> or
<literal>Location</literal> block for a Subversion
- repository. It tells httpd to use the Subversion
+ repository. It tells <command>httpd</command> to use the Subversion
backend for <literal>mod_dav</literal> to handle all
requests.</para>
@@ -8623,12 +8660,12 @@
<term><literal>SVNAllowBulkUpdates On|Off</literal></term>
<listitem>
- <para>This directive toggles support for all-inclusive
+ <para>Toggles support for all-inclusive
responses to update-style <literal>REPORT</literal>
requests. Subversion clients use
<literal>REPORT</literal> requests to get information
about directory tree checkouts and updates from
- <literal>mod_dav_svn</literal>. They can ask the
+ <command>mod_dav_svn</command>. They can ask the
server to send that information in one of two ways:
with the entirety of the tree's information in one
massive response, or with a
@@ -8637,8 +8674,8 @@
enough information for the client to know what
<emphasis>additional</emphasis> data to request from
the server. When this directive is included with a
- value of <literal>off</literal>,
- <literal>mod_dav_svn</literal> will only ever respond
+ value of <literal>Off</literal>,
+ <command>mod_dav_svn</command> will only ever respond
to these <literal>REPORT</literal> requests with
skelta responses, regardless of the type of responses
requested by the client.</para>
@@ -8651,7 +8688,7 @@
checkouts, thus leaving an audit trail of
<literal>GET</literal> and <literal>PROPFIND</literal>
requests in Apache's logs. The default value of this
- directive is <literal>on</literal>.</para>
+ directive is <literal>On</literal>.</para>
</listitem>
</varlistentry>
@@ -8659,19 +8696,19 @@
<term><literal>SVNAutoversioning On|Off</literal></term>
<listitem>
- <para>This directive, when its value is
- <literal>on</literal>, allows write requests from
+ <para>When its value is
+ <literal>On</literal>, allows write requests from
WebDAV clients to result in automatic commits. A
- generic log message is autogenerated and attached to
- each revision. If you enable Autoversioning, you'll
+ generic log message is auto-generated and attached to
+ each revision. If you enable autoversioning, you'll
likely want to set <literal>ModMimeUsePathInfo
On</literal> so that <literal>mod_mime</literal> can
set <literal>svn:mime-type</literal> to the correct
- mime-type automatically (as best as
+ MIME type automatically (as best as
<literal>mod_mime</literal> is able to, of course).
For more information, see <xref
linkend="svn.webdav"/>. The default value of this
- directive is <literal>off</literal>.</para>
+ directive is <literal>Off</literal>.</para>
</listitem>
</varlistentry>
@@ -8681,7 +8718,7 @@
<replaceable>directory-path</replaceable></literal></term>
<listitem>
- <para>This directive specifies the location in the
+ <para>Specifies the location in the
filesystem for a Subversion repository's files. In a
configuration block for a Subversion repository,
either this directive or
@@ -8698,7 +8735,7 @@
<para>Specifies the URI component (namespace) for
special Subversion resources. The default is
- <quote><literal>!svn</literal></quote>, and most
+ <literal>!svn</literal>, and most
administrators will never use this directive. Set
this only if there is a pressing need to have a file
named <filename>!svn</filename> in your repository.
@@ -8752,14 +8789,16 @@
</varlistentry>
<varlistentry>
- <term><literal>SVNPathAuthz
- <replaceable>file-path</replaceable></literal></term>
+ <term><literal>SVNPathAuthz On|Off|short_circuit</literal></term>
<listitem>
- <para>Control path-based authorization by enabling or
- disabling subrequests. See
- <xref linkend="svn.serverconfig.httpd.authz.pathauthzoff"/>
- for details.</para>
+ <para>Controls path-based authorization by enabling
+ subrequests (<literal>On</literal>), disabling
+ subrequests (<literal>Off</literal>; see <xref
+ linkend="svn.serverconfig.httpd.authz.pathauthzoff"/>),
+ or querying <command>mod_authz_svn</command> directly
+ (<literal>short_circuit</literal>). The default
+ value of this directive is <literal>On</literal>.</para>
</listitem>
</varlistentry>
@@ -8796,14 +8835,14 @@
<para>Specifies the location in the filesystem where the
activities database should be stored. By default,
- mod_dav_svn creates and uses a directory in the
+ <command>mod_dav_svn</command> creates and uses a directory in the
repository
called <filename>dav/activities.d</filename>. The
path specified with this option must be an absolute
path.</para>
<para>If specified for
- an <literal>SVNParentPath</literal> area, mod_dav_svn
+ an <literal>SVNParentPath</literal> area, <command>mod_dav_svn</command>
appends the basename of the repository to the path
specified here. For example:</para>
@@ -8862,7 +8901,7 @@
</varlistentry>
<varlistentry>
- <term>Fetching a directory</term>
+ <term>Fetch a directory</term>
<listitem>
<para><literal>get-dir /trunk r17 text</literal></para>
</listitem>
@@ -8876,14 +8915,14 @@
</varlistentry>
<varlistentry>
- <term>Fetch file revision</term>
+ <term>Fetch a file revision</term>
<listitem>
<para><literal>get-file-revs /path r12:15 include-merged-revisions</literal></para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Fetching of merge information</term>
+ <term>Fetch merge information</term>
<listitem>
<para><literal>get-mergeinfo (/path1 /path2)</literal></para>
</listitem>
@@ -8905,7 +8944,7 @@
</varlistentry>
<varlistentry>
- <term>Replaying of revisions (svnsync)</term>
+ <term>Replay revisions (svnsync)</term>
<listitem>
<para><literal>replay /path r19</literal></para>
</listitem>
@@ -8965,11 +9004,104 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
+ <sect1 id="svn.ref.mod_authz_svn">
+
+ <title>mod_authz_svn</title>
+
+ <refentry id="svn.ref.mod_authz_svn.conf">
+ <refnamediv>
+
+ <refname>mod_authz_svn Configuration Directives</refname>
+ <refpurpose>Apache configuration directives for configuring
+ path-based authorization for Subversion repositories served
+ through the Apache HTTP Server.</refpurpose>
+
+ </refnamediv>
+
+ <refsect1 id="svn.ref.mod_authz_svn.conf.desc">
+ <title>Description</title>
+
+ <para>This section briefly describes each Apache configuration
+ directive offered by <command>mod_authz_svn</command>. For
+ an in-depth description of using path-based authorization in
+ Subversion, see <xref linkend="svn.serverconfig.pathbasedauthz"/>.)</para>
+
+ </refsect1>
+
+ <refsect1 id="svn.ref.mod_authz_svn.conf.directives">
+ <title>Directives</title>
+
+ <para>These are the <filename>httpd.conf</filename> directives
+ that apply to <command>mod_authz_svn</command>:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><literal>AuthzSVNAccessFile
+ <replaceable>file-path</replaceable></literal></term>
+ <listitem>
+
+ <para>Consult <replaceable>file-path</replaceable> for
+ access rules describing the permissions for paths in
+ Subversion repository.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>AuthzSVNAnonymous On|Off</literal></term>
+ <listitem>
+
+ <para>Set to <literal>Off</literal> to disable two
+ special-case behaviours of this module: interaction
+ with the <literal>Satisfy Any</literal> directive and
+ enforcement of the authorization policy even when no
+ <literal>Require</literal> directives are present.
+ The default value of this directive is
+ <literal>On</literal>.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>AuthzSVNAuthoritative On|Off</literal></term>
+ <listitem>
+
+ <para>Set to <literal>Off</literal> to allow access
+ control to be passed along to lower modules. The
+ default value of this directive is
+ <literal>On</literal>.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>AuthzSVNNoAuthWhenAnonymousAllowed On|Off</literal></term>
+ <listitem>
+
+ <para>Set to <literal>On</literal> to suppress
+ authentication and authorization for requests which
+ anonymous users are allowed to perform. The default
+ value of this directive is
+ <literal>On</literal>.</para>
+
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ </refentry>
+ </sect1>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
<sect1 id="svn.ref.properties">
<title>Subversion Properties</title>
- <para>Subversion allows users to invent arbitrarily-named
+ <para>Subversion allows users to invent arbitrarily named
versioned properties on files and directories, as well as
unversioned properties on revisions. The only restriction is on
properties whose names begin with <literal>svn:</literal> (those
@@ -8980,6 +9112,9 @@
<sect2 id="svn.ref.properties.versioned-props">
<title>Versioned Properties</title>
+ <para>These are the versioned properties that Subversion reserves
+ for its own use:</para>
+
<variablelist>
<varlistentry>
@@ -8999,10 +9134,10 @@
<listitem>
<para>If present on a file, the value indicates the
- file's mime-type. This allows the client to decide
+ file's MIME type. This allows the client to decide
whether line-based contextual merging is safe to
perform during updates, and can also affect how the
- file behaves when fetched via web browser. See
+ file behaves when fetched via a web browser. See
<xref
linkend="svn.advanced.props.special.mime-type"/>. </para>
@@ -9044,7 +9179,7 @@
to manipulate the file's line-endings in the working
copy and in exported trees. See <xref
linkend="svn.advanced.props.special.eol-style"/> and
- <xref linkend="svn.ref.svn.c.export" />.</para>
+ <xref linkend="svn.ref.svn.c.export" /> earlier in this chapter.</para>
</listitem>
</varlistentry>
@@ -9111,6 +9246,9 @@
<sect2 id="svn.ref.properties.unversioned-props">
<title>Unversioned Properties</title>
+ <para>These are the unversioned properties tht Subversion reserves
+ for its own use:</para>
+
<variablelist>
<varlistentry>
@@ -9119,7 +9257,7 @@
<para>If present, contains the authenticated username of
the person who created the revision. (If not present,
- then the revision was committed anonymously.)</para>
+ the revision was committed anonymously.)</para>
</listitem>
</varlistentry>
@@ -9168,6 +9306,8 @@
<sect1 id="svn.ref.reposhooks">
<title>Repository Hooks</title>
+
+ <para>These are the repository hooks that Subversion provides:</para>
<!-- =============================================================== -->
<refentry id="svn.ref.reposhooks.start-commit">
@@ -9188,11 +9328,11 @@
<para>The start-commit hook is run before the commit
transaction is even created. It is typically used to
- decide if the user has commit privileges at all.</para>
+ decide whether the user has commit privileges at all.</para>
<para>If the start-commit hook program returns a nonzero exit
value, the commit is stopped before the commit transaction
- is even created, and anything printed to stderr is
+ is even created, and anything printed to <filename>stderr</filename> is
marshalled back to the client.</para>
</refsect1>
@@ -9211,17 +9351,17 @@
<para>Authenticated username attempting the commit</para>
</listitem>
<listitem>
- <para>(New in Subversion 1.5.) Colon-separated list of
+ <para>Colon-separated list of
capabilities that a client passes to the server,
including <literal>depth</literal>,
<literal>mergeinfo</literal>, and
- <literal>log-revprops</literal>.</para>
+ <literal>log-revprops</literal> (new in Subversion 1.5).</para>
</listitem>
</orderedlist>
</refsect1>
<refsect1>
- <title>Common Uses</title>
+ <title>Common uses</title>
<para>Access control (e.g., temporarily lock out commits for
some reason).</para>
@@ -9252,7 +9392,7 @@
<para>The <literal>pre-commit</literal> hook is run just
before a commit transaction is promoted to a new revision.
Typically, this hook is used to protect against commits that
- are disallowed due to content or location (for example, your
+ are disallowed due to content or location (e.g., your
site might require that all commits to a certain branch
include a ticket number from the bug tracker, or that the
incoming log message is nonempty).</para>
@@ -9260,12 +9400,12 @@
<para>If the <literal>pre-commit</literal> hook program
returns a nonzero exit value, the commit is aborted, the
commit transaction is removed, and anything printed to
- stderr is marshalled back to the client.</para>
+ <filename>stderr</filename> is marshalled back to the client.</para>
</refsect1>
<refsect1>
- <title>Input Parameter(s)</title>
+ <title>Input parameter(s)</title>
<para>The command-line arguments passed to the hook program,
in order, are:</para>
@@ -9281,7 +9421,7 @@
</refsect1>
<refsect1>
- <title>Common Uses</title>
+ <title>Common uses</title>
<para>Change validation and control</para>
</refsect1>
@@ -9305,7 +9445,7 @@
<title>Description</title>
<para>The <literal>post-commit</literal> hook is run after the
- transaction is committed and a new revision created. Most
+ transaction is committed and a new revision is created. Most
people use this hook to send out descriptive emails about
the commit or to notify some other tool (such as an issue
tracker) that a commit has happened. Some configurations
@@ -9315,13 +9455,13 @@
nonzero exit status, the commit <emphasis>will
not</emphasis> be aborted since it has already
completed. However, anything that the hook printed
- to <literal>STDERR</literal> will be marshalled back to the
+ to <filename>stderr</filename> will be marshalled back to the
client, making it easier to diagnose hook failures.</para>
</refsect1>
<refsect1>
- <title>Input Parameter(s)</title>
+ <title>Input parameter(s)</title>
<para>The command-line arguments passed to the hook program,
in order, are:</para>
@@ -9337,7 +9477,7 @@
</refsect1>
<refsect1>
- <title>Common Uses</title>
+ <title>Common uses</title>
<para>Commit notification; tool integration</para>
</refsect1>
@@ -9372,12 +9512,12 @@
<para>If the <literal>pre-revprop-change</literal> hook
doesn't exist, isn't executable, or returns a nonzero exit
value, no change to the property will be made, and anything
- printed to stderr is marshalled back to the client.</para>
+ printed to <filename>stderr</filename> is marshalled back to the client.</para>
</refsect1>
<refsect1>
- <title>Input Parameter(s)</title>
+ <title>Input parameter(s)</title>
<para>The command-line arguments passed to the hook program,
in order, are:</para>
@@ -9390,7 +9530,7 @@
<para>Revision whose property is about to be modified</para>
</listitem>
<listitem>
- <para>Authenticated username attempting the propchange</para>
+ <para>Authenticated username attempting the property change</para>
</listitem>
<listitem>
<para>Name of the property changed</para>
@@ -9409,7 +9549,7 @@
</refsect1>
<refsect1>
- <title>Common Uses</title>
+ <title>Common uses</title>
<para>Access control; change validation and control</para>
</refsect1>
@@ -9434,9 +9574,9 @@
<title>Description</title>
<para>The <literal>post-revprop-change</literal> hook is run
- immediately after to the modification of a revision property
- when performed outside the scope of a normal commit. As can
- be derived from the description of its counterpart, the
+ immediately after the modification of a revision property
+ when performed outside the scope of a normal commit. As you can
+ derive from the description of its counterpart, the
<literal>pre-revprop-change</literal> hook, this hook will
not run at all unless
the <literal>pre-revprop-change</literal> hook is
@@ -9447,13 +9587,13 @@
nonzero exit status, the change <emphasis>will
not</emphasis> be aborted since it has already
completed. However, anything that the hook printed
- to <literal>STDERR</literal> will be marshalled back to the
+ to <filename>stderr</filename> will be marshalled back to the
client, making it easier to diagnose hook failures.</para>
</refsect1>
<refsect1>
- <title>Input Parameter(s)</title>
+ <title>Input parameter(s)</title>
<para>The command-line arguments passed to the hook program,
in order, are:</para>
@@ -9484,8 +9624,8 @@
</refsect1>
<refsect1>
- <title>Common Uses</title>
- <para>propchange notification</para>
+ <title>Common uses</title>
+ <para>Property change notification</para>
</refsect1>
</refentry>
@@ -9511,19 +9651,19 @@
someone attempts to lock a path. It can be used to prevent
locks altogether or to create a more complex policy
specifying exactly which users are allowed to lock
- particular paths. If the hook notices a pre-existing lock,
- then it can also decide whether a user is allowed
+ particular paths. If the hook notices a preexisting lock,
+ it can also decide whether a user is allowed
to <quote>steal</quote> the existing lock.</para>
<para>If the <literal>pre-lock</literal> hook program returns
a nonzero exit value, the lock action is aborted and
- anything printed to stderr is marshalled back to the
+ anything printed to <filename>stderr</filename> is marshalled back to the
client.</para>
</refsect1>
<refsect1>
- <title>Input Parameter(s)</title>
+ <title>Input parameter(s)</title>
<para>The command-line arguments passed to the hook program,
in order, are:</para>
@@ -9543,7 +9683,7 @@
</refsect1>
<refsect1>
- <title>Common Uses</title>
+ <title>Common uses</title>
<para>Access control</para>
</refsect1>
@@ -9567,20 +9707,20 @@
<title>Description</title>
<para>The <literal>post-lock</literal> hook runs after one or
- more paths has been locked. It is typically used to send
+ more paths have been locked. It is typically used to send
email notification of the lock event.</para>
<para>If the <literal>post-lock</literal> hook returns a
nonzero exit status, the lock <emphasis>will
not</emphasis> be aborted since it has already
completed. However, anything that the hook printed
- to <literal>STDERR</literal> will be marshalled back to the
+ to <filename>stderr</filename> will be marshalled back to the
client, making it easier to diagnose hook failures.</para>
</refsect1>
<refsect1>
- <title>Input Parameter(s)</title>
+ <title>Input parameter(s)</title>
<para>The command-line arguments passed to the hook program,
in order, are:</para>
@@ -9601,7 +9741,7 @@
</refsect1>
<refsect1>
- <title>Common Uses</title>
+ <title>Common uses</title>
<para>Lock notification</para>
</refsect1>
@@ -9635,13 +9775,13 @@
<para>If the <literal>pre-unlock</literal> hook program
returns a nonzero exit value, the unlock action is aborted
- and anything printed to stderr is marshalled back to the
+ and anything printed to <filename>stderr</filename> is marshalled back to the
client.</para>
</refsect1>
<refsect1>
- <title>Input Parameter(s)</title>
+ <title>Input parameter(s)</title>
<para>The command-line arguments passed to the hook program,
in order, are:</para>
@@ -9661,7 +9801,7 @@
</refsect1>
<refsect1>
- <title>Common Uses</title>
+ <title>Common uses</title>
<para>Access control</para>
</refsect1>
@@ -9685,20 +9825,20 @@
<title>Description</title>
<para>The <literal>post-unlock</literal> hook runs after one
- or more paths has been unlocked. It is typically used to
+ or more paths have been unlocked. It is typically used to
send email notification of the unlock event.</para>
<para>If the <literal>post-unlock</literal> hook returns a
nonzero exit status, the unlock <emphasis>will
not</emphasis> be aborted since it has already
completed. However, anything that the hook printed
- to <literal>STDERR</literal> will be marshalled back to the
+ to <filename>stderr</filename> will be marshalled back to the
client, making it easier to diagnose hook failures.</para>
</refsect1>
<refsect1>
- <title>Input Parameter(s)</title>
+ <title>Input parameter(s)</title>
<para>The command-line arguments passed to the hook program,
in order, are:</para>
@@ -9719,7 +9859,7 @@
</refsect1>
<refsect1>
- <title>Common Uses</title>
+ <title>Common uses</title>
<para>Unlock notification</para>
</refsect1>
Modified: trunk/src/de/book/foreword.xml
==============================================================================
--- trunk/src/de/book/foreword.xml (original)
+++ trunk/src/de/book/foreword.xml Tue Aug 12 11:40:38 2008
@@ -23,7 +23,7 @@
<firstname>Karl</firstname>
<surname>Fogel</surname>
</author>
- <pubdate>Chicago, 14, März 2004</pubdate>
+ <pubdate>Chicago, 14, März 2004.</pubdate>
</prefaceinfo>
@@ -72,7 +72,7 @@
<para>The problem with such FAQs is that they are not, in a
literal sense, FAQs at all. No one ever called the tech support
line and asked, <quote>How can we maximize
- productivity?</quote>. Rather, people asked highly specific
+ productivity?</quote> Rather, people asked highly specific
questions, such as <quote>How can we change the calendaring system
to send reminders two days in advance instead of one?</quote>
and so on. But it's a lot easier to make up imaginary
@@ -111,7 +111,7 @@
of the authors' encounters with users. It began with Ben
Collins-Sussman's observation that people were asking the same
basic questions over and over on the Subversion mailing lists:
- What are the standard workflows to use with Subversion? Do
+ what are the standard workflows to use with Subversion? Do
branches and tags work the same way as in other version control
systems? How can I find out who made a particular change?</para>
-->
@@ -129,7 +129,7 @@
<!--
<para>Frustrated at seeing the same questions day after day, Ben
worked intensely over a month in the summer of 2002 to write
- <citetitle>The Subversion Handbook</citetitle>, a 60 page
+ <citetitle>The Subversion Handbook</citetitle>, a 60-page
manual that covered all the basics of using Subversion. The
manual made no pretense of being complete, but it was
distributed with Subversion and got users over that initial hump
@@ -141,7 +141,7 @@
<para>Frustriert davon, Tag für Tag immer wieder die gleichen Fragen
zu sehen, arbeitete Ben im Sommer 2002 über einen Monat intensiv
daran, <citetitle>The Subversion Handbook</citetitle> zu
- schreiben, eine sechzig-seitige Anleitung, die die Grundlagen der
+ schreiben, eine 60-seitige Anleitung, die die Grundlagen der
Benutzung von Subversion beschrieb. Die Anleitung erhob keinen
Anspruch auf Vollständigkeit, aber sie wurde mit Subversion
verteilt und half vielen über die ersten Buckel der Lernkurve.
@@ -158,7 +158,7 @@
stream—indeed, an uncontrollable geyser—of bottom-up
source material. Subversion was already in the hands of
thousands of early adopters, and those users were giving tons of
- feedback, not only about Subversion, but about its existing
+ feedback, not only about Subversion, but also about its existing
documentation.</para>
-->
<para>Die drei Co-Autoren des neuen Buches erhielten somit eine
@@ -185,7 +185,7 @@
back, the book is simply a straightforward description of a
piece of software. There's the overview, the obligatory guided
tour, the chapter on administrative configuration, some advanced
- topics, and of course a command reference and troubleshooting
+ topics, and of course, a command reference and troubleshooting
guide. Only when you come back to it later, seeking the
solution to some specific problem, does its authenticity shine
out: the telling details that can only result from encounters
@@ -218,7 +218,7 @@
<!--
<para>Of course, no one can promise that this book will answer
- every question you have about Subversion. Sometimes, the
+ every question you have about Subversion. Sometimes the
precision with which it anticipates your questions will seem
eerily telepathic; yet occasionally, you will stumble into a
hole in the community's knowledge and come away empty-handed.
Modified: trunk/src/de/book/styles.css
==============================================================================
--- trunk/src/de/book/styles.css (original)
+++ trunk/src/de/book/styles.css Tue Aug 12 11:40:38 2008
@@ -1,23 +1,61 @@
-/************************************************************************/
-/* Custom style-sheet stuffs for the Subversion book in HTML form. */
-/************************************************************************/
-
-/*
- * Copyright (c) 2003-2008
- * Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato.
- *
- * This work is licensed under the Creative Commons Attribution License.
- * To view a copy of this license, visit
- * http://creativecommons.org/licenses/by/2.0/ or send a letter to
- * Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305,
- * USA.
- */
+/****************************************************************************
+ * *
+ * CUSTOM STYLE-SHEET STUFFS FOR THE SUBVERSION BOOK IN HTML FORM *
+ * *
+ ****************************************************************************
+ * *
+ * Copyright (c) 2003-2008 *
+ * Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato. *
+ * *
+ * This work is licensed under the Creative Commons Attribution License. *
+ * To view a copy of this license, visit *
+ * http://creativecommons.org/licenses/by/2.0/ or send a letter to *
+ * Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, *
+ * USA. *
+ * *
+ ****************************************************************************/
body
{
background: white;
- margin: 0.5in;
- font-family: arial,helvetica,sans-serif;
+ margin: 1in;
+ font-family: serif;
+}
+
+p, li, ul, ol, dd, dt
+{
+ font-style: normal;
+ font-weight: normal;
+ color: black;
+}
+
+tt, pre
+{
+ font-family: monospace;
+}
+
+a
+{
+ color: blue;
+ text-decoration: underline;
+}
+
+a:hover
+{
+ background: rgb(75%,75%,100%);
+ color: blue;
+ text-decoration: underline;
+}
+
+a:visited
+{
+ color: purple;
+ text-decoration: underline;
+}
+
+img
+{
+ border: none;
}
h1.title
@@ -59,66 +97,59 @@
color: black;
}
-.toc b
+strong
{
- font-size: 125%;
- font-style: normal;
- font-weight: bold;
- color: black;
+ font-weight: normal;
}
-p,li,ul,ol,dd,dt
+.toc b
{
+ font-family: sans-serif;
+ font-size: 120%;
font-style: normal;
- font-weight: normal;
+ font-weight: bold;
color: black;
}
-tt,pre
+.title
{
- font-family: courier new,courier,fixed;
+ font-family: sans-serif;
}
-.command, .screen, .programlisting
+.screen, .programlisting, .structname
{
- font-family: courier new,courier,fixed;
+ font-family: monospace;
font-style: normal;
font-weight: normal;
}
-.filename
+.userinput
{
- font-family: arial,helvetica,sans-serif;
- font-style: italic;
+ font-weight: normal;
}
-a
-{
- color: blue;
- text-decoration: underline;
-}
-
-a:hover
+.command
{
- background: rgb(75%,75%,100%);
- color: blue;
- text-decoration: underline;
+ font-style: italic;
}
-a:visited
+.filename
{
- color: purple;
- text-decoration: underline;
+ font-family: serif;
+ font-style: italic;
}
-img
+.figure, .example, .table
{
- border: none;
+ margin: 0.125in 0.25in;
}
-.figure, .example, .table
+.figure p.title b, .example p.title b, .table p.title b
{
- margin: 0.125in 0.5in;
+ font-family: serif;
+ font-size: 80%;
+ font-style: italic;
+ font-weight: normal;
}
.table table
@@ -153,14 +184,20 @@
font-size: 100% !important;
}
-.author
+.author, .pubdate
{
+ margin: 0;
font-size: 100%;
font-style: italic;
font-weight: normal;
color: black;
}
+.preface div.author, .preface .pubdate
+{
+ font-size: 80%;
+}
+
.sidebar
{
border-top: dotted 1px black;
@@ -169,7 +206,7 @@
border-bottom: solid 2px black;
background: rgb(240,220,170);
padding: 0 0.12in;
- margin: 0.5in;
+ margin: 0.25in;
}
.note .programlisting, .note .screen,
@@ -187,35 +224,39 @@
font-size: 125%;
}
-.note
+.note, .tip, .warning
{
border: black solid 1px;
- background: url(./images/note.png) no-repeat rgb(252,246,220);
- margin: 0.12in 0;
+ margin: 0.125in 0;
padding: 0 55px;
+ font-size: 90%;
+}
+
+.note
+{
+ background: url(./images/note.png) no-repeat rgb(252,246,220);
}
.tip
{
- border: black solid 1px;
background: url(./images/tip.png) no-repeat rgb(224,244,255);
- margin: 0.12in 0;
- padding: 0 55px;
}
.warning
{
- border: black solid 1px;
background: url(./images/warning.png) no-repeat rgb(255,210,210);
- margin: 0.12in 0;
- padding: 0 55px;
+}
+
+.note .title, .tip .title, .warning .title
+{
+ display: none;
}
.programlisting, .screen
{
font-size: 90%;
color: black;
- margin: 1em 0.5in;
+ margin: 1em 0.25in;
padding: 0.5em;
background: rgb(240,240,240);
border-top: black dotted 1px;
@@ -245,3 +286,25 @@
{
display: none;
}
+
+/* --------------------- */
+/* PRINT MEDIA OVERRIDES */
+/* --------------------- */
+
+ at media print
+{
+ body
+ {
+ margin: 0;
+ }
+
+ .navheader, .navfooter
+ {
+ display: none;
+ }
+
+ #svn-footer hr
+ {
+ display: block;
+ }
+}
More information about the svnbook-dev
mailing list