[svnbook commit] r2985 - trunk/src/en/book
sussman
noreply at red-bean.com
Sun Mar 2 21:19:52 CST 2008
Author: sussman
Date: Sun Mar 2 21:19:52 2008
New Revision: 2985
Log:
ch01-fundamental-concepts.xml: enter ORA's copyedits.
Modified:
trunk/src/en/book/ch01-fundamental-concepts.xml
Modified: trunk/src/en/book/ch01-fundamental-concepts.xml
==============================================================================
--- trunk/src/en/book/ch01-fundamental-concepts.xml (original)
+++ trunk/src/en/book/ch01-fundamental-concepts.xml Sun Mar 2 21:19:52 2008
@@ -41,7 +41,7 @@
<emphasis>is</emphasis> a kind of file server, but it's not your
usual breed. What makes the Subversion repository special is
that <emphasis>it remembers every change</emphasis> ever written
- to it: every change to every file, and even changes to the
+ to it—every change to every file, and even changes to the
directory tree itself, such as the addition, deletion, and
rearrangement of files and directories.</para>
@@ -49,12 +49,13 @@
sees only the latest version of the filesystem tree. But the
client also has the ability to view
<emphasis>previous</emphasis> states of the filesystem. For
- example, a client can ask historical questions like, <quote>What
- did this directory contain last Wednesday?</quote> or <quote>Who
- was the last person to change this file, and what changes did he
- make?</quote> These are the sorts of questions that are at the
- heart of any <firstterm>version control system</firstterm>:
- systems that are designed to track changes to data over time.
+ example, a client can ask historical questions such
+ as <quote>What did this directory contain last
+ Wednesday?</quote> or <quote>Who was the last person to change
+ this file, and what changes did he make?</quote> These are the
+ sorts of questions that are at the heart of
+ any <firstterm>version control system</firstterm>: systems that
+ are designed to track changes to data over time.
</para>
</sect1>
@@ -76,8 +77,8 @@
<!-- =============================================================== -->
<sect2 id="svn.basic.vsn-models.problem-sharing">
- <title>The Problem of File-Sharing</title>
-
+ <title>The Problem of File Sharing</title>
+
<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
@@ -87,7 +88,7 @@
<para>Consider the scenario shown in <xref
linkend="svn.basic.vsn-models.problem-sharing.dia-1"/>.
- Suppose we have two co-workers, Harry and Sally. They each
+ Suppose we have two coworkers, Harry and Sally. They each
decide to edit the same repository file at the same time. If
Harry saves his changes to the repository first, then it's
possible that (a few moments later) Sally could accidentally
@@ -107,11 +108,11 @@
</figure>
</sect2>
-
+
<!-- =============================================================== -->
<sect2 id="svn.basic.vsn-models.lock-unlock">
<title>The Lock-Modify-Unlock Solution</title>
-
+
<para>Many version control systems use a
<firstterm>lock-modify-unlock</firstterm> model to address the
problem of many authors clobbering each other's work. In this
@@ -120,20 +121,20 @@
Harry must <quote>lock</quote> a file before he can begin
making changes to it. If Harry has locked a file, then Sally
cannot also lock it, and therefore cannot make any changes to
- that file. All she can do is read the file, and wait for
+ that file. All she can do is read the file and wait for
Harry to finish his changes and release his lock. After Harry
unlocks the file, Sally can take her turn by locking and
editing the file. <xref
linkend="svn.basic.vsn-models.lock-unlock.dia-1"/>
demonstrates this simple solution.</para>
-
+
<figure id="svn.basic.vsn-models.lock-unlock.dia-1">
<title>The lock-modify-unlock solution</title>
<graphic fileref="images/ch02dia3.png"/>
</figure>
-
+
<para>The problem with the lock-modify-unlock model is that it's
- a bit restrictive, and often becomes a roadblock for
+ a bit restrictive and often becomes a roadblock for
users:</para>
<itemizedlist>
@@ -148,7 +149,7 @@
The situation ends up causing a lot of unnecessary delay
and wasted time.</para>
</listitem>
-
+
<listitem>
<para><emphasis>Locking may cause unnecessary
serialization.</emphasis>
@@ -161,7 +162,7 @@
There's no need for them to take turns in this
situation.</para>
</listitem>
-
+
<listitem>
<para><emphasis>Locking may create a false sense of
security.</emphasis>
@@ -174,9 +175,9 @@
prevent the problem—yet it somehow provided a false
sense of security. It's easy for Harry and Sally to
imagine that by locking files, each is beginning a safe,
- insulated task, and thus not bother discussing their
- incompatible changes early on. Locking often becomes a
- substitute for real communication.</para>
+ insulated task, and thus they need not bother discussing
+ their incompatible changes early on. Locking often
+ becomes a substitute for real communication.</para>
</listitem>
</itemizedlist>
@@ -185,7 +186,7 @@
<!-- =============================================================== -->
<sect2 id="svn.basic.vsn-models.copy-merge">
<title>The Copy-Modify-Merge Solution</title>
-
+
<para>Subversion, CVS, and many other version control systems
use a <firstterm>copy-modify-merge</firstterm> model as an
alternative to locking. In this model, each user's client
@@ -195,12 +196,12 @@
simultaneously and independently, modifying their private
copies. Finally, the 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
+ assists with the merging, but ultimately, a human being is
responsible for making it happen 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
+ repository. They work concurrently and make changes to the
same file A within their copies. 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
@@ -209,7 +210,7 @@
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
+ his own; once he has both sets of changes integrated, he
saves his working copy back to the repository. <xref
linkend="svn.basic.vsn-models.copy-merge.dia-1"/> and <xref
linkend="svn.basic.vsn-models.copy-merge.dia-2"/> show this
@@ -219,7 +220,7 @@
<title>The copy-modify-merge solution</title>
<graphic fileref="images/ch02dia4.png"/>
</figure>
-
+
<figure id="svn.basic.vsn-models.copy-merge.dia-2">
<title>The copy-modify-merge solution (continued)</title>
<graphic fileref="images/ch02dia5.png"/>
@@ -231,7 +232,7 @@
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
- able to see both sets of conflicting changes, and manually
+ 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
and making the necessary intelligent choices. Once Harry has
@@ -255,16 +256,16 @@
sense of security that a locking system will somehow prevent
conflicts; in practice, locking seems to inhibit productivity
more than anything else.</para>
-
+
<sidebar id="svn.basic.vsn-models.copy-merge.sb-1">
- <title>When Locking is Necessary</title>
-
+ <title>When Locking Is Necessary</title>
+
<para>While the lock-modify-unlock model is considered
generally harmful to collaboration, there are still times
when locking is appropriate.</para>
<para>The copy-modify-merge model is based on the assumption
- that files are contextually mergeable: that is, that the
+ that files are contextually mergeable—that is, that the
majority of the files in the repository are line-based text
files (such as program source code). But for files with
binary formats, such as artwork or sound, it's often
@@ -274,26 +275,26 @@
somebody ends up wasting time on changes that are ultimately
discarded.</para>
- <para>While Subversion is still primarily a copy-modify-merge
+ <para>While Subversion is primarily a copy-modify-merge
system, it still recognizes the need to lock an occasional
- file and thus provide mechanisms for this. This feature is
- discussed later in this book, in
+ file, and thus provides mechanisms for this. This feature is
+ discussed later in this book in
<xref linkend="svn.advanced.locking"/>.</para>
</sidebar>
</sect2>
-
+
</sect1>
-
+
<!-- How svn implements the philosophy -->
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.basic.in-action">
<title>Subversion in Action</title>
-
+
<para>It's time to move from the abstract to the concrete. In
this section, we'll show real examples of Subversion being
used.</para>
@@ -301,48 +302,48 @@
<!-- =============================================================== -->
<sect2 id="svn.advanced.reposurls">
<title>Subversion Repository URLs</title>
-
+
<para>Throughout this book, Subversion uses URLs to identify
versioned files and directories in Subversion repositories.
For the most part, these URLs use the standard syntax,
allowing for server names and port numbers to be specified as
part of the URL:</para>
-
+
<screen>
$ svn checkout http://svn.example.com:9834/repos
…
</screen>
-
+
<para>But there are some nuances in Subversion's handling of URLs
that are notable. For example, URLs containing the
<literal>file://</literal> access method (used for local
repositories) must, in accordance with convention, have either a
server name of <literal>localhost</literal> or no server name at
all:</para>
-
+
<screen>
$ svn checkout file:///var/svn/repos
…
$ svn checkout file://localhost/var/svn/repos
…
</screen>
-
+
<para>Also, users of the <literal>file://</literal> scheme on
Windows platforms will need to use an unofficially
<quote>standard</quote> syntax for accessing repositories
that are on the same machine, but on a different drive than
the client's current working drive. Either of the two
- following URL path syntaxes will work where
+ following URL path syntaxes will work, where
<literal>X</literal> is the drive on which the repository
resides:</para>
-
+
<screen>
C:\> svn checkout file:///X:/var/svn/repos
…
C:\> svn checkout "file:///X|/var/svn/repos"
…
</screen>
-
+
<para>In the second syntax, you need to quote the URL so that the
vertical bar character is not interpreted as a pipe. Also, note
that a URL uses forward slashes even though the native
@@ -360,37 +361,37 @@
will not understand how to interact with that
filesystem.</para>
</note>
-
+
<para>Finally, it should be noted that the Subversion client will
automatically encode URLs as necessary, just like a web browser
does. For example, if a URL contains a space or upper-ASCII
- character:</para>
-
+ character as in the following:</para>
+
<screen>
$ svn checkout "http://host/path with space/project/españa"
</screen>
-
- <para>…then Subversion will escape the unsafe characters
+
+ <para>then Subversion will escape the unsafe characters
and behave as if you had typed:</para>
-
+
<screen>
$ svn checkout http://host/path%20with%20space/project/espa%C3%B1a
</screen>
-
+
<para>If the URL contains spaces, be sure to place it within quote
marks, so that your shell treats the whole thing as a single
argument to the <command>svn</command> program.</para>
-
+
</sect2>
-
+
<!-- =============================================================== -->
<sect2 id="svn.basic.in-action.wc">
<title>Working Copies</title>
-
+
<para>You've already read about working copies; now we'll
demonstrate how the Subversion client creates and uses
them.</para>
-
+
<para>A Subversion working copy is an ordinary directory tree on
your local system, containing a collection of files. You can
edit these files however you wish, and if they're source code
@@ -414,18 +415,18 @@
maintained by Subversion, to help it carry out these commands.
In particular, each directory in your working copy contains a
subdirectory named <filename>.svn</filename>, also known as
- the working copy <firstterm>administrative
+ the working copy's <firstterm>administrative
directory</firstterm>. The files in each administrative
directory help Subversion recognize which files contain
- unpublished changes, and which files are out-of-date with
+ unpublished changes, and which files are out of date with
respect to others' work.</para>
-
+
<para>A typical Subversion repository often 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>
-
+
<para>For example, suppose you have a repository that contains
two software projects, <literal>paint</literal> and
<literal>calc</literal>. Each project lives in its own
@@ -436,10 +437,10 @@
<title>The repository's filesystem</title>
<graphic fileref="images/ch02dia6.png"/>
</figure>
-
+
<para>To get a working copy, you must <firstterm>check
out</firstterm> some subtree of the repository. (The term
- <quote>check out</quote> may sound like it has something to do
+ <emphasis>check out</emphasis> 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 check out <filename>/calc</filename>, you will get a
@@ -456,14 +457,14 @@
Makefile integer.c button.c .svn/
</screen>
- <para>The list of letter A's in the left margin indicates that
+ <para>The list of letter As in the left margin 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> directory, with one
additional entry—<filename>.svn</filename>—which
holds the extra information needed by Subversion, as mentioned
earlier.</para>
-
+
<para>Suppose you make changes to <filename>button.c</filename>.
Since the <filename>.svn</filename> directory remembers the
file's original modification date and contents, Subversion can
@@ -494,21 +495,20 @@
working copy of <filename>/calc</filename> at the same time
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
+ unchanged; Subversion modifies working copies only at the
user'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>
+ <para>To bring her project up to date, Sally can ask Subversion
+ to <firstterm>update</firstterm> her working copy, by using
+ the <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>
<screen>
$ pwd
/home/sally/calc
-$ ls -A
+$ ls -A
.svn/ Makefile integer.c button.c
$ svn update
@@ -520,7 +520,7 @@
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
- in the <filename>.svn</filename> directory, and further
+ in the <filename>.svn</filename> directory as well as further
information in the repository, to decide which files need to
be brought up to date.</para>
@@ -528,7 +528,7 @@
<title>Repository URLs</title>
<para>Subversion repositories can be accessed through many
- different methods—on local disk, or through various
+ different methods—on local disk or through various
network protocols, depending on how your administrator has
set things up for you. A repository location, however, is
always a URL.
@@ -537,37 +537,37 @@
methods.</para>
<table id="svn.basic.in-action.wc.tbl-1">
- <title>Repository Access URLs</title>
+ <title>Repository access URLs</title>
<tgroup cols="2">
<thead>
<row>
<entry>Schema</entry>
- <entry>Access Method</entry>
+ <entry>Access method</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>file:///</literal></entry>
- <entry>direct repository access (on local disk)</entry>
+ <entry>Direct repository access (on local disk)</entry>
</row>
<row>
<entry><literal>http://</literal></entry>
- <entry>access via WebDAV protocol to Subversion-aware
+ <entry>Access via WebDAV protocol to Subversion-aware
Apache server</entry>
</row>
<row>
<entry><literal>https://</literal></entry>
- <entry>same as <literal>http://</literal>, but with
+ <entry>Same as <literal>http://</literal>, but with
SSL encryption.</entry>
</row>
<row>
<entry><literal>svn://</literal></entry>
- <entry>access via custom protocol to an
+ <entry>Access via custom protocol to an
<literal>svnserve</literal> server</entry>
</row>
<row>
<entry><literal>svn+ssh://</literal></entry>
- <entry>same as <literal>svn://</literal>, but through
+ <entry>Same as <literal>svn://</literal>, but through
an SSH tunnel.</entry>
</row>
</tbody>
@@ -581,10 +581,10 @@
<xref linkend="svn.serverconfig"/>.</para>
</sidebar>
-
+
</sect2>
-
-
+
+
<!-- =============================================================== -->
<sect2 id="svn.basic.in-action.revs">
<title>Revisions</title>
@@ -592,22 +592,22 @@
<para>An <command>svn commit</command> operation publishes
changes to any number of files and directories as a single
atomic transaction. In your working copy, you can change
- files' contents; create, delete, rename and copy files and
+ files' contents; create, delete, rename, and copy files and
directories; then commit a complete set of changes as an
atomic transaction.</para>
- <para>By <quote>atomic transaction</quote>, we mean simply this:
- either all of the changes happen in the repository, or none of
- them happen. Subversion tries to retain this atomicity in the
- face of program crashes, system crashes, network problems, and
- other users' actions.</para>
+ <para>By atomic transaction, we mean simply this: either all of
+ the changes happen in the repository, or none of them happen.
+ Subversion tries to retain this atomicity in the face of
+ program crashes, system crashes, 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
<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
+ repository is numbered 0 and consists of nothing but an
empty root directory.</para>
<para><xref linkend="svn.basic.in-action.revs.dia-1"/> illustrates a nice way to
@@ -703,14 +703,14 @@
<itemizedlist>
<listitem>
- <para>what revision your working file is based on (this is
+ <para>What revision your working file is based on (this is
called the file's <firstterm>working
- revision</firstterm>), and</para>
+ revision</firstterm>) and</para>
</listitem>
<listitem>
- <para>a timestamp recording when the local copy was last
- updated by the repository.</para>
+ <para>A timestamp recording of when the local copy was last
+ updated by the repository</para>
</listitem>
</itemizedlist>
@@ -720,7 +720,7 @@
<variablelist>
<varlistentry>
- <term>Unchanged, and current</term>
+ <term>Unchanged, and current</term>
<listitem>
<para>The file is unchanged in the working directory, and
@@ -747,14 +747,15 @@
</varlistentry>
<varlistentry>
- <term>Unchanged, and out-of-date</term>
+ <term>Unchanged, and out-of-date</term>
<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 latest public revision. An <command>svn
- commit</command> of the file will do nothing, and an
+ The file should eventually be updated in order to make
+ it current with the latest public revision.
+ An <command>svn commit</command> of the file will do
+ nothing, and an
<command>svn update</command> of the file will fold the
latest changes into your working copy.</para>
</listitem>
@@ -765,7 +766,7 @@
<listitem>
<para>The file has been changed both in the working
- directory, and in the repository. An <command>svn
+ directory and in the repository. An <command>svn
commit</command> of the file will fail with an
<quote>out-of-date</quote> error. The file should be
updated first; an <command>svn update</command> command
@@ -801,11 +802,11 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.basic.in-action.mixedrevs.update-commit">
- <title>Updates and Commits are Separate</title>
+ <title>Updates and commits are separate</title>
<para>One of the fundamental rules of Subversion is that
a <quote>push</quote> action does not cause
- a <quote>pull</quote>, nor the other way around. Just
+ a <quote>pull,</quote> nor the other way around. Just
because you're ready to submit new changes to the repository
doesn't mean you're ready to receive changes from other
people. And if you have new changes still in progress,
@@ -813,11 +814,11 @@
repository changes into your own, rather than forcing you to
publish them.</para>
- <para>The main side-effect of this rule is that it means a
+ <para>The main side effect of this rule is that it means a
working copy has to do extra bookkeeping to track mixed
- revisions, and be tolerant of the mixture as well. It's
- made more complicated by the fact that directories
- themselves are versioned.</para>
+ revisions as well as be tolerant of the mixture. It's made
+ more complicated by the fact that directories themselves are
+ versioned.</para>
<para>For example, suppose you have a working copy entirely at
revision 10. You edit the
@@ -831,17 +832,17 @@
repository, since you haven't yet run <command>svn
update</command>, and <command>svn commit</command> doesn't
pull down new changes. If, on the other hand,
- <command>svn commit</command> <emphasis>were</emphasis> to
- automatically download the newest changes, then it would be
- possible to set the entire working copy to revision
- 15—but then we'd be breaking the fundamental rule
- of <quote>push</quote> and <quote>pull</quote> remaining
- separate actions. Therefore the only safe thing the
- Subversion client can do is mark the one
+ <command>svn commit</command> were to automatically download
+ the newest changes, then it would be possible to set the
+ entire working copy to revision 15—but then we'd be
+ breaking the fundamental rule of <quote>push</quote>
+ and <quote>pull</quote> remaining separate actions.
+ Therefore, the only safe thing the Subversion client can do
+ is mark the one
file—<filename>foo.html</filename>—as being at
revision 15. The rest of the working copy remains at
revision 10. Only by running <command>svn update</command>
- can the latest changes be downloaded, and the whole working
+ can the latest changes be downloaded and the whole working
copy be marked as revision 15.</para>
</sect3>
@@ -849,13 +850,13 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.basic.in-action.mixedrevs.normal">
<title>Mixed revisions are normal</title>
-
+
<para>The fact is, <emphasis>every time</emphasis> you run
<command>svn commit</command>, your working copy ends up
with some mixture of revisions. The things you just
committed are marked as having larger working revisions than
everything else. After several commits (with no updates
- in-between) your working copy will contain a whole mixture
+ in between), your working copy will contain a whole mixture
of revisions. Even if you're the only person using the
repository, you will still see this phenomenon. To examine
your mixture of working revisions, use the <command>svn
@@ -884,16 +885,17 @@
<title>Mixed revisions are useful</title>
<para>If your project is sufficiently complex, you'll discover
- that it's sometimes nice to forcibly <firstterm>backdate</firstterm>
- (or, update to a revision older than the one you already
- have) portions of your working copy to an earlier revision; you'll
- learn how to do that in <xref linkend="svn.tour"/>. Perhaps
- you'd like to test an earlier version of a sub-module
- contained in a subdirectory, or perhaps you'd like to figure
- out when a bug first came into existence in a specific file.
- This is the <quote>time machine</quote> aspect of a version
- control system—the feature which allows you to move
- any portion of your working copy forward and backward in
+ that it's sometimes nice to
+ forcibly <firstterm>backdate</firstterm> (or, update to a
+ revision older than the one you already have) portions of
+ your working copy to an earlier revision; you'll learn how
+ to do that in <xref linkend="svn.tour"/>. Perhaps you'd
+ like to test an earlier version of a submodule contained in
+ a subdirectory, or perhaps you'd like to figure out when a
+ bug first came into existence in a specific file. This is
+ the <quote>time machine</quote> aspect of a version control
+ system—the feature that allows you to move any
+ portion of your working copy forward and backward in
history.</para>
</sect3>
@@ -904,15 +906,15 @@
<para>However you make use of mixed revisions in your working
copy, there are limitations to this flexibility.</para>
-
+
<para>First, you cannot commit the deletion of a file or
- directory which isn't fully up-to-date. If a newer version
+ directory that isn't fully up to date. If a newer version
of the item exists in the repository, your attempt to delete
- will be rejected, to prevent you from accidentally
+ will be rejected in order to prevent you from accidentally
destroying changes you've not yet seen.</para>
<para>Second, you cannot commit a metadata change to a
- directory unless it's fully up-to-date. You'll learn about
+ directory unless it's fully up to date. You'll learn about
attaching <quote>properties</quote> to items in <xref
linkend="svn.advanced"/>. A directory's working revision
defines a specific set of entries and properties, and thus
More information about the svnbook-dev
mailing list