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

cmpilato noreply at red-bean.com
Wed Aug 15 09:30:05 CDT 2007


Author: cmpilato
Date: Wed Aug 15 09:30:05 2007
New Revision: 2856

Log:
Tweaks made or suggested by Eric Hanchrow.

Modified:
   trunk/src/en/book/ch05-repository-admin.xml

Modified: trunk/src/en/book/ch05-repository-admin.xml
==============================================================================
--- trunk/src/en/book/ch05-repository-admin.xml	(original)
+++ trunk/src/en/book/ch05-repository-admin.xml	Wed Aug 15 09:30:05 2007
@@ -92,8 +92,8 @@
       <varlistentry>
         <term>format</term>
         <listitem>
-          <para>A file whose contents are a single integer value that
-            dictates the version number of the repository layout.</para>
+          <para>A file that contains a single integer that
+            indicates the version number of the repository layout.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -148,8 +148,7 @@
       mindless repetition if you find yourself setting up multiples of
       these things.</para>
 
-    <para>Some of things you'll want to consider up front, though, are
-      as follows:</para>
+    <para>Some things you'll want to consider up front, though, are:</para>
 
     <itemizedlist>
       <listitem>
@@ -390,8 +389,8 @@
         at all because only one of the available back-ends will work
         in this scenario.</para>
 
-      <para>To try to address each and every possible way to deploy
-        Subversion is both not possible and outside the scope of this
+      <para>Addressing each possible way to deploy
+        Subversion is both impossible, and outside the scope of this
         book.  We simply encourage you to evaluate your options using
         these pages and other sources as your reference material, and
         plan ahead.</para>
@@ -420,7 +419,8 @@
             <quote>eff-ess-eff-ess</quote>.)</para>
         </footnote> 
         —a versioned filesystem implementation that uses the
-        native OS filesystem to store data.</para>
+        native OS filesystem directly—rather than via a database
+        library or some other abstraction layer—to store data.</para>
 
       <para><xref linkend="svn.reposadmin.basics.backends.tbl-1" />
         gives a comparative overview of Berkeley DB and FSFS
@@ -708,7 +708,7 @@
           waiting for a response.</para>
 
         <para>The most important distinction, however, is FSFS's
-          inability to be <quote>wedged</quote> when something goes
+          imperviousness to <quote>wedging</quote> when something goes
           wrong.  If a process using a Berkeley DB database runs into
           a permissions problem or suddenly crashes, the database can
           be left in an unusable state until an administrator recovers
@@ -843,7 +843,8 @@
         report what is about to happen and to prevent it from
         happening at all.  Other hooks (the <quote>post hooks</quote>)
         run after the completion of a repository event, and are useful
-        for reporting purposes only.  Each hook is handed enough
+        for performing tasks that examine—but don't
+        modify—the repository.  Each hook is handed enough
         information to tell what that event is (or was), the specific
         repository changes proposed (or completed), and the username
         of the person who triggered the event.</para>
@@ -886,9 +887,8 @@
         need to supply a program whose basename is the name of the
         hook, and whose extension is one of the special extensions
         recognized by Windows for executable programs, such as
-        <filename>.exe</filename> or <filename>.com</filename> for
-        programs, and <filename>.bat</filename> for batch
-        files.</para>
+        <filename>.exe</filename> for programs, and
+        <filename>.bat</filename> for batch files.</para>
 
       <tip>
         <para>For security reasons, the Subversion repository executes
@@ -902,28 +902,29 @@
           and/or use absolute paths to programs.</para>
       </tip>
 
