[svnbook commit] r2698 - trunk/src/en/book

sussman noreply at red-bean.com
Sat Feb 24 21:25:48 CST 2007


Author: sussman
Date: Sat Feb 24 21:25:47 2007
New Revision: 2698

Modified:
   trunk/src/en/book/ch-branching-and-merging.xml
   trunk/src/en/book/ch-server-configuration.xml

Log:
 * src/en/book/ch-server-configuration.xml:  rewrite the beginning of the chapter, per cmpilato's suggestions.

Modified: trunk/src/en/book/ch-branching-and-merging.xml
==============================================================================
--- trunk/src/en/book/ch-branching-and-merging.xml	(original)
+++ trunk/src/en/book/ch-branching-and-merging.xml	Sat Feb 24 21:25:47 2007
@@ -1275,11 +1275,13 @@
         merge</command> to <quote>undo</quote> the change in your
         working copy, and then commit the local modification to the
         repository.  All you need to do is to specify a
-        <emphasis>reverse</emphasis> difference:</para>
+        <emphasis>reverse</emphasis> difference.  (You can do this by
+        specifying <option>--revision 303:302</option>, or by an
+        equivalent <option>--change -303</option>.)</para>
 
 
       <screen>
-$ svn merge -r 303:302 http://svn.example.com/repos/calc/trunk
+$ svn merge -c -303 http://svn.example.com/repos/calc/trunk
 U  integer.c
 
 $ svn status

Modified: trunk/src/en/book/ch-server-configuration.xml
==============================================================================
--- trunk/src/en/book/ch-server-configuration.xml	(original)
+++ trunk/src/en/book/ch-server-configuration.xml	Sat Feb 24 21:25:47 2007
@@ -35,20 +35,52 @@
     <para>Apache is an extremely popular webserver; 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.  In the
-      other corner is <command>svnserve</command>: a small, standalone
-      server program that speaks a custom protocol with clients.
-      <xref linkend="svn.serverconfig.overview.tbl-1"/> presents a
-      comparison of the two servers.</para>
+      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>
+
+    <para>In the other corner is <command>svnserve</command>: a small,
+      lightweight server program that speaks a custom protocol with
+      clients.  Because its protocol is explicitly designed for
+      Subversion and is stateful (unlike HTTP), it provides
+      significantly faster network operations—but at the cost of
+      some features as well.  It only understands CRAM-MD5
+      authentication, has no logging, no web-browsing, and no option
+      to encrypt network traffic.  It is, however, extremely easy to
+      set up and is often the best option for small teams just
+      starting out with Subversion.</para>
+
+    <para>A third option is to use <command>svnserve</command>
+      tunneled over an SSH connection.  Even though this scenario
+      still uses <command>svnserve</command>, it differs quite a bit
+      in features from a traditional <command>svnserve</command>
+      deployment.  SSH is used to encrypt all communication.  SSH is
+      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 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
+      via <literal>file://</literal> URLs. Path-based access control
+      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>
 
     <table id="svn.serverconfig.overview.tbl-1">
-      <title>Network Server Comparison</title>
+      <title>Comparison of Subversion Server Options</title>
       <tgroup cols="3">
         <thead>
           <row>
             <entry>Feature</entry>
             <entry>Apache + mod_dav_svn</entry>
             <entry>svnserve</entry>
+            <entry>svnserve over SSH</entry>
           </row>
         </thead>
         <tbody>
@@ -56,14 +88,15 @@
             <entry>Authentication options</entry>
             <entry>HTTP(S) basic auth, X.509 certificates, LDAP, NTLM, or
               any other mechanism available to Apache httpd</entry>
-            <entry>CRAM-MD5 or SSH</entry>
+            <entry>CRAM-MD5</entry>
+            <entry>SSH</entry>
           </row>
 
           <row>
             <entry>User account options</entry>
             <entry>private 'users' file</entry>
-            <entry>private 'users' file, or existing system (SSH)
-              accounts</entry>
+            <entry>private 'users' file</entry>
+            <entry>system accounts</entry>
           </row>
 
           <row>
@@ -72,12 +105,15 @@
               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
+              repository</entry>
           </row>
 
           <row>
             <entry>Encryption</entry>
             <entry>via optional SSL</entry>
-            <entry>via optional SSH tunnel</entry>
+            <entry>none</entry>
+            <entry>SSH tunneled</entry>
           </row>
 
           <row>
@@ -86,12 +122,14 @@
             optional <quote>high-level</quote> logging of general
             client operations</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>
           </row>
 
           <row>
@@ -99,100 +137,49 @@
             <entry>limited built-in support, or via 3rd-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>
           </row>
 
           <row>
             <entry>Speed</entry>
             <entry>somewhat slower</entry>
             <entry>somewhat faster</entry>
+            <entry>somewhat faster</entry>
           </row>
 
           <row>
             <entry>Initial setup</entry>
             <entry>somewhat complex</entry>
-            <entry>fairly simple</entry>
+            <entry>extremely simple</entry>
+            <entry>moderately simple </entry>
           </row>
 
         </tbody>
       </tgroup>
     </table>
 
+  </sect1>
 
+  <sect1 id="svn.serverconfig.choosing">
 
