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—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—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—<filename>.svn</filename>—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—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