-      <para>Subversion will attempt to execute hooks as the same user
-        who owns the process which is accessing the Subversion
-        repository.  In most cases, the repository is being accessed
-        via a Subversion server, so this user is the same user as
-        which that server runs on the system.  The hooks themselves
-        will need to be configured with OS-level permissions that
-        allow that user to execute them.  Also, this means that any
-        file or programs (including the Subversion repository itself)
-        accessed directly or indirectly by the hook will be accessed
-        as the same user.  In other words, be alert to potential
-        permission-related problems that could prevent the hook from
-        performing the tasks it is designed to perform.</para>
+      <para>Subversion executes hooks as the same user who owns the
+        process which is accessing the Subversion repository.  In most
+        cases, the repository is being accessed via a Subversion
+        server, so this user is the same user as which that server
+        runs on the system.  The hooks themselves will need to be
+        configured with OS-level permissions that allow that user to
+        execute them.  Also, this means that any file or programs
+        (including the Subversion repository itself) accessed directly
+        or indirectly by the hook will be accessed as the same user.
+        In other words, be alert to potential permission-related
+        problems that could prevent the hook from performing the tasks
+        it is designed to perform.</para>
 
       <para>There are nine hooks implemented by the Subversion
         repository, and you can get details about each of them in
         <xref linkend="svn.ref.reposhooks" />.  As a repository
         administrator, you'll need to decide which of hooks you wish
         to implement (by way of providing an appropriately named and
-        permissioned hook program), and how.  This decision needs to
-        be made with the bigger picture of how repository is deployed
-        in mind.  For example, if you are using server configuration
-        stuffs to determine which usernames are permitted to commit
+        permissioned hook program), and how.  When you make this
+        decision, keep in mind
+        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
         sort of access control via the hook system.</para>
 
@@ -938,9 +939,9 @@
         linkend="svn.developer" />.</para>
 
       <warning>
-        <para>While hook scripts can be leveraged to do almost
+        <para>While hook scripts can do almost
           anything, there is one dimension in which hook script
-          authors should show restraint: do <emphasis>not</emphasis>
+          authors should show restraint:  do <emphasis>not</emphasis>
           modify a commit transaction using hook scripts.  While it
           might be tempting to use hook scripts to automatically
           correct errors or shortcomings or policy violations present
@@ -952,7 +953,7 @@
           behavior.  Instead of modifying the transaction, you should
           simply <emphasis>validate</emphasis> the transaction in the
           <filename>pre-commit</filename> hook and reject the commit
-          if it does not meet the desired requirements.  As an added
+          if it does not meet the desired requirements.  As a
           bonus, your users will learn the value of careful,
           compliance-minded work habits.</para>
       </warning>
@@ -979,15 +980,10 @@
         applications and database environments have different
         requirements, and so they have provided a mechanism for
         overriding at runtime many of the configuration values for the
-        Berkeley DB environment.  Berkeley checks for the presence of
+        Berkeley DB environment:  BDB checks for the presence of
         a file named <filename>DB_CONFIG</filename> in the environment
-        directory, and parses the options found in that file for use
-        with that particular Berkeley DB environment.</para>
-
-      <para>The Berkeley DB configuration file for a BDB-backed
-        repository is located in the repository's
-        <filename>db</filename> subdirectory, at
-        <filename>db/DB_CONFIG</filename>.  Subversion itself creates
+        directory (namely, the repository's
+        <filename>db</filename> subdirectory), and parses the options found in that file .  Subversion itself creates
         this file when it creates the rest of the repository.  The
         file initially contains some default options, as well as
         pointers to the Berkeley DB online documentation so you can
@@ -1013,7 +1009,7 @@
   <sect1 id="svn.reposadmin.maint">
     <title>Repository Maintenance</title>
 
-    <para>Maintaining a Subversion repository can be a daunting task,
+    <para>Maintaining a Subversion repository can be daunting,
       mostly due to the complexities inherent in systems which have a
       database backend.  Doing the task well is all about knowing the
       tools—what they are, when to use them, and how to use
@@ -1062,7 +1058,7 @@
         <para>We've already mentioned <command>svnadmin</command>'s
           <literal>create</literal> subcommand (see <xref
           linkend="svn.reposadmin.basics.creating"/>).  Most of the
-          others we will cover as they become topically relevant later
+          others we will cover later
           in this chapter.  And you can consult <xref
           linkend="svn.ref.svnadmin" /> for a full rundown of
           subcommands and what each of them offers.</para>
