[svnbook commit] r2580 - branches/ora-2e-reorg/src/en/book
sussman
noreply at red-bean.com
Sat Dec 23 21:26:16 CST 2006
Author: sussman
Date: Sat Dec 23 21:26:16 2006
New Revision: 2580
Modified:
branches/ora-2e-reorg/src/en/book/ch-fundamental-concepts.xml
branches/ora-2e-reorg/src/en/book/ch-preface.xml
Log:
Ben's first pass at ch01 for our Jan. 5 deadline.
* ch-preface.xml
(svn.preface.organization): add descriptions of 'new' ch03 and ch07.
* ch-fundamental-concepts.xml: lots of word cleanup, clarification, etc.
De-emphasize CVS comparisons, as per
our prime directive.
Modified: branches/ora-2e-reorg/src/en/book/ch-fundamental-concepts.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-fundamental-concepts.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-fundamental-concepts.xml Sat Dec 23 21:26:16 2006
@@ -7,19 +7,19 @@
concepts, work our way into the specific ideas behind
Subversion, and show some simple examples of Subversion in
use.</para>
-
+
<para>Even though the examples in this chapter show people sharing
collections of program source code, keep in mind that Subversion
can manage any sort of file collection—it's not limited to
helping computer programmers.</para>
-
-
+
+
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.basic.repository">
- <title>The Repository</title>
-
+ <title>The Repository</title>
+
<para>Subversion is a centralized system for sharing information.
At its core is a repository, which is a central store of data.
The repository stores information in the form of a
@@ -35,7 +35,7 @@
<title>A typical client/server system</title>
<graphic fileref="images/ch02dia1.png"/>
</figure>
-
+
<para>So why is this interesting? So far, this sounds like the
definition of a typical file server. And indeed, the repository
<emphasis>is</emphasis> a kind of file server, but it's not your
@@ -67,8 +67,14 @@
<para>The core mission of a version control system is to enable
collaborative editing and sharing of data. But different
- systems use different strategies to achieve this.</para>
-
+ systems use different strategies to achieve this. It's
+ important to understand these different strategies for a couple
+ of reasons. First, it will help you compare and contrast
+ existing version control systems, in case you encounter other
+ systems similar to Subversion. Beyond that, it will also help
+ you make more effective use of Subversion, since Subversion
+ itself supports a couple of different ways of working.</para>
+
<!-- =============================================================== -->
<sect2 id="svn.basic.vsn-models.problem-sharing">
<title>The Problem of File-Sharing</title>
@@ -161,17 +167,17 @@
<para><emphasis>Locking may create a false sense of
security.</emphasis>
- Pretend that Harry locks and edits file A, while
- Sally simultaneously locks and edits file B. But suppose
- 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 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.</para>
+ Suppose Harry locks and edits file A, while Sally
+ simultaneously locks and edits file B. But what if 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 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>
</listitem>
</itemizedlist>
@@ -181,17 +187,17 @@
<sect2 id="svn.basic.vsn-models.copy-merge">
<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
+ <para>Subversion, CVS, and a number of other version control
+ systems use a <firstterm>copy-modify-merge</firstterm> model as an
alternative to locking. In this model, each user's client
contacts the project repository and creates a personal
<firstterm>working copy</firstterm>—a local reflection
- of the repository's files and directories. Users then work in
- parallel, 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 responsible for making it happen
- correctly.</para>
+ of the repository's files and directories. Users then work
+ 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
+ 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
@@ -238,8 +244,8 @@
parallel, never waiting 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>
+ the amount of time it takes to resolve conflicts is usually
+ far less than the time lost by a locking system.</para>
<para>In the end, it all comes down to one critical factor: user
communication. When users communicate poorly, both syntactic
@@ -268,10 +274,11 @@
somebody ends up wasting time on changes that are ultimately
discarded.</para>
- <para>While CVS and Subversion are still primarily
- copy-modify-merge systems, they both recognize the need to
- lock an occasional file and provide mechanisms for this.
- See <xref linkend="svn.advanced.locking"/>.</para>
+ <para>While Subversion is still primarily a copy-modify-merge
+ system, it still recognizes the need to lock an occasional
+ file ands provide mechanisms for this. This feature is
+ discussed later in this book, in
+ <xref linkend="svn.advanced.locking"/>.</para>
</sidebar>
@@ -295,11 +302,11 @@
<sect2 id="svn.advanced.reposurls">
<title>Subversion Repository URLs</title>
- <para>As illustrated throughout this book, Subversion uses URLs to
- identify versioned resources 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>
+ <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
@@ -449,9 +456,12 @@
<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. <xref linkend="svn.basic.in-action.wc.tbl-1"/> describes how
- different URL schemas map to the available access methods.</para>
+ network protocols, depending on how your administrator has
+ set things up for you. A repository location, however, is
+ always a URL.
+ <xref linkend="svn.basic.in-action.wc.tbl-1"/> describes how
+ different URL schemas map to the available access
+ methods.</para>
<table id="svn.basic.in-action.wc.tbl-1">
<title>Repository Access URLs</title>
@@ -492,7 +502,10 @@
</table>
<para>For more information on how Subversion parses URLs, see
- <xref linkend="svn.advanced.reposurls"/>.</para>
+ <xref linkend="svn.advanced.reposurls"/>. For more
+ information on the different types of network servers
+ available for Subversion, see
+ <xref linkend="svn.serverconfig"/>.</para>
</sidebar>
@@ -506,19 +519,21 @@
in</firstterm>) changes to the repository.</para>
<para>To publish your changes to others, you can use
- Subversion's <command>commit</command> command:</para>
+ Subversion's <command>commit</command> command.</para>
<screen>
-$ svn commit button.c
+$ svn commit button.c -m "Fixed a typo in button.c."
Sending button.c
Transmitting file data .
Committed revision 57.
</screen>
<para>Now your changes to <filename>button.c</filename> have
- been committed to the repository; if another user checks out a
- working copy of <filename>/calc</filename>, they will see
- your changes in the latest version of the file.</para>
+ been committed to the repository, with a note describing your
+ change (namely, that you fixed a typo). If another user
+ checks out a working copy of <filename>/calc</filename>, they
+ will see your changes in the latest version of the
+ file.</para>
<para>Suppose you have a collaborator, Sally, who checked out a
working copy of <filename>/calc</filename> at the same time
@@ -561,18 +576,18 @@
<sect2 id="svn.basic.in-action.revs">
<title>Revisions</title>
- <para>An <command>svn commit</command> operation can publish
+ <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
- directories, and then commit the complete set of changes as a
- unit.</para>
+ directories, and then commit a complete set of changes as an
+ atomic transaction.</para>
- <para>In the repository, each commit is treated as an atomic
- transaction: either all the commit's changes take place, or
- none of them take place. Subversion tries to retain this
- atomicity in the face of program crashes, system crashes,
- network problems, and other users' actions.</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>Each time the repository accepts a commit, this creates a
new state of the filesystem tree, called a
@@ -581,14 +596,14 @@
previous revision. The initial revision of a freshly created
repository is numbered zero, 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
visualize the repository. Imagine an array of revision
numbers, starting at 0, 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 a commit.</para>
-
+
<figure id="svn.basic.in-action.revs.dia-1">
<title>The repository</title>
<graphic fileref="images/ch02dia7.png"/>
@@ -596,21 +611,23 @@
<sidebar>
<title>Global Revision Numbers</title>
-
- <para>Unlike those of many other version control systems,
- Subversion's revision numbers apply to <emphasis>entire
- trees</emphasis>, not individual files. Each revision
- number selects an entire tree, a particular state of the
- repository after some committed change. Another way to
- think about it is that revision N represents the state of
- the repository filesystem after the Nth commit. When
- Subversion users talk about <quote>revision 5 of
+
+ <para>Unlike most version control systems, Subversion's
+ revision numbers apply to <emphasis>entire trees</emphasis>,
+ not individual files. Each revision number selects an
+ entire tree, a particular state of the repository after some
+ committed change. Another way to think about it is that
+ revision N represents the state of the repository filesystem
+ after the Nth commit. When Subversion users talk
+ about <quote>revision 5 of
<filename>foo.c</filename></quote>, they really mean
<quote><filename>foo.c</filename> as it appears in revision
5.</quote> Notice that in general, revisions N and M of a
- file do <emphasis>not</emphasis> necessarily differ! Because
- CVS uses per-file revision numbers, CVS users might want to
- see <xref linkend="svn.forcvs"/> for more details.</para>
+ file do <emphasis>not</emphasis> necessarily differ! Many
+ other version control systems use per-file revision numbers,
+ so this concept may seem unusual at first. (Former CVS users
+ might want to see <xref linkend="svn.forcvs"/> for more
+ details.)</para>
</sidebar>
<para>It's important to note that working copies do not always
@@ -660,24 +677,24 @@
correspond to exactly one revision in the repository.</para>
</sect2>
-
-
+
+
<!-- =============================================================== -->
<sect2 id="svn.basic.in-action.track-repos">
<title>How Working Copies Track the Repository</title>
-
+
<para>For each file in a working directory, Subversion records
two essential pieces of information in the
<filename>.svn/</filename> administrative area:</para>
-
-
+
+
<itemizedlist>
<listitem>
<para>what revision your working file is based on (this is
called the file's <firstterm>working
revision</firstterm>), and</para>
</listitem>
-
+
<listitem>
<para>a timestamp recording when the local copy was last
updated by the repository.</para>
@@ -701,21 +718,21 @@
nothing.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<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
+ repository since you last updated. There are local
changes that have not been committed to the repository,
thus an <command>svn commit</command> of the file will
succeed in publishing your changes, and an <command>svn
update</command> of the file will do nothing.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Unchanged, and out-of-date</term>
@@ -723,13 +740,13 @@
<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. An <command>svn
+ 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>
</varlistentry>
-
+
<varlistentry>
<term>Locally changed, and out-of-date</term>
@@ -746,15 +763,16 @@
</listitem>
</varlistentry>
</variablelist>
-
-
+
+
<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.tour.cycle.examine.status" />.</para>
-
+ that command, see
+ <xref linkend="svn.tour.cycle.examine.status" />.</para>
+
</sect2>
-
+
<!-- =============================================================== -->
<sect2 id="svn.basic.in-action.mixedrevs">
<title>Mixed Revision Working Copies</title>
@@ -882,7 +900,7 @@
directory unless it's fully up-to-date. You'll learn
about attaching
<quote>properties</quote> to items in <xref
- linkend="svn.serverconfig"/>. A directory's working
+ linkend="svn.advanced"/>. 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
@@ -924,12 +942,12 @@
</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
+ should now be ready to move into the next chapter, which is a
detailed tour of Subversion's commands and features.</para>
-
+
</sect1>
</chapter>
Modified: branches/ora-2e-reorg/src/en/book/ch-preface.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-preface.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-preface.xml Sat Dec 23 21:26:16 2006
@@ -261,8 +261,17 @@
<term><xref linkend="svn.tour"/></term>
<listitem>
<para>Walks you through a day in the life of a Subversion
- user. It demonstrates how to use Subversion to obtain,
- modify, and commit data.</para>
+ user. It demonstrates how to use a Subversion client to
+ obtain, modify, and commit data.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><xref linkend="svn.advanced"/></term>
+ <listitem>
+ <para>Covers more complex features that regular users will
+ eventually come into contact with, such as versioned
+ metadata, file locking, and peg revisions.</para>
</listitem>
</varlistentry>
@@ -298,13 +307,11 @@
</varlistentry>
<varlistentry>
- <term><xref linkend="svn.advanced"/></term>
+ <term><xref linkend="svn.customization"/></term>
<listitem>
<para>Explores the Subversion client configuration files,
- file and directory properties, how to
- <literal>ignore</literal> files in your working copy,
- how to include external trees in your working copy, and
- lastly, how to handle vendor branches.</para>
+ the handling of internationalized text, and how to make
+ external tools cooperate with Subversion.</para>
</listitem>
</varlistentry>
More information about the svnbook-dev
mailing list