[svnbook commit] r1307 - in trunk/src/nb: . book
sunny256
svnbook-dev at red-bean.com
Tue May 17 22:06:23 CDT 2005
Author: sunny256
Date: Tue May 17 22:06:21 2005
New Revision: 1307
Removed:
trunk/src/nb/book/colo.xml
Modified:
trunk/src/nb/LAST_UPDATED
trunk/src/nb/TRANSLATION-STATUS
trunk/src/nb/book/book.xml
trunk/src/nb/book/ch00.xml
trunk/src/nb/book/ch03.xml
trunk/src/nb/book/ch06.xml
trunk/src/nb/book/ch07.xml
trunk/src/nb/book/ch09.xml
trunk/src/nb/book/styles.css
Log:
Sync the Norwegian svnbook with the English version, r1268:1306.
* src/nb/LAST_UPDATED
Updated by make sync as usual.
* src/nb/TRANSLATION-STATUS
Removed the files from the list which was removed by cmpilato in
r1304. And colo.xml .
* src/nb/book/book.xml
Merged and updated r1297, colo.xml is gone.
* src/nb/book/ch00.xml
Merged and updated r1289.
* src/nb/book/ch03.xml
Merged and updated r1287, r1288, r1295.
* src/nb/book/ch06.xml
Merged r1277, r1278, r1302.
* src/nb/book/ch07.xml
Merged r1281, r1283, r1284, r1285.
* src/nb/book/ch09.xml
Merged r1291, r1292, r1299, r1305.
* src/nb/book/colo.xml
Removed in r1297 and is history here too.
* src/nb/book/styles.css
Merged r1303.
Modified: trunk/src/nb/LAST_UPDATED
==============================================================================
--- trunk/src/nb/LAST_UPDATED (original)
+++ trunk/src/nb/LAST_UPDATED Tue May 17 22:06:21 2005
@@ -1 +1 @@
-1268
+1306
Modified: trunk/src/nb/TRANSLATION-STATUS
==============================================================================
--- trunk/src/nb/TRANSLATION-STATUS (original)
+++ trunk/src/nb/TRANSLATION-STATUS Tue May 17 22:06:21 2005
@@ -43,8 +43,6 @@
2.1.4. Untranslated
- README
- book-dist.py
book/appb.xml
book/appc.xml
book/appd.xml
@@ -52,7 +50,6 @@
book/ch07.xml
book/ch08.xml
book/ch09.xml
- book/colo.xml
book/copyright.xml
book/images/VersioningModels.ppt
book/images/branches.ppt
@@ -62,14 +59,7 @@
2.2. Files not part of the translation at the moment
- 2.2.1. Probably not necessary to translate
-
- HACKING
- REVIEW
- TODO
- outline.txt
-
- 2.2.2. Contains no i18n information
+ 2.2.1. Contains no i18n information
book/images/DirectoryModels.ppt
book/images/ch02dia6.png
Modified: trunk/src/nb/book/book.xml
==============================================================================
--- trunk/src/nb/book/book.xml (original)
+++ trunk/src/nb/book/book.xml Tue May 17 22:06:21 2005
@@ -20,7 +20,6 @@
<!ENTITY appc SYSTEM "appc.xml">
<!ENTITY appd SYSTEM "appd.xml">
<!ENTITY license SYSTEM "copyright.xml">
-<!ENTITY colo SYSTEM "colo.xml">
]>
@ENGLISH }}} -->
<!DOCTYPE book SYSTEM "../../tools/dtd/dblite.dtd"
@@ -43,7 +42,6 @@
<!ENTITY appc SYSTEM "appc.xml">
<!ENTITY appd SYSTEM "appd.xml">
<!ENTITY license SYSTEM "copyright.xml">
-<!ENTITY colo SYSTEM "colo.xml">
]>
<!-- @ENGLISH {{{
@@ -153,7 +151,6 @@
&appc;
&appd;
&license;
- &colo;
</book>
<!-- vim: set ft=svnbook : -->
Modified: trunk/src/nb/book/ch00.xml
==============================================================================
--- trunk/src/nb/book/ch00.xml (original)
+++ trunk/src/nb/book/ch00.xml Tue May 17 22:06:21 2005
@@ -750,10 +750,10 @@
<listitem>
<!-- @ENGLISH {{{
<para>You will always find the latest version of this book in
- Subversion's own source tree.</para>
+ the book's own Subversion repository.</para>
@ENGLISH }}} -->
<para>Du vil alltid finne den seneste versjonen av denne boken i
- Subversions eget kildekodetre.</para>
+ bokens eget Subversiondepot.</para>
</listitem>
<listitem>
Modified: trunk/src/nb/book/ch03.xml
==============================================================================
--- trunk/src/nb/book/ch03.xml (original)
+++ trunk/src/nb/book/ch03.xml Tue May 17 22:06:21 2005
@@ -869,12 +869,12 @@
<listitem>
<!-- @ENGLISH {{{
- <para>Merge others' changes</para>
+ <para>Merge others' changes into your working copy</para>
@ENGLISH }}} -->
- <para>Flett inn andres forandringer</para>
+ <para>Flett andres forandringer inn i arbeidskopien din</para>
<itemizedlist>
<listitem>
- <para><command>svn merge</command></para>
+ <para><command>svn update</command></para>
</listitem>
<listitem>
<para><command>svn resolved</command></para>
@@ -1160,6 +1160,28 @@
som du vil bruke oftest for å gjøre forandringer i trestrukturen
(vi vil dekke <command>svn import</command> og <command>svn
mkdir</command> senere).</para>
+
+ <!-- @ENGLISH {{{
+ <warning>
+ <para>While you can edit your files with whatever tool you
+ like, you shouldn't change the structure of your working
+ copy without letting Subversion know what you're doing. Use
+ the <command>svn copy</command>, <command>svn
+ delete</command>, and <command>svn move</command> commands
+ to change the structure of your working copy, and use the
+ <command>svn add</command> command to place new files and
+ directories under version control.</para> </warning>
+ @ENGLISH }}} -->
+ <warning>
+ <para>Selv om du kan redigere filene dine med hvilket verktøy du
+ vil, bør du ikke forandre strukturen i arbeidskopien uten å la
+ Subversion vite hva du gjør.
+ Bruk kommandoene <command>svn copy</command>, <command>svn
+ delete</command> og <command>svn move</command> for å forandre
+ strukturen på arbeidskopien, og bruk <command>svn
+ add</command>-kommandoen for å legge inn nye filer og
+ kataloger under versjonskontroll.</para>
+ </warning>
<variablelist>
@@ -1782,14 +1804,14 @@
<!-- @ENGLISH {{{
<para>The second column tells the status of a file or
directory's properties (see <xref
- linkend="svn-ch-7-sect-2"></xref> for more information on
+ linkend="svn-ch-7-sect-2"/> for more information on
properties). If an <computeroutput>M</computeroutput>
appears in the second column, then the properties have been
modified, otherwise a whitespace will be printed.</para>
@ENGLISH }}} -->
<para>Den andre kolonnen forteller statusen på egenskapene til
en fil eller katalog (se <xref
- linkend="svn-ch-7-sect-2"></xref> for mer informasjon om
+ linkend="svn-ch-7-sect-2"/> for mer informasjon om
egenskaper).
Hvis en <computeroutput>M</computeroutput> viser seg i den
andre kolonnen, er egenskapene blitt modifisert, ellers vil et
Modified: trunk/src/nb/book/ch06.xml
==============================================================================
--- trunk/src/nb/book/ch06.xml (original)
+++ trunk/src/nb/book/ch06.xml Tue May 17 22:06:21 2005
@@ -577,7 +577,8 @@
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.</para>
+ authenticated username. For more on this, see <xref
+ linkend="svn-ch-6-sect-3.4"/>.</para>
<para>As you've already guessed, a repository's
<filename>svnserve.conf</filename> file is the central
@@ -731,20 +732,45 @@
…
</screen>
- <para>What's happening here is that the Subversion client is
- invoking a local <command>ssh</command> process, connecting to
- <literal>host.example.com</literal>, authenticating as the user
- <literal>harry</literal>, then spawning a private
- <command>svnserve</command> process on the remote machine,
+ <para>In this example, the Subversion client is invoking a local
+ <command>ssh</command> process, connecting to
+ <literal>host.example.com</literal>, authenticating as the
+ user <literal>harry</literal>, then spawning a private
+ <command>svnserve</command> process on the remote machine
running as the user <literal>harry</literal>. The
<command>svnserve</command> command is being invoked in tunnel
mode (<option>-t</option>) and its network protocol is being
<quote>tunneled</quote> over the encrypted connection by
<command>ssh</command>, the tunnel-agent.
- <command>svnserve</command> is aware that it's running as the user
- <literal>harry</literal>, and if the client performs a commit,
- the authenticated username will be attributed as the author of
- the new revision.</para>
+ <command>svnserve</command> is aware that it's running as the
+ user <literal>harry</literal>, and if the client performs a
+ commit, the authenticated username will be attributed as the
+ author of the new revision.</para>
+
+ <para>The important thing to understand here is that the
+ Subversion client is <emphasis>not</emphasis> connecting to a
+ running <command>svnserve</command> daemon. This method of
+ access doesn't require a daemon, nor does it notice one if
+ present. It relies wholly on the ability of
+ <command>ssh</command> to spawn a temporary
+ <command>svnserve</command> process, which then terminates
+ when the network connection is closed.</para>
+
+ <para>When using <literal>svn+ssh://</literal> URLs to access a
+ repository, remember that it's the <command>ssh</command>
+ program prompting for authentication, and
+ <emphasis>not</emphasis> the <command>svn</command> client
+ program. That means there's no automatic password caching
+ going on (see <xref linkend="svn-ch-6-sect-2.2"/>). The
+ Subversion client often makes multiple connections to the
+ repository, though users don't normally notice this due to the
+ password caching feature. When using
+ <literal>svn+ssh://</literal> URLs, however, users may be
+ annoyed by <command>ssh</command> repeatedly asking for a
+ password for every outbound connection. The solution is to
+ use a separate SSH password-caching tool like
+ <command>ssh-agent</command> on a Unix-like system, or
+ <command>pageant</command> on Windows.</para>
<para>When running over a tunnel, authorization is primarily
controlled by operating system permissions to the repository's
@@ -806,27 +832,139 @@
a convenient way to override the default SSH tunnel agent.
But if you need to have several different overrides for
different servers, each perhaps contacting a different port or
- passing a different set of options, you can use the mechanism
- demonstrated in this example. Now if we were to set the
- <literal>JOESSH</literal> environment variable, its value
+ passing a different set of options to SSH, you can use the
+ mechanism demonstrated in this example. Now if we were to set
+ 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>
-
- <para>A final note: when using <literal>svn+ssh://</literal>
- URLs to access a repository, remember that it's the
- <command>ssh</command> program prompting you for
- authentication, and <emphasis>not</emphasis> the
- <command>svn</command> program. That means there's no
- automatic password caching going on (see <xref
- linkend="svn-ch-6-sect-2.2"/>). If you want to prevent
- <command>ssh</command> from repeatedly asking for your
- password, you'll need to use a separate memory-caching tool
- like <command>ssh-agent</command> on a Unix-like system, or
- <command>pageant</command> on Windows.</para>
+ instead of <command>/opt/alternate/ssh -p
+ 29934</command>.</para>
</sect2>
+ <sect2 id="svn-ch-6-sect-3.5">
+ <title>SSH configuration tricks</title>
+
+ <para>It's not only possible to control 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
+ exact <command>svnserve</command> command executed
+ by <command>sshd</command>, as well as how to have multiple
+ users share a single system account.</para>
+
+ <sect3 id="svn-ch-6-sect-3.5.1">
+ <title>Initial setup</title>
+
+ <para>To begin, locate the home directory of the account
+ you'll be using to launch <command>svnserve</command>. Make
+ sure the account has an SSH public/private keypair
+ installed, and that the user can log in via public-key
+ authentication. Password authentication will not work,
+ since all of the following SSH tricks revolve around using
+ the SSH <filename>authorized_keys</filename> file.</para>
+
+ <para>If it doesn't already exist, create the
+ <filename>authorized_keys</filename> file (on Unix,
+ typically <filename>~/.ssh/authorized_keys</filename>).
+ Each line in this file describes a public key that is
+ allowed to connect. The lines are typically of the
+ form:</para>
+
+<screen>
+ ssh-dsa AAAABtce9euch.... user at example.com
+</screen>
+
+ <para>The first field describes the type of key, the second
+ field is the uuencoded key itself, and the third field is a
+ comment. However, it's a lesser known fact that the entire
+ line can be preceded by a <literal>command</literal>
+ field:</para>
+
+<screen>
+ command="program" ssh-dsa AAAABtce9euch.... user at example.com
+</screen>
+
+ <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
+ 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>
+
+<screen>
+ command="program" TYPE KEY COMMENT
+</screen>
+
+ </sect3>
+
+ <sect3 id="svn-ch-6-sect-3.5.2">
+ <title>Controlling the invoked command</title>
+
+ <para>Because we can specify the executed server-side command,
+ it's easy to name a specific <command>svnserve</command>
+ binary to run and to pass it extra arguments:</para>
+
+<screen>
+ command="/path/to/svnserve -t -r /virtual/root" TYPE KEY COMMENT
+</screen>
+
+ <para>In this example, <filename>/path/to/svnserve</filename>
+ might be a custom wrapper script
+ around <command>svnserve</command> which sets the umask (see
+ <xref linkend="svn-ch-6-sect-5"/>). It also shows how to
+ anchor <command>svnserve</command> in a virtual root
+ directory, just as one often does when
+ running <command>svnserve</command> as a daemon process.
+ This might be done either to restrict access to parts of the
+ system, or simply to relieve the user of having to type an
+ absolute path in the <literal>svn+ssh://</literal>
+ URL.</para>
+
+ <para>It's also possible to have multiple users share a single
+ account. Instead of creating a separate system account for
+ each user, generate a public/private keypair for each
+ person. Then place each public key into
+ the <filename>authorized_users</filename> file, one per
+ line, and use the <option>--tunnel-user</option>
+ option:</para>
+
+<screen>
+ command="svnserve -t --tunnel-user=harry" TYPE1 KEY1 harry at example.com
+ command="svnserve -t --tunnel-user=sally" TYPE2 KEY2 sally at example.com
+</screen>
+
+ <para>This example allows both Harry and Sally to connect to
+ 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
+ argument is the authenticated user. Without
+ <option>--tunnel-user</option>, it would appear as though
+ all commits were coming from the one shared system
+ account.</para>
+
+ <para>A final word of caution: giving a user access to the
+ server via public-key in a shared account might still allow
+ other forms of SSH access, even if you've set the
+ 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.
+ 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
+</screen>
+
+ </sect3>
+
+ </sect2>
+
</sect1>
@@ -841,10 +979,10 @@
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
- extension to HTTP 1.1 (see <systemitem
- class="url">http://www.webdav.org/</systemitem> for more
- information.) This protocol takes the ubiquitous HTTP protocol
- that is the core of the World Wide Web, and adds
+ extension to HTTP 1.1
+ (see <systemitem class="url">http://www.webdav.org/</systemitem>
+ for more information.) This protocol takes the ubiquitous HTTP
+ protocol that is the core of the World Wide Web, and adds
writing—specifically, versioned
writing—capabilities. The result is a standardized,
robust system that is conveniently packaged as part of the
@@ -1547,13 +1685,13 @@
<example id="svn-ch-6-sect-4.4.2-ex-1">
<title>A sample configuration for anonymous access.</title>
<programlisting>
- <Location /repos>
- DAV svn
- SVNParentPath /usr/local/svn
-
- # our access control policy
- AuthzSVNAccessFile /path/to/access/file
- </Location>
+<Location /repos>
+ DAV svn
+ SVNParentPath /usr/local/svn
+
+ # our access control policy
+ AuthzSVNAccessFile /path/to/access/file
+</Location>
</programlisting>
</example>
@@ -1567,21 +1705,21 @@
<example id="svn-ch-6-sect-4.4.2-ex-2">
<title>A sample configuration for authenticated access.</title>
<programlisting>
- <Location /repos>
- DAV svn
- SVNParentPath /usr/local/svn
+<Location /repos>
+ DAV svn
+ SVNParentPath /usr/local/svn
- # our access control policy
- AuthzSVNAccessFile /path/to/access/file
+ # our access control policy
+ AuthzSVNAccessFile /path/to/access/file
- # only authenticated users may access the repository
- Require valid-user
+ # only authenticated users may access the repository
+ Require valid-user
- # how to authenticate a user
- AuthType Basic
- AuthName "Subversion repository"
- AuthUserFile /path/to/users/file
- </Location>
+ # how to authenticate a user
+ AuthType Basic
+ AuthName "Subversion repository"
+ AuthUserFile /path/to/users/file
+</Location>
</programlisting>
</example>
@@ -1601,23 +1739,23 @@
<title>A sample configuration for mixed
authenticated/anonymous access.</title>
<programlisting>
- <Location /repos>
- DAV svn
- SVNParentPath /usr/local/svn
+<Location /repos>
+ DAV svn
+ SVNParentPath /usr/local/svn
- # our access control policy
- AuthzSVNAccessFile /path/to/access/file
+ # our access control policy
+ AuthzSVNAccessFile /path/to/access/file
- # try anonymous access first, resort to real
- # authentication if necessary.
- Satisfy Any
- Require valid-user
+ # try anonymous access first, resort to real
+ # authentication if necessary.
+ Satisfy Any
+ Require valid-user
- # how to authenticate a user
- AuthType Basic
- AuthName "Subversion repository"
- AuthUserFile /path/to/users/file
- </Location>
+ # how to authenticate a user
+ AuthType Basic
+ AuthName "Subversion repository"
+ AuthUserFile /path/to/users/file
+</Location>
</programlisting>
</example>
@@ -1818,12 +1956,12 @@
<example id="svn-ch-6-sect-4.4.3-ex-1">
<title>Disabling path checks altogether</title>
<programlisting>
- <Location /repos>
- DAV svn
- SVNParentPath /usr/local/svn
+<Location /repos>
+ DAV svn
+ SVNParentPath /usr/local/svn
- SVNPathAuthz off
- </Location>
+ SVNPathAuthz off
+</Location>
</programlisting>
</example>
Modified: trunk/src/nb/book/ch07.xml
==============================================================================
--- trunk/src/nb/book/ch07.xml (original)
+++ trunk/src/nb/book/ch07.xml Tue May 17 22:06:21 2005
@@ -1738,6 +1738,246 @@
</sect1>
<!-- ******************************************************************* -->
+ <!-- *** SECTION 2 1/2: ADDRESSING HISTORICAL AMBIGUITY *** -->
+ <!-- ******************************************************************* -->
+ <sect1 id="svn-ch-7-sect-2b">
+ <title>Addressing Historical Ambiguity</title>
+
+ <para>The ability to copy, move, and rename files and directories;
+ to be able to create an object, then delete it and then add a
+ new one at the same path—those are operations which we
+ perform on files and directories on our computers all the time,
+ and operations we tend to take for granted. And Subversion
+ would like you to think they are granted. Subversion's file
+ management support is quite liberating, affording almost as much
+ flexibility for versioned files that you'd expect when
+ manipulating your unversioned ones. But that flexibility means
+ that across the lifetime of your repository, a given versioned
+ resource might have many paths, and a given path might represent
+ serveral entirely different versioned resources.</para>
+
+ <para>Subversion is pretty smart about noticing when an object's
+ version history includes such <quote>changes of address</quote>.
+ For example, if you ask for all the logs of a particular file
+ that was renamed last week, Subversion happily provides all
+ those logs—the revision in which the rename itself
+ happened, plus the logs of relevant revisions both before and
+ after that rename. So, most of the time, you don't even have to
+ think about such things. But occasionally, Subversion needs
+ your help to clear up ambiguities.</para>
+
+ <para>The simplest example of this occurs when a directory or file
+ is deleted from version control, and then a new directory or
+ file is created with the same name and added to version control.
+ Clearly the thing you deleted and the thing you later added
+ aren't the same thing, they merely happen to have had the same
+ path, which we'll call <filename>/trunk/object</filename>.
+ What, then, does it mean to ask Subversion about the history of
+ <filename>/trunk/object</filename>? Are you asking about the
+ thing currently at that location, or the old thing you deleted
+ from that location? Are you asking about the operations that
+ have happened to all the objects that have lived at that path?
+ Clearly, Subversion needs a hint about what you are really
+ asking.</para>
+
+ <para>And thanks to moves, versioned resource history can get far
+ more twisted than that, even. 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
+ actually have some wings, so you do the unthinkable and decide
+ to give the project a name.
+ <footnote>
+ <para><quote>You're not supposed to name it. Once you name it,
+ you start getting attached to it.</quote> — Mike
+ Wazowski</para>
+ </footnote>
+ Let's say you called your software Frabnaggilywort. At this
+ point, it makes sense to rename the directory to reflect the
+ project's new name, so <filename>concept</filename> is renamed
+ to <filename>frabnaggilywort</filename>. Life goes on,
+ Frabnaggilywort releases a 1.0 version, and is downloaded and
+ used daily by hordes of people aiming to improve their
+ lives.</para>
+
+ <para>It's a nice story, really, but it doesn't end there.
+ Entrepreneur that you are, you've already got another think in
+ the tank. So you make a new directory,
+ <filename>concept</filename>, and the cycle begins again. In
+ fact, the cycle begins again many times over the years, each
+ time starting with that old <filename>concept</filename>
+ directory, then sometimes seeing that directory renamed as the
+ idea cures, sometimes seeing it deleted when you scrap the idea.
+ Or, to get really sick, maybe you rename
+ <filename>concept</filename> to something else for a while, but
+ later rename the thing back to <filename>concept</filename> for
+ some reason.</para>
+
+ <para>When scenarios like these occur, attempting to instruct
+ Subversion to work with these re-used 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
+ twenty 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>
+
+ <para>In version 1.1, Subversion introduced a way for you to tell
+ it exactly which Main Street you meant. It's called the
+ <firstterm>peg revision</firstterm>, and it is a revision
+ provided to Subversion for the sole purpose of identifying a
+ unique line of history. Because at most one versioned resource
+ may occupy a path at any given time—or, more precisely, in
+ any one revision—the combination of a path and a peg
+ revision is all that is needed to refer to a specific line of
+ history. Peg revisions are specified to the Subversion
+ command-line client using <firstterm>at syntax</firstterm>, so
+ called because the syntax involves appending an <quote>at
+ sign</quote> (<literal>@</literal>) and the peg revision to the
+ end of the path with which the revision is associated.</para>
+
+ <para>But what of the <option>--revision (-r)</option> of which
+ we've spoken so much in this book? That revision (or set of
+ revisions) is called the <firstterm>operative
+ revision</firstterm> (or <firstterm>operative revision
+ range</firstterm>). Once a particular line of history has been
+ identified using a path and peg revision, Subversion performs
+ the requested operation using the operative revision(s). To map
+ this to our Chicagoland streets analogy, if we are told to go to
+ 606 N. Main Street in Wheaton,
+ <footnote>
+ <para>606 N. Main Street, Wheaton, Illinois, is the home of
+ the Wheaton History Center. Get it—<quote>History
+ Center</quote>? It seemed appropriate….</para>
+ </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 which can travelled (north or
+ south on Main Street), and will keep us from travelling 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
+ go.</para>
+
+ <!-- Drop algorithm here -->
+
+ <para>Say long ago we created our repository, and in revision 1
+ 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 five years and twenty thousand 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
+ <emphasis>current</emphasis> file looked back in revision 1, or
+ are we 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 either of them. To find out how the
+ current <filename>IDEA</filename> file looked in that old
+ revision, you run:</para>
+
+ <screen>
+$ svn cat -r 1 concept/IDEA
+subversion/libsvn_client/ra.c:775: (apr_err=20014)
+svn: Unable to find repository location for 'concept/IDEA' in revision 1
+</screen>
+
+ <para>Of course, in this example, the current
+ <filename>IDEA</filename> file didn't exist yet in revision 1,
+ so Subversion gives an error. The command above is shorthand
+ for a longer notation which explicitly lists a peg revision.
+ The expanded notation is:</para>
+
+ <screen>
+$ svn cat -r 1 concept/IDEA at BASE
+subversion/libsvn_client/ra.c:775: (apr_err=20014)
+svn: Unable to find repository location for 'concept/IDEA' in revision 1
+</screen>
+
+ <para>And when executed, has the expected results. Peg revisions
+ generally default to a value of <literal>BASE</literal> (the
+ revision currently present in the working copy) when applied to
+ working copy paths, and of <literal>HEAD</literal> when applied
+ to URLs.</para>
+
+ <para>Let's ask the other question, then—in revision 1, what
+ were the contents of whatever file occupied the address
+ <filename>concepts/IDEA</filename> at the time? We'll use an
+ explicit peg revision to help us out.</para>
+
+ <screen>
+$ svn cat concept/IDEA at 1
+The idea behind this project is to come up with a piece of software
+that can frab a naggily wort. Frabbing naggily worts is tricky
+business, and doing it incorrectly can have serious ramifications, so
+we need to employ over-the-top input validation and data verification
+mechanisms.
+</screen>
+
+ <para>This appears to be the right output. The text even mentions
+ frabbing naggily worts, so this is almost certainly the file
+ which describes the software now called Frabnaggilywort. In
+ fact, we can verify this using the combination of an explicit
+ peg revision and explicit operative revision. We know that in
+ <literal>HEAD</literal>, the Frabnaggilywort project is located
+ in the <filename>frabnaggilywort</filename> directory. So we
+ specify that we want to see how the line of history identified
+ in <literal>HEAD</literal> as the path
+ <filename>frabnaggilywort/IDEA</filename> looked in revision
+ 1.</para>
+
+ <screen>
+$ svn cat -r 1 frabnaggilywort/IDEA at HEAD
+The idea behind this project is to come up with a piece of software
+that can frab a naggily wort. Frabbing naggily worts is tricky
+business, and doing it incorrectly can have serious ramifications, so
+we need to employ over-the-top input validation and data verification
+mechanisms.
+</screen>
+
+ <para>And the peg and operative revisions need not be so trivial,
+ either. For example, say <filename>frabnaggilywort</filename>
+ had beed deleted from <literal>HEAD</literal>, but we know it
+ existed in revision 20, and we want to see the diffs for its
+ <filename>IDEA</filename> file between revisions 4 and 10. We
+ can use the peg revision 20 in conjunction with the URL that
+ would have held Frabnaggilywort's <filename>IDEA</filename> file
+ in revision 20, and then use 4 and 10 as our operative revision
+ range.</para>
+
+ <screen>
+$ svn diff -r 4:10 http://svn.red-bean.com/projects/frabnaggilywort/IDEA@20
+Index: frabnaggilywort/IDEA
+===================================================================
+--- frabnaggilywort/IDEA (revision 4)
++++ frabnaggilywort/IDEA (revision 10)
+@@ -1,5 +1,5 @@
+-The idea behind this project is to come up with a piece of software
+-that can frab a naggily wort. Frabbing naggily worts is tricky
+-business, and doing it incorrectly can have serious ramifications, so
+-we need to employ over-the-top input validation and data verification
+-mechanisms.
++The idea behind this project is to come up with a piece of
++client-server software that can remotely frab a naggily wort.
++Frabbing naggily worts is tricky business, and doing it incorrectly
++can have serious ramifications, so we need to employ over-the-top
++input validation and data verification mechanisms.
+</screen>
+
+ <para>Fortunately, most folks aren't faced with such complex
+ situations. But when you are, remember that peg revisions are
+ that extra hint Subversion needs to clear up ambiguity.</para>
+
+ </sect1>
+
+ <!-- ******************************************************************* -->
<!-- *** SECTION 3: EXTERNALS DEFINITIONS *** -->
<!-- ******************************************************************* -->
<sect1 id="svn-ch-7-sect-3">
Modified: trunk/src/nb/book/ch09.xml
==============================================================================
--- trunk/src/nb/book/ch09.xml (original)
+++ trunk/src/nb/book/ch09.xml Tue May 17 22:06:21 2005
@@ -5342,6 +5342,14 @@
</varlistentry>
<varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Displays version information, a list of repository
+ back-end modules available, and exits.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>--root</option>=<replaceable>ROOT</replaceable>
(<option>-r</option>=<replaceable>ROOT</replaceable>)</term>
<listitem>
@@ -5532,6 +5540,139 @@
</refentry>
</sect1>
+ <!-- ================================================================= -->
+ <!-- ======================== SECTION 6 ============================== -->
+ <!-- ================================================================= -->
+ <sect1 id="svn-ch-9-sect-6">
+
+ <title><command>mod_dav_svn</command></title>
+
+ <refentry id="svn-ch-9-sect-6.1">
+ <refnamediv>
+
+ <refname><literal>mod_dav_svn</literal> Configuration
+ Directives</refname> <refpurpose>Apache configuration
+ directives for serving Subversion repositories through Apache
+ HTTP Server.</refpurpose>
+
+ </refnamediv>
+
+ <refsect1 id="svn-ch-9-sect-6.1.1">
+ <title>Description</title>
+
+ <para>This section briefly describes each of the Subversion
+ Apache configuration directives. For an in-depth
+ description of configuring Apache with Subversion, see <xref
+ linkend="svn-ch-6-sect-4"/>.)</para>
+
+ </refsect1>
+
+ <refsect1 id="svn-ch-9-sect-6.1.2">
+ <title>Directives</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><literal>DAV svn</literal></term>
+ <listitem>
+
+ <para>This directive must be included in any
+ <literal>Directory</literal> or
+ <literal>Location</literal> block for a Subversion
+ repository. It tells httpd to use the Subversion
+ backend for mod_dav to handle all requests.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>SVNPath</literal></term>
+ <listitem>
+
+ <para>This directive specifies the location in the
+ filesystem for a Subversion repository's files. In a
+ configuration block for a Subversion repository,
+ either this directive or
+ <literal>SVNParentPath</literal> must be present, but
+ not both.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>SVNSpecialURI</literal></term>
+ <listitem>
+
+ <para>Specifies the URI component (namespace) for
+ special Subversion resources. The default is
+ <quote><literal>!svn</literal></quote>, and most
+ administrators will never use this directive. Only
+ set this if there is a pressing need to have a file
+ named <filename>!svn</filename> in your repository. If
+ you change this on a server already in use, it will
+ break all of the outstanding working copies and your
+ users will hunt you down with pitchforks and flaming
+ torches.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>SVNReposName</literal></term>
+ <listitem>
+
+ <para>Specifies the name of a Subversion repository for
+ use in <literal>HTTP GET</literal> requests. This
+ value will be prepended to the title of all directory
+ listings (which are served when you navigate to a
+ Subversion repository with a web browser). This
+ directive is optional.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>SVNIndexXSLT</literal></term>
+ <listitem>
+
+ <para>Specifies the URI of an XSL transformation for
+ directory indexes. This directive is optional.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>SVNParentPath</literal></term>
+ <listitem>
+
+ <para>Specifies the location in the filesystem of a
+ parent directory whose child directories are
+ Subversion repositories. In a configuration block for
+ a Subversion repository, either this directive or
+ <literal>SVNPath</literal> must be present, but not
+ both.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>SVNPathAuthz</literal></term>
+ <listitem>
+
+ <para>Control path-based authorization by enabling or
+ disabling subrequests. See <xref
+ linkend="svn-ch-6-sect-4.4.3"/> for details.</para>
+
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+ </refentry>
+ </sect1>
+
+
+
</chapter>
<!--
Modified: trunk/src/nb/book/styles.css
==============================================================================
--- trunk/src/nb/book/styles.css (original)
+++ trunk/src/nb/book/styles.css Tue May 17 22:06:21 2005
@@ -112,19 +112,28 @@
.table table
{
- border: 1px rgb(180,180,180) solid;
- border-spacing: 0px;
+ border-width: 1px;
+ border-style: solid;
+ border-color: black;
+ border-spacing: 0;
+ background: rgb(240,240,240);
}
.table td
{
- border: 1px rgb(180,180,180) solid;
+ border: none;
+ border-right: 1px black solid;
+ border-bottom: 1px black solid;
+ padding: 2px;
}
.table th
{
background: rgb(180,180,180);
- border: 1px rgb(180,180,180) solid;
+ border: none;
+ border-right: 1px black solid;
+ border-bottom: 1px black solid;
+ padding: 2px;
}
.table p.title, .figure p.title, .example p.title
@@ -143,16 +152,28 @@
.sidebar
{
- border: solid 2px rgb(180,180,180);
- padding: 0.12in;
- margin: 1em 0.5in;
+ border-top: dotted 1px black;
+ border-left: dotted 1px black;
+ border-right: solid 2px black;
+ border-bottom: solid 2px black;
+ background: rgb(240,220,170);
+ padding: 0 0.12in;
+ margin: 0.5in;
+}
+
+.note .programlisting, .note .screen,
+.tip .programlisting, .tip .screen,
+.warning .programlisting, .warning .screen,
+.sidebar .programlisting, .sidebar .screen
+{
+ border: none;
+ background: none;
}
.sidebar p.title
{
text-align: center;
font-size: 125%;
- background: rgb(180,180,180);
}
.note
@@ -181,9 +202,6 @@
.programlisting, .screen
{
- font-family: courier new,courier,fixed;
- font-style: normal;
- font-weight: normal;
font-size: 90%;
color: black;
margin: 1em 0.5in;
More information about the svnbook-dev
mailing list