@@ -1075,7 +1071,8 @@
             
         <para><command>svnlook</command> is a tool provided by
           Subversion for examining the various revisions and
-          transactions in a repository.  No part of this program
+          <firstterm>transactions</firstterm> (which are revisions
+          in-the-making) in a repository.  No part of this program
           attempts to change the repository.  <command>svnlook</command>
           is typically used by the repository hooks for reporting the
           changes that are about to be committed (in the case of the
@@ -1184,7 +1181,7 @@
           the stream.</para>
 
         <para><command>svnlook</command> can perform a variety of
-          other queries: displaying subsets of bits of information
+          other queries:  displaying subsets of bits of information
           we've mentioned previously, recursively listing versioned
           directory trees, reporting which paths were modified in a
           given revision or transaction, showing textual and property
@@ -1315,15 +1312,23 @@
           recover</command> reflects the common use cases of the
           <command>db_recover</command> utility.</para>
             
-        <para>There are still a few Berkeley DB utilities that you
-          might find useful.  The <command>db_dump</command> and
-          <command>db_load</command> programs write and read,
+        <para>However, there are still a few Berkeley DB utilities
+          that you might find useful.  The <command>db_dump</command>
+          and <command>db_load</command> programs write and read,
           respectively, a custom file format which describes the keys
           and values in a Berkeley DB database.  Since Berkeley
           databases are not portable across machine architectures,
           this format is a useful way to transfer those databases from
           machine to machine, irrespective of architecture or
-          operating system.  Also, the <command>db_stat</command>
+          operating system.  As we describe later in this chapter, you
+          can also use <command>svnadmin dump</command> and
+          <command>svnadmin load</command> for similar purposes, but
+          <command>db_dump</command> and <command>db_load</command>
+          can do certain jobs just as well and much faster.  They can
+          also be useful if the experienced Berkeley DB hacker needs
+          to do in-place tweaking of the data in a BDB-backed
+          repository for some reason, which is something Subversion's
+          utilities won't allow.  Also, the <command>db_stat</command>
           utility can provide useful information about the status of
           your Berkeley DB environment, including detailed statistics
           about the locking and storage subsystems.</para>
@@ -1344,16 +1349,16 @@
       <para>Sometimes a user will have an error in her log message (a
         misspelling or some misinformation, perhaps).  If the
         repository is configured (using the
-        <literal>pre-revprop-change</literal> and
-        <literal>post-revprop-change</literal> hooks; see <xref
-        linkend="svn.reposadmin.create.hooks"/>) to accept changes to this log
-        message after the commit is finished, then the user can
-        <quote>fix</quote> her log message remotely using the
+        <literal>pre-revprop-change</literal> hook; see <xref
+        linkend="svn.reposadmin.create.hooks"/>) to accept changes to
+        this log message after the commit is finished, then the user
+        can <quote>fix</quote> her log message remotely using the
         <command>svn</command> program's <literal>propset</literal>
-        command (see <xref linkend="svn.ref"/>).  However, because of
-        the potential to lose information forever, Subversion
-        repositories are not, by default, configured to allow changes
-        to unversioned properties—except by an administrator.</para>
+        command (see <xref linkend="svn.ref.svn.c.propset"/>).
+        However, because of the potential to lose information forever,
+        Subversion repositories are not, by default, configured to
+        allow changes to unversioned properties—except by an
+        administrator.</para>
 
       <para>If a log message needs to be changed by an administrator,
         this can be done using <command>svnadmin setlog</command>.
@@ -1366,12 +1371,13 @@
 $ svnadmin setlog myrepos newlog.txt -r 388
 </screen>
       
-      <para>The <command>svnadmin setlog</command> command alone is
+      <para>The <command>svnadmin setlog</command> command, by
+        default, is
         still bound by the same protections against modifying
         unversioned properties as a remote client is—the
         <literal>pre-</literal> and
         <literal>post-revprop-change</literal> hooks are still