-    <sect2 id="svn.serverconfig.overview.apache">
-
-      <title>The Apache HTTP Server</title>
-
-      <para>The Apache HTTP Server is a well-established, full-featured
-        web server program.  But when you extend this server with the
-        <command>mod_dav_svn</command> Subversion server module, the
-        Apache HTTP Server becomes a Subversion server, too.  Clients
-        speak to server via HTTP or HTTPS, using the WebDAV/DeltaV
-        protocol.</para>
-
-      <variablelist>
-        <varlistentry>
-          <term>Why you might want to use it:</term>
-          <listitem>
-            <itemizedlist>
-
-              <listitem><para>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>Full Apache logging.</para></listitem>
-
-              <listitem><para>Network traffic can be encrypted via
-                  SSL.</para></listitem>
-
-              <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>Repository can be mounted as a network
-                  drive for transparent version control. (See
-                  <xref
-                  linkend="svn.webdav.autoversioning"/>.)</para></listitem>
-
-            </itemizedlist>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>Why you might want to avoid it:</term>
-          <listitem>
-            <itemizedlist>
-
-            <listitem><para>Noticeably slower than svnserve, because
-                HTTP is a stateless protocol and requires more
-                turnarounds.</para></listitem>
+    <title>Choosing a Server Configuration</title>
 
-            <listitem><para>Initial setup can be complex.</para></listitem>
+    <para>So, which server should you use?  Which is best?</para>
 
-            </itemizedlist>
-          </listitem>
-        </varlistentry>
+    <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
+      itself doesn't endorse one server or another, or consider either
+      server more <quote>official</quote> than another.</para>
 
-      </variablelist>
+    <para>Here are some reasons why you might choose one deployment
+      over another, as well as reasons you
+      might <emphasis>not</emphasis> choose one.</para>
 
-    </sect2>
-
-
-    <sect2 id="svn.serverconfig.overview.svnserve">
+    <sect2 id="svn.serverconfig.choosing.svnserve">
 
       <title>The <command>svnserve</command> Server</title>
 
-      <para><command>svnserve</command> is a lightweight server
-        process which can run either as a persistent daemon, or as
-        something automatically launched by inetd when necessary.
-        Clients authenticate via the CRAM-MD5 algorithm and speak a
-        network protocol that is custom to Subversion.</para>
-
       <variablelist>
         <varlistentry>
           <term>Why you might want to use it:</term>
@@ -240,21 +227,10 @@
 
     </sect2>
 
-    <sect2 id="svn.serverconfig.overview.svn-ssh">
+    <sect2 id="svn.serverconfig.choosing.svn-ssh">
 
       <title><command>svnserve</command> over SSH</title>
 
-      <para><command>svnserve</command> can be invoked via SSH to
-        handle Subversion client communication tunneled across that
-        protocol.  Each Subversion client uses an existing
-        SSH-accessed system account to spawn a temporary
-        <command>svnserve</command> process (running as themselves) on
-        the server machine.  The <command>svnserve</command> process
-        accesses the repository, communicates with the client over the
-        SSH tunnel, then dies when the SSH connection is closed.
-        (There is no long-running <command>svnserve</command>
-        process.)</para>
-
       <variablelist>
         <varlistentry>
           <term>Why you might want to use it:</term>
@@ -299,18 +275,65 @@
 
     </sect2>
 
-    <sect2 id="svn.serverconfig.overview.choosing-a-server">
+    <sect2 id="svn.serverconfig.choosing.apache">
 
-      <title>Choosing the Best Server Configuration</title>
+      <title>The Apache HTTP Server</title>
+
+      <variablelist>
+        <varlistentry>
+          <term>Why you might want to use it:</term>
+          <listitem>
+            <itemizedlist>
+
+              <listitem><para>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>Full Apache logging.</para></listitem>
+
+              <listitem><para>Network traffic can be encrypted via
+                  SSL.</para></listitem>
+
+              <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>Repository can be mounted as a network
+                  drive for transparent version control. (See
+                  <xref
+                  linkend="svn.webdav.autoversioning"/>.)</para></listitem>
+
+            </itemizedlist>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>Why you might want to avoid it:</term>
+          <listitem>
+            <itemizedlist>
+
+            <listitem><para>Noticeably slower than svnserve, because
+                HTTP is a stateless protocol and requires more
+                turnarounds.</para></listitem>
+
+            <listitem><para>Initial setup can be complex.</para></listitem>
+
+            </itemizedlist>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+    </sect2>
 
-      <para>So, which server should you use?  Which is best?</para>
+    <sect2 id="svn.serverconfig.choosing.recommendations">
 
-      <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
-        itself doesn't endorse one server or another, or consider
-        either server more <quote>official</quote> than
-        another.</para>
+      <title>Recommendations</title>
 
       <para>In general, the authors of this book recommend a vanilla
         <command>svnserve</command> installation for small teams just
@@ -319,8 +342,8 @@
         Remember, you can always switch to a more complex server
         deployment as your needs change.</para>
 
-      <para>Here are some general recommendations, based on years of
-        supporting users:</para>
+      <para>Here are some general recommendations and tips, based on
+        years of supporting users:</para>
 
       <itemizedlist>
         <listitem>




More information about the svnbook-dev mailing list