[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Updates to ch02.xml

From: Matt Blais <mblais1_at_yummage.com>
Date: 2003-08-15 16:51:31 CEST

Minor readability changes, plus a couple error corrections.

D:\Collabnet\svn\trunk\doc\book\book>svn diff ch02.xml
Index: ch02.xml
===================================================================
--- ch02.xml (revision 6740)
+++ ch02.xml (working copy)
@@ -74,7 +74,7 @@
       <para>All version control systems have to solve the same
         fundamental problem: how will the system allow users to share
         information, but prevent them from accidentally stepping on
- each other's feet? It's all too easy for users to
+ each other's toes? It's all too easy for users to
         accidentally overwrite each other's changes in the
         repository.</para>
 
@@ -143,7 +143,7 @@
             These changes don't overlap at all. They could easily
             edit the file simultaneously, and no great harm would
             come, assuming the changes were properly merged together.
- There's no need for them to take turns in this
+ There's no reason why they should have to take turns in
+ this
             situation.</para></listitem>
     
         <listitem><para>
@@ -154,11 +154,11 @@
             that A and B depend on one another, and the changes made
             to each are semantically incompatible. Suddenly A and B
             don't work together anymore. The locking system was
- powerless to prevent the problem&mdash;yet it somehow
- provided a sense of false security. It's easy for Harry
and
- Sally to imagine that by locking files, each is beginning a
- safe, insulated task, and thus inhibits them from
- discussing their incompatible changes early
+ powerless to prevent the problem&mdash;yet it can
+ provide a false sense of security. It's easy for Harry and
+ Sally to imagine that by locking files, they are each
beginning a
+ safe, insulated task; thus they are inhibited from
+ discussing their incompatible changes with each other early
             on.</para></listitem>
       </itemizedlist>
 
@@ -167,30 +167,40 @@
     <sect2 id="svn-ch-2-sect-2.3">
       <title>The Copy-Modify-Merge Solution</title>
       
- <para>Subversion, CVS, and other version control systems use a
- <firstterm>copy-modify-merge</firstterm> model as an
- alternative to locking. In this model, each user's client
+ <para>In contrast to the Lock-Modify-Unlock model described
above,
+ a very different approach known as the
+ <firstterm>copy-modify-merge</firstterm> model is taken by
+ Subversion, CVS, and other version control systems.
+ In this model, each user's client
         reads the repository and creates a personal <firstterm>working
         copy</firstterm> of the file or project. Users then work in
- parallel, modifying their private copies. Finally, the
+ parallel, each modifying their own private working copy.
+ Finally, these
         private copies are merged together into a new, final version.
         The version control system often assists with the merging, but
- ultimately a human being is responsible for making it happen
+ ultimately a human beings is responsible for ensuring that
+ merging happens
         correctly.</para>
       
- <para>Here's an example. Say that Harry and Sally each create
- working copies of the same project, copied from the
- repository. They work concurrently, and make changes to the
- same file "A" within their copies. Sally saves her changes to
+ <para>Here's an example. Let's say that Harry and Sally each
create
+ their own working copy of a project from the
+ repository. They work concurrently, and each makes changes to
their
+ own copy of the same file "A". 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
- A in the repository has somehow changed since he last copied
+ later, the repository informs him that his file "A" is
+ <firstterm>out-of-date</firstterm>. In other words, 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
- file A. Chances are that Sally's changes don't overlap with
- his own; so once he has both sets of changes integrated, he
- saves his working copy back to the repository.</para>
+ any new changes from the repository (i.e., Sally's changes)
into his working copy of
+ file "A". Now Harry's file "A" contains both his own changes
+ and Sally's.</para>
+
+ <para>The chances are good that Sally's changes don't overlap
with
+ Harry's; if this is the case then both sets of changes are
integrated
+ in Harry's working copy, he simply saves it back to the
repository.
+ Now the new version of file "A" in the repository
+ contains <emphasis>both</emphasis> Sally's changes
<emphasis>and</emphasis> Harry's.
+ Neither Sally nor Harry was forced to wait while the other
edited the file,
+ nor did they need to know that the other person was
simultaneously editing it.
+ </para>
 
       <figure id="svn-ch2-dia4">
         <title>The Copy-Modify-Merge Solution</title>
@@ -207,7 +217,7 @@
         <firstterm>conflict</firstterm>, and it's usually not much of
         a problem. When Harry asks his client to merge the latest
         repository changes into his working copy, his copy of file A
- is somehow flagged as being in a state of conflict: he'll be
+ will be flagged as being in a state of conflict: he'll be
         able to see both sets of conflicting changes, and manually
         choose between them. Note that software can't automatically
         resolve conflicts; only humans are capable of understanding @@
-217,21 +227,21 @@
         merged file back to the repository.</para>
 
       <para>The copy-modify-merge model may sound a bit chaotic, but
- in practice, it runs extremely smoothly. Users can work in
- parallel, never waiting for one another. When they work on
+ in practice, it runs very smoothly. Users can work in
+ parallel, never having to wait for one another. When they work

+ on
         the same files, it turns out that most of their concurrent
         changes don't overlap at all; conflicts are infrequent. And
         the amount of time it takes to resolve conflicts is far less
- than the time lost by a locking system.</para>
+ than the time lost waiting with a locking system.</para>
 
       <para>In the end, it all comes down to one critical factor: user
         communication. When users communicate poorly, both syntactic
         and semantic conflicts increase. No system can force users to
         communicate perfectly, and no system can detect semantic
- conflicts. So there's no point in being lulled into a false
- promise that a locking system will somehow prevent conflicts;
- in practice, locking seems to inhibit productivity more than
- anything else.</para>
+ conflicts. So there's no point in being lulled by the false
+ sense of security that comes from believing
+ that a locking system can somehow prevent conflicts;
+ in practice, locking only inhibits productivity.</para>
       
     </sect2>
     
@@ -259,28 +269,27 @@
 
       <para>After you've made some changes to the files in your
         working copy and verified that they work properly, Subversion
- provides you with commands to "publish" your changes to the
- other people working with you on your project (by writing to
- the repository). If other people publish their own changes,
- Subversion provides you with commands to merge those changes
- into your working directory (by reading from the
- repository).</para>
+ provides you with commands to "publish" your changes back to
the
+ repository, at which point they become available to other
people working
+ with you on your project. When other people publish their own
changes
+ to the repository, Subversion provides you with commands to
merge their changes
+ into your working copy.</para>
 
- <para>A working copy also contains some extra files, created and
- maintained by Subversion, to help it carry out these commands.
+ <para>A working copy also contains some additional files, created
and
+ maintained by Subversion to help it carry out these functions.
         In particular, each directory in your working copy contains a
         subdirectory named <filename>.svn</filename>, also known as
         the working copy <firstterm>administrative
- directory</firstterm>. The files in each administrative
- directory help Subversion recognize which files contain
+ directory</firstterm>. The contents of an administrative
+ directory help Subversion recognize which files in your working

+ copy contain
         unpublished changes, and which files are out-of-date with
- respect to others' work.</para>
+ respect to others' work in the repository.</para>
       
- <para>A typical Subversion repository often holds the files (or
+ <para>A typical Subversion repository holds the files (or
         source code) for several projects; usually, each project is a
         subdirectory in the repository's filesystem tree. In this
- arrangement, a user's working copy will usually correspond to
- a particular subtree of the repository.</para>
+ case, the directory structure of a user's working copy of a
project
+ usually mirrors the structure of the project subtree in the
+ repository.</para>
       
       <para>For example, suppose you have a repository that contains
         two software projects.</para>
@@ -294,11 +303,11 @@
         subdirectories: <filename>paint</filename> and
         <filename>calc</filename>.</para>
 
- <para>To get a working copy, you must <firstterm>check
+ <para>To get a working copy of a project, you must
+ <firstterm>check
         out</firstterm> some subtree of the repository. (The term
         "check out" may sound like it has something to do with locking
         or reserving resources, but it doesn't; it simply creates a
- private copy of the project for you.) For example, If you
+ private copy of the project for you.) For example, if you
         check out <filename>/calc</filename>, you will get a working
         copy like this: </para>
 
@@ -314,11 +323,11 @@
 </screen>
 
       <para>The list of letter A's indicates that Subversion is adding
- a number of items to your working copy. You now have a
- personal copy of the repository's <filename>/calc</filename>
+ a number of files to your working copy. You now have a
+ personal working copy of the repository's
+ <filename>/calc</filename>
         directory, with one additional
         entry&mdash;<filename>.svn</filename>&mdash;which holds the
- extra information needed by Subversion, as mentioned
+ extra housekeeping information managed by Subversion, as
+ mentioned
         earlier.</para>
 
       <sidebar>
@@ -326,8 +335,9 @@
 
         <para>Subversion repositories can be accessed through many
           different methods&mdash;on local disk, or through various
- network protocols. A repository location, however, is
- always a URL. The URL schema indicates the access
+ network protocols. However, when using the svn
+ command-line client a repository location is always
+ specified as a URL. The URL schema indicates the access
           method:</para>
 
         <table id="svn-ch-02-table-1">
@@ -432,14 +442,14 @@
         you did. When you commit your change to
         <filename>button.c</filename>, Sally's working copy is left
         unchanged; Subversion only modifies working copies at the
- user's request.</para>
+ owner's request.</para>
 
       <para>To bring her project up to date, Sally can ask
         Subversion to <firstterm>update</firstterm> her working copy,
         by using the Subversion <command>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>
+ well as any other changes that have been committed to the
repository
+ since she last updated or checked out her project.</para>
 
 <screen>
 $ pwd
@@ -454,8 +464,10 @@
 
       <para>The output from the <command>svn update</command> command
         indicates that Subversion updated the contents of
- <filename>button.c</filename>. Note that Sally didn't need to
- specify which files to update; Subversion uses the information
+ <filename>button.c</filename>. Note that Sally didn't
+ specify which files to update, which indicates that she wants
+ to update all the project files in her current directory.
+ Subversion uses the information
         in the <filename>.svn</filename> directory, and further
         information in the repository, to decide which files need to
         be brought up to date.</para>
@@ -480,11 +492,11 @@
         network problems, and other users' actions.</para>
 
       <para>Each time the repository accepts a commit, this creates a
- new state of the filesystem tree, called a
+ new state of the repository's filesystem tree, called a
         <firstterm>revision</firstterm>. Each revision is assigned a
         unique natural number, one greater than the number of the
- previous revision. The initial revision of a freshly created
- repository is numbered zero, and consists of nothing but an
+ previous revision. The initial revision number of a freshly
created
+ repository is zero, and consists of nothing but an
         empty root directory.</para>
       
       <para>A nice way to visualize the repository is as a series of @@
-492,7 +504,7 @@
         stretching from left to right. Each revision number has a
         filesystem tree hanging below it, and each tree is a
         <quote>snapshot</quote> of the way the repository looked after
- each commit. </para>
+ a commit.</para>
       
       <figure id="svn-ch2-dia7">
         <title>The Repository</title>
@@ -521,7 +533,7 @@
         </sidebar>
 
       <para>It's important to note that working copies do not always
- correspond to any single revision in the repository; they may
+ correspond to a particular revision in the repository; they may
         contain files from several different revisions. For example,
         suppose you check out a working copy from a repository whose
         most recent revision is 4:</para>
@@ -562,9 +574,10 @@
         the text of <filename>Makefile</filename> is identical in
         revisions 4, 5, and 6, but Subversion will mark your working
         copy of <filename>Makefile</filename> with revision 6 to
- indicate that it is still current. So, after you do a clean
- update at the top of your working copy, it will generally
- correspond to exactly one revision in the repository.</para>
+ indicate that it is still current. After you do a clean
+ update of your entire working copy, it will generally
+ correspond exactly to a particular revision in the repository
+ (normally the most recent <firstterm>youngest</firstterm>
+ revision).</para>
 
     </sect2>
     
@@ -580,7 +593,8 @@
       <itemizedlist>
         <listitem><para>what revision your working file is based on
             (this is called the file's <firstterm>working
- revision</firstterm>), and</para></listitem>
+ revision</firstterm> (or <firstterm>base
revision</firstterm>)),
+ and</para></listitem>
         
         <listitem><para>a timestamp recording when the local copy was
             last updated by the repository.</para></listitem> @@ -594,8
+608,8 @@
         <varlistentry>
           <term>Unchanged, and current</term>
 
- <listitem><para>The file is unchanged in the working
- directory, and no changes to that file have been committed
+ <listitem><para>The file has not been unchanged in the
working
+ directory, and no changes to the file have been committed
           to the repository since its working revision. A
           <command>svn commit</command> of the file will do nothing,
           and a <command>svn update</command> of the file will do @@
-606,11 +620,11 @@
           <term>Locally changed, and current</term>
 
           <listitem><para>The file has been changed in the working
- directory, and no changes to that file have been committed
- to the repository since its base revision. There are local
- changes that have not been committed to the repository, thus
+ directory, and no changes to the file have been committed
+ to the repository since its base revision. Since there are
local
+ changes that have not been committed to the repository,
           a <command>svn commit</command> of the file will succeed in
- publishing your changes, and a <command>svn update</command>
+ publishing your changes to the repository, and a <command>svn

+ update</command>
           of the file will do nothing.</para></listitem>
         </varlistentry>
         
@@ -619,11 +633,12 @@
 
           <listitem><para>The file has not been changed in the working
           directory, but it has been changed in the repository. The
- file should eventually be updated, to make it current with
- the public revision. A <command>svn commit</command> of the
- file will do nothing, and a <command>svn update</command> of
- the file will fold the latest changes into your working
- copy.</para></listitem>
+ file needs to be updated to make it current with
+ the public revision in the repository. A <command>svn
commit</command> of the
+ file will do nothing (there have been no local changes),
+ and a <command>svn update</command> of
+ the file will merge the latest changes from the repository
+ into your working copy.</para></listitem>
         </varlistentry>
         
         <varlistentry>
@@ -632,12 +647,12 @@
           <listitem><para>The file has been changed both in the
           working directory, and in the repository. A <command>svn
           commit</command> of the file will fail with an "out-of-date"
- error. The file should be updated first; a <command>svn
+ error. Before a file's local changes can be committed to the
+ repository, the file must be "up to date" with the
+ repository; a <command>svn
           update</command> command will attempt to merge the public
- changes with the local changes. If Subversion can't
- complete the merge in a plausible way automatically, it
- leaves it to the user to resolve the
- conflict.</para></listitem>
+ changes and the local changes. If Subversion can't
+ automatically the merge all the changes correctly,
+ the user must resolve the conflict.</para></listitem>
         </varlistentry>
       </variablelist>
       
@@ -645,7 +660,7 @@
       <para>This may sound like a lot to keep track of, but the
         <command>svn status</command> command will show you the state
         of any item in your working copy. For more information on
- that command, see <xref linkend="svn-ch-3-sect-4.3.1"
/>.</para>
+ the status command, see <xref linkend="svn-ch-3-sect-4.3.1"
+ />.</para>
      
     </sect2>
     
@@ -654,7 +669,7 @@
 
       <para>As a general principle, Subversion tries to be as flexible
         as possible. One special kind of flexibility is the ability
- to have a working copy containing mixed revision
+ to have a working copy that contains mixed revision
         numbers.</para>
 
       <para>At first, it may not be entirely clear why this sort of @@
-665,11 +680,11 @@
         bit of a mess. As demonstrated earlier, the working copy can
         always be brought to a single working revision by running
         <command>svn update</command>. Why would someone
- <emphasis>deliberately</emphasis> want a mixture of working
- revisions?</para>
+ <emphasis>want</emphasis> a mixture of working
+ revisions within a project?</para>
 
       <para>Assuming your project is sufficiently complex, you'll
- discover that it's sometimes nice to forcibly
+ discover that it's sometimes useful to forcibly
         <quote>backdate</quote> portions of your working copy to an
         earlier revision; you'll learn how to do that in Chapter 3.
         Perhaps you'd like to test an earlier version of a sub-module,
@@ -682,17 +697,19 @@
 
       <para>First, you cannot commit the deletion of a file or
         directory which isn't fully up-to-date. If a newer version of
- the item exists in the repository, your attempt to delete will
+ the item exists in the repository, your attempt to delete it
+ will
         be rejected, to prevent you from accidentally
- destroying changes you've not yet seen.</para>
+ destroying changes you've not yet seen (changes that were
+ most likely made by someone else).</para>
 