-        triggered, and therefore must be setup to accept changes of
+        triggered, and therefore must be set up to accept changes of
         this nature.  But an administrator can get around these
         protections by passing the <option>--bypass-hooks</option>
         option to the <command>svnadmin setlog</command> command.</para>
@@ -1396,7 +1402,7 @@
         past few years, disk usage is still a valid concern for
         administrators seeking to version large amounts of data.
         Every bit of version history information stored in the live
-        repository is information that needs to be backed up
+        repository needs to be backed up
         elsewhere, perhaps multiple times as part of rotating backup
         schedules.  It is useful to know what pieces of Subversion's
         repository data need to remain on the live site, which need to
@@ -1406,7 +1412,7 @@
       <sect3 id="svn.reposadmin.maint.diskspace.deltas">
         <title>How Subversion saves disk space</title>
 
-        <para>To keep the size of the repository as small as possible,
+        <para>To keep the repository small,
           Subversion uses <firstterm>deltification</firstterm> (or,
           <quote>deltified storage</quote>) within the repository
           itself.  Deltification involves encoding the representation
@@ -1418,11 +1424,11 @@
           enough space to say, <quote>I look just like this other
           piece of data over here, except for the following couple of
           changes</quote>.  The result is that most of the repository
-          data that tends to be sizable—namely, the contents of
+          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
           data.  And for repositories created with Subversion 1.4 or
-          later, the space saving get even better—now those
+          later, the space savings are even better—now those
           fulltext representations of file contents are themselves
           compressed.</para>
 
@@ -1450,9 +1456,9 @@
           in the repository the remnants of the revision-to-be that
           wasn't—an uncommitted transaction and all the file and
           directory changes associated with it.  This could happen for
-          several reasons: perhaps the client operation was
+          several reasons:  perhaps the client operation was
           inelegantly terminated by the user, or a network failure
-          might have occurred in the middle of an operation, etc.
+          occurred in the middle of an operation.
           Regardless of the reason, dead transactions can happen.
           They don't do any real harm, other than consuming disk
           space.  A fastidious administrator may nonetheless wish to
@@ -1476,7 +1482,8 @@
           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 removal!  If so, the transaction's name
+          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, the
           <literal>rmtxns</literal> subcommand can take its input
@@ -1569,21 +1576,21 @@
           before modifying the actual database files.  These files
           capture all the actions taken along the route of changing
           the database from one state to another—while the
-          database files reflect at any given time some state, the log
-          files contain all the many changes along the way between
-          states.  As such, they can grow and accumulate quite
+          database files, at any given time, reflect a particular state, the log
+          files contain all the many changes along the way <emphasis>between</emphasis>
+          states.  Thus, they can grow and accumulate quite
           rapidly.</para>
 
         <para>Fortunately, beginning with the 4.2 release of Berkeley
           DB, the database environment has the ability to remove its
-          own unused log files without any external procedures.  Any
+          own unused log files automatically.  Any
           repositories created using an <command>svnadmin</command>
           which is compiled against Berkeley DB version 4.2 or greater
           will be configured for this automatic log file removal.  If
           you don't want this feature enabled, simply pass the
           <option>--bdb-log-keep</option> option to the
           <command>svnadmin create</command> command.  If you forget
-          to do this, or change your mind at a later time, simple edit
+          to do this, or change your mind at a later time, simply edit
           the <filename>DB_CONFIG</filename> file found in your
           repository's <filename>db</filename> directory, comment out
           the line which contains the <literal>set_flags
@@ -1610,8 +1617,8 @@
 /path/to/repos/log.0000000031
 /path/to/repos/log.0000000032
 /path/to/repos/log.0000000033
-
-$ svnadmin list-unused-dblogs /path/to/repos | xargs rm
+…
+$ rm `svnadmin list-unused-dblogs /path/to/repos`
 ## disk space reclaimed!
 </screen>
 
@@ -1620,8 +1627,8 @@
             as part of a backup or disaster recovery plan should
             <emphasis>not</emphasis> make use of the log file
             autoremoval feature.  Reconstruction of a repository's
-            data from log files can only be accomplished when the log
-            files are all available.  If some of the log files are
+            data from log files can only be accomplished when <emphasis>all</emphasis> the log
+            files are available.  If some of the log files are
             removed from disk before the backup system has a chance to
             copy them elsewhere, the incomplete set of backed-up log
             files is essentially useless.</para>
@@ -1679,7 +1686,7 @@
         transactions and checkpoints and pre-write journaling to
         ensure that only the most catastrophic of events
         <footnote>
-          <para>E.g.: hard drive + huge electromagnet = disaster.</para>
+          <para>E.g.:  hard drive + huge electromagnet = disaster.</para>
         </footnote>
         can permanently destroy a database environment.  A
         sufficiently paranoid repository administrator will have made
@@ -1736,12 +1743,13 @@
 
       <para>If the previous procedure, for some reason, does not
         successfully unwedge your repository, you should do two
-        things.  First, move your broken repository out of the way and
-        restore your latest backup of it.  Then, send an email to the
-        Subversion user list (at
-        <email>users at subversion.tigris.org</email>) describing your
-        problem in detail.  Data integrity is an extremely high
-        priority to the Subversion developers.</para>
+        things.  First, move your broken repository directory aside
+        (perhaps by renaming it to something like
+        <filename>repos.BROKEN</filename>) and then restore your
+        latest backup of it.  Then, send an email to the Subversion
+        user list (at <email>users at subversion.tigris.org</email>)
+        describing your problem in detail.  Data integrity is an
+        extremely high priority to the Subversion developers.</para>
 
     </sect2>
 
@@ -1750,7 +1758,7 @@
       <title>Migrating Repository Data Elsewhere</title>
     
       <para>A Subversion filesystem has its data spread throughout
-        various back-end data store files in a fashion generally
+        files in the repository, in a fashion generally
         understood by (and of interest to) only the Subversion
         developers themselves.  However, circumstances may arise that
         call for all, or some subset, of that data to be copied or
@@ -1774,10 +1782,9 @@
           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
-          file format.  The format should be treated as a binary file
-          format, highly sensitive to meddling.  Many text editor
-          tools will corrupt the file's contents, often due to
-          automatic line ending character conversion.</para>
+          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>
       </warning>
 
       <para>There are many reasons for dumping and loading Subversion
@@ -1800,7 +1807,7 @@
         linkend="svn.reposadmin.maint.filtering" />) purging versioned
         data from repository history.</para>
 
-      <para>Whatever your reason for migration repository history,
+      <para>Whatever your reason for migrating repository history,
         using the <command>svnadmin dump</command> and
         <command>svnadmin load</command> subcommands is
         straightforward.  <command>svnadmin dump</command> will output
@@ -1830,7 +1837,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
+        (<command>svn checkout</command>, for example), so it's safe
         to run this command at any time.</para>
 
       <para>The other subcommand in the pair, <command>svnadmin
@@ -1885,8 +1892,7 @@
         course, you should use these options with care—if your
         post-commit hook sends emails to a mailing list for each new
         commit, you might not want to spew hundreds or thousands of
-        commit emails in rapid succession at that list for each of the
-        loaded revisions!  You can read more about the use of hook
+        commit emails in rapid succession at that list!  You can read more about the use of hook
         scripts in <xref
         linkend="svn.reposadmin.create.hooks"/>.</para>
 
@@ -1898,7 +1904,7 @@
   
       <screen>
 $ svnadmin create newrepos
-$ svnadmin dump myrepos | svnadmin load newrepos
+$ svnadmin dump oldrepos | svnadmin load newrepos
 </screen>
 
       <para>By default, the dump file will be quite large—much
@@ -1942,7 +1948,7 @@
         revision.  For one thing, there is no previous revision in the
         dump file!  And secondly, Subversion cannot know the state of
         the repository into which the dump data will be loaded (if it
-        ever, in fact, occurs).  To ensure that the output of each
+        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
         full representation of every directory, file, and property in