- <para>Second, you cannot commit a metadata change to a directory
+ <para>Similarly, you cannot commit a metadata change to a
+ directory
         unless it's fully up-to-date. You'll learn about attaching
         <quote>properties</quote> to items in Chapter 6. A
         directory's working revision defines a specific set of entries
- and properties, and thus committing a property change to an
- out-of-date directory may destroy properties you've not yet
- seen.</para>
+ and properties, and committing a property change on an
+ out-of-date directory could have the effect of destroying
+ properties you've not yet seen.</para>
+ <!--mblais: ### Are property values automatically merged, like
+ file contents? -->
 
     </sect2>
 
@@ -707,7 +724,7 @@
     <itemizedlist>
       <listitem>
         <para>We've introduced the notions of the central repository,
- the client working copy, and the array of repository
+ the user's working copy, and the array of repository
           revision trees.</para>
       </listitem>
 
@@ -719,14 +736,15 @@
 
       <listitem>
         <para>We've talked a bit about the way Subversion tracks and
- manages information in a working copy.</para>
+ manages information in a working copy, and synchronizes
changes
+ made to a file by several users.</para>
       </listitem>
 
     </itemizedlist>
     
     <para>At this point, you should have a good idea of how Subversion
     works in the most general sense. Armed with this knowledge, you
- should now be ready to jump into the next chapter, which is a
+ are now ready to jump into the next chapter, which is a
     detailed tour of Subversion's commands and features. </para>
       
   </sect1>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Fri Aug 15 16:52:53 2003

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.