@@ -1984,7 +1990,7 @@
         nightly to append dump file data for all the revisions that
         were added to the repository since the last time the script
         ran.  Used like this, <command>svnadmin dump</command> can be
-        one way to backup changes to your repository over time in case
+        one way to back up changes to your repository over time in case
         of a system crash or some other catastrophic event.</para>
 
       <para>The dump format can also be used to merge the contents of
@@ -2192,8 +2198,8 @@
       <warning>
         <para>If you do plan on manually editing the dump file to
           remove a top-level directory, make sure that your editor is
-          not set to automatically convert end-lines to the native
-          format (e.g. \r\n to \n) as the content will then not agree
+          not set to automatically convert end-of-line characters to the native
+          format (e.g. \r\n to \n), as the content will then not agree
           with the metadata.  This will render the dump file
           useless.</para>
       </warning>
@@ -2307,7 +2313,9 @@
         revision, the contents of the copy source might not be
         readily available.  If you suspect that you have any copies
         of this sort in your repository, you might want to rethink
-        your set of included/excluded paths.</para>
+        your set of included/excluded paths, perhaps including the
+        paths that served as sources of your troublesome copy
+        operations, too.</para>
 
       <para>Finally, <command>svndumpfilter</command> takes path
         filtering quite literally.  If you are trying to copy the
@@ -2525,7 +2533,7 @@
         initialize</command> subcommand.  Note that the various
         <command>svnsync</command> subcommands provide several of the
         same authentication-related options that
-        <command>svn</command> does: <option>--username</option>,
+        <command>svn</command> does:  <option>--username</option>,
         <option>--password</option>,
         <option>--non-interactive</option>,
         <option>--config-dir</option>, and
@@ -2665,7 +2673,7 @@
         time throughout the lifetime of the repository, and don't
         leave an audit trail that indicates when they were changed,
         replication processes have to pay special attention to them.
-        If you've already mirror the first 15 revisions of a
+        If you've already mirrored the first 15 revisions of a
         repository and someone then changes a revision property on
         revision 12, <command>svnsync</command> won't know to go back
         and patch up its copy of revision 12.  You'll need to tell it
@@ -2729,10 +2737,15 @@
         linkend="svn.ref.svn.c.switch" />.  There is a possible danger
         here, though, in that if the primary and mirror repositories
         aren't in close synchronization, a working copy up-to-date
-        with and pointing to the primary repository will, if relocated
-        to point to an out-of-date mirror, become confused about the
-        apparent sudden loss of revisions it fully expects to be
-        present.</para>
+        with, and pointing to, the primary repository will, if
+        relocated to point to an out-of-date mirror, become confused
+        about the apparent sudden loss of revisions it fully expects
+        to be present, and throws errors to that effect.  If this
+        occurs, you can relocate your working copy back to the primary
+        repository and then either wait until the mirror repository is
+        up-to-date, or backdate your working copy to a revision you
+        know is present in the sync repository and then retry the
+        relocation.</para>
 
       <para>Finally, be aware that the revision-based replication
         provided by <command>svnsync</command> is only
@@ -2764,7 +2777,7 @@
         incremental.  A full backup of the repository involves
         squirreling away in one sweeping action all the information
         required to fully reconstruct that repository in the event of
-        a catastrophe.  Usually, it means quite literally the
+        a catastrophe.  Usually, it means, quite literally, the
         duplication of the entire repository directory (which includes
         either a Berkeley DB or FSFS environment).  Incremental
         backups are lesser things, backups of only the portion of the
@@ -2822,7 +2835,7 @@
         <command>hot-backup.py</command> from a program scheduler
         (such as <command>cron</command> on Unix systems) which will
         cause it to run nightly (or at whatever granularity of Time
-        you deem safe enough for you).</para>
+        you deem safe).</para>
 
       <para>Some administrators use a different backup mechanism built
         around generating and storing repository dump data.  We
@@ -2831,7 +2844,7 @@
         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>
-        option to that command.  There is some value in these methods
+        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,
         versioned filesystem type, or release of Subversion or




More information about the svnbook-dev mailing list