[svnbook] r3798 committed - * src/en/book/ch00-preface.xml,...
svnbook at googlecode.com
svnbook at googlecode.com
Thu Oct 14 16:58:37 CDT 2010
Revision: 3798
Author: cmpilato at gmail.com
Date: Thu Oct 14 14:58:06 2010
Log: * src/en/book/ch00-preface.xml,
* src/en/book/ch01-fundamental-concepts.xml,
* src/en/book/ch02-basic-usage.xml,
* src/en/book/ch03-advanced-topics.xml
Major reworking, mostly of chapter 1, but elsewhere, too. This is
my first pass at implementing fixes for a slew of organizational
grievances I've long held about this text.
http://code.google.com/p/svnbook/source/detail?r=3798
Modified:
/trunk/src/en/book/ch00-preface.xml
/trunk/src/en/book/ch01-fundamental-concepts.xml
/trunk/src/en/book/ch02-basic-usage.xml
/trunk/src/en/book/ch03-advanced-topics.xml
=======================================
--- /trunk/src/en/book/ch00-preface.xml Fri Oct 8 13:04:41 2010
+++ /trunk/src/en/book/ch00-preface.xml Thu Oct 14 14:58:06 2010
@@ -10,12 +10,15 @@
own shadow during design.</quote></para>
</blockquote>
- <para>
- <indexterm>
- <primary>Concurrent Versions System (CVS)</primary>
- </indexterm>
-
- In the world of open source software, the Concurrent Versions
+ <indexterm>
+ <primary>Concurrent Versions System</primary>
+ </indexterm>
+ <indexterm>
+ <primary>CVS</primary>
+ <see>Concurrent Versions System</see>
+ </indexterm>
+
+ <para>In the world of open source software, the Concurrent Versions
System (CVS) was the tool of choice for version control for many
years. And rightly so. CVS was open source software itself, and
its nonrestrictive modus operandi and support for networked
@@ -57,19 +60,26 @@
<sect1 id="svn.intro.whatis">
<title>What Is Subversion?</title>
-
- <para>
- <indexterm>
- <primary>Subversion</primary>
- <secondary>defined</secondary>
- </indexterm>
-
- Subversion is a free/open source version control system.
- That is, Subversion manages files and directories, and the
- changes made to them, over time. This allows you to recover
- older versions of your data or examine the history of how your
- data changed. In this regard, many people think of a version
- control system as a sort of <quote>time machine.</quote></para>
+
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>version control systems</primary>
+ </indexterm>
+ <indexterm>
+ <primary>VCS</primary>
+ <see>version control systems</see>
+ </indexterm>
+
+ <para>Subversion is a free/open source <firstterm>version control
+ system</firstterm> (VCS). That is, Subversion manages files and
+ directories, and the changes made to them, over time. This
+ allows you to recover older versions of your data or examine the
+ history of how your data changed. In this regard, many people
+ think of a version control system as a sort of <quote>time
+ machine.</quote></para>
<para>Subversion can operate across networks, which allows it to
be used by people on different computers. At some level, the
@@ -81,13 +91,22 @@
losing that conduit—if some incorrect change is made to
the data, just undo that change.</para>
- <para>Some version control systems are also software configuration
- management (SCM) systems. These systems are specifically
- tailored to manage trees of source code and have many features
- that are specific to software development—such as natively
- understanding programming languages, or supplying tools for
- building software. Subversion, however, is not one of these
- systems. It is a general system that can be used to manage
+ <indexterm>
+ <primary>software configuration management</primary>
+ </indexterm>
+ <indexterm>
+ <primary>SCM</primary>
+ <see>software configuration management</see>
+ </indexterm>
+
+ <para>Some version control systems are also <firstterm>software
+ configuration management</firstterm> (SCM) systems. These
+ systems are specifically tailored to manage trees of source code
+ and have many features that are specific to software
+ development—such as natively understanding programming
+ languages, or supplying tools for building software.
+ Subversion, however, is not one of these systems. It is a
+ general system that can be used to manage
<emphasis>any</emphasis> collection of files. For you, those
files might be source code—for others, anything from
grocery shopping lists to digital video mixdowns and
@@ -112,14 +131,14 @@
documents (usually over a network) and keep track of who made
which changes, then Subversion is also appropriate. This is
why Subversion is so often used in software development
- environments—working on a development team is an inherently
social
- activity, and Subversion makes it easy to collaborate with
- other programmers. Of course, there's a cost to using
- Subversion as well: administrative overhead. You'll need to
- manage a data repository to store the information and all its
- history, and be diligent about backing it up. When working
- with the data on a daily basis, you won't be able to copy,
- move, rename, or delete files the way you usually do.
+ environments—working on a development team is an
+ inherently social activity, and Subversion makes it easy to
+ collaborate with other programmers. Of course, there's a cost
+ to using Subversion as well: administrative overhead. You'll
+ need to manage a data repository to store the information and
+ all its history, and be diligent about backing it up. When
+ working with the data on a daily basis, you won't be able to
+ copy, move, rename, or delete files the way you usually do.
Instead, you'll have to do all of those things through
Subversion.</para>
@@ -144,6 +163,8 @@
overhead of tracking changes, such as <command>rsync</command>
or <command>unison</command>.</para>
+ <!-- TODO: Fill in the landscape with respect to DVCS -->
+
</sect2>
<!-- ===============================================================
-->
@@ -151,16 +172,15 @@
<title>Subversion's History</title>
- <para>
- <indexterm>
- <primary>Subversion</primary>
- <secondary>history of</secondary>
- </indexterm>
- <indexterm>
- <primary>CollabNet</primary>
- </indexterm>
-
- In early 2000, CollabNet, Inc. (<ulink
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>history of</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>CollabNet</primary>
+ </indexterm>
+
+ <para>In early 2000, CollabNet, Inc. (<ulink
url="http://www.collab.net"/>) began seeking developers to
write a replacement for CVS. CollabNet offers a collaboration
software suite called CollabNet Enterprise Edition (CEE), of
@@ -182,24 +202,23 @@
discussing a design for a new version control system with his
friend Jim Blandy. In 1995, the two had started Cyclic
Software, a company providing CVS support contracts, and
- although they later sold the business, they still used CVS every
- day at their jobs. Their frustration with CVS had led Jim to
- think carefully about better ways to manage versioned data, and
- he'd already come up with not only the name
- <quote>Subversion,</quote> but also the basic design of
- the Subversion data store. When CollabNet called, Karl
- immediately agreed to work on the project, and Jim got his
- employer, Red Hat Software, to essentially donate him to the
- project for an indefinite period of time. CollabNet hired
- Karl and Ben Collins-Sussman, and detailed design work began
- in May 2000. With the help of some well-placed prods from
- Brian Behlendorf and Jason Robbins of CollabNet, and from Greg
- Stein (at the time an independent developer active in the
- WebDAV/DeltaV specification process), Subversion quickly
- attracted a community of active developers. It turned out
- that many people had encountered the same frustrating
- experiences with CVS and welcomed the chance to finally do
- something about it.</para>
+ although they later sold the business, they still used CVS
+ every day at their jobs. Their frustration with CVS had led
+ Jim to think carefully about better ways to manage versioned
+ data, and he'd already come up with not only the Subversion
+ name, but also the basic design of the Subversion data store.
+ When CollabNet called, Karl immediately agreed to work on the
+ project, and Jim got his employer, Red Hat Software, to
+ essentially donate him to the project for an indefinite period
+ of time. CollabNet hired Karl and Ben Collins-Sussman, and
+ detailed design work began in May 2000. With the help of some
+ well-placed prods from Brian Behlendorf and Jason Robbins of
+ CollabNet, and from Greg Stein (at the time an independent
+ developer active in the WebDAV/DeltaV specification process),
+ Subversion quickly attracted a community of active developers.
+ It turned out that many people had encountered the same
+ frustrating experiences with CVS and welcomed the chance to
+ finally do something about it.</para>
<para>The original design team settled on some simple goals. They
didn't want to break new ground in version control methodology,
@@ -239,13 +258,12 @@
<title>Subversion's Architecture</title>
- <para>
- <indexterm>
- <primary>Subversion</primary>
- <secondary>architecture</secondary>
- </indexterm>
-
- <xref linkend="svn.intro.architecture.dia-1"/> illustrates
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>architecture</secondary>
+ </indexterm>
+
+ <para><xref linkend="svn.intro.architecture.dia-1"/> illustrates
a <quote>mile-high</quote> view of Subversion's
design.</para>
@@ -254,15 +272,14 @@
<graphic fileref="images/ch01dia1.png"/>
</figure>
- <para>On one end is a Subversion repository that holds all of your
- versioned data. On the other end is your Subversion client
- program, which manages local reflections of portions of that
- versioned data (called <quote>working copies</quote>). Between
- these extremes are multiple routes through various Repository
- Access (RA) layers. Some of these routes go across computer
- networks and through network servers which then access the
- repository. Others bypass the network altogether and access the
- repository directly.</para>
+ <para>On one end is a Subversion repository that holds all of
+ your versioned data. On the other end is your Subversion
+ client program, which manages local reflections of portions of
+ that versioned data. Between these extremes are multiple
+ routes through a Repository Access (RA) layer, some of which
+ go across computer networks and through network servers which
+ then access the repository, others of which bypass the network
+ altogether and access the repository directly.</para>
</sect2>
@@ -271,19 +288,45 @@
<title>Subversion's Components</title>
- <para>
- <indexterm>
- <primary>Subversion</primary>
- <secondary>components</secondary>
- </indexterm>
-
- Subversion, once installed, has a number of different
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>components</secondary>
+ </indexterm>
+
+ <para>Subversion, once installed, has a number of different
pieces. The following is a quick overview of what you get.
- Don't be alarmed if the brief descriptions leave you scratching
- your head—<emphasis>plenty</emphasis> more pages
- in this book are devoted to alleviating that confusion.</para>
+ Don't be alarmed if the brief descriptions leave you
+ scratching your head—<emphasis>plenty</emphasis> more
+ pages in this book are devoted to alleviating that
+ confusion.</para>
<variablelist>
+
+ <indexterm>
+ <primary>svn</primary>
+ </indexterm>
+ <indexterm>
+ <primary>svnversion</primary>
+ </indexterm>
+ <indexterm>
+ <primary>svnlook</primary>
+ </indexterm>
+ <indexterm>
+ <primary>svnadmin</primary>
+ </indexterm>
+ <indexterm>
+ <primary>mod_dav_svn</primary>
+ </indexterm>
+ <indexterm>
+ <primary>svnserve</primary>
+ </indexterm>
+ <indexterm>
+ <primary>svndumpfilter</primary>
+ </indexterm>
+ <indexterm>
+ <primary>svnsync</primary>
+ </indexterm>
+
<varlistentry>
<term>svn</term>
<listitem>
@@ -298,14 +341,14 @@
revisions of the items present) of a working copy</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>svnlook</term>
<listitem>
<para>A tool for directly inspecting a Subversion
repository</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>svnadmin</term>
<listitem>
@@ -313,7 +356,7 @@
repository</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>mod_dav_svn</term>
<listitem>
@@ -352,27 +395,26 @@
</sect2>
- <!-- =============================================================== -->
+ <!-- ===============================================================
-->
<sect2 id="svn.intro.whatsnew">
<title>What's New in Subversion</title>
- <para>
- <indexterm>
- <primary>Subversion</primary>
- <secondary>history of</secondary>
- </indexterm>
-
- The first edition of this book was released in 2004, shortly
- after Subversion had reached 1.0. Over the following four
- years Subversion released five major new versions, fixing bugs
- and adding major new features. While we've managed to keep
- the online version of this book up to date, we're thrilled
- that the second edition from O'Reilly now covers Subversion up
- through release 1.5, a major milestone for the project.
- Here's a quick summary of major new changes since Subversion
- 1.0. Note that this is not a complete list; for full details,
- please visit Subversion's web site at
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>history of</secondary>
+ </indexterm>
+
+ <para>The first edition of this book was released in 2004,
+ shortly after Subversion had reached 1.0. Over the following
+ four years Subversion released five major new versions, fixing
+ bugs and adding major new features. While we've managed to
+ keep the online version of this book up to date, we're
+ thrilled that the second edition from O'Reilly now covers
+ Subversion up through release 1.5, a major milestone for the
+ project. Here's a quick summary of major new changes since
+ Subversion 1.0. Note that this is not a complete list; for
+ full details, please visit Subversion's web site at
<ulink url="http://subversion.apache.org"/>.</para>
<variablelist>
@@ -695,135 +737,135 @@
<para>The chapters that follow and their contents are listed
here:</para>
- <variablelist>
-
- <varlistentry>
- <term><xref linkend="svn.basic"/></term>
- <listitem>
- <para>Explains the basics of version control and different
- versioning models, along with Subversion's repository,
- working copies, and revisions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <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 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>
-
- <varlistentry>
- <term><xref linkend="svn.branchmerge"/></term>
- <listitem>
- <para>Discusses branches, merges, and tagging, including
- best practices for branching and merging, common
- use cases, how to undo changes, and how to easily swing
- from one branch to the next.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><xref linkend="svn.reposadmin"/></term>
- <listitem>
- <para>Describes the basics of the Subversion repository,
- how to create, configure, and maintain a repository, and
- the tools you can use to do all of this.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><xref linkend="svn.serverconfig"/></term>
- <listitem>
- <para>Explains how to configure your Subversion server and
- offers different ways to access your repository:
- <literal>HTTP</literal>, the <literal>svn</literal>
- protocol, and local disk access. It also covers the details
- of authentication, authorization and anonymous
- access.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><xref linkend="svn.customization"/></term>
- <listitem>
- <para>Explores the Subversion client configuration files,
- the handling of internationalized text, and how to make
- external tools cooperate with Subversion.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><xref linkend="svn.developer"/></term>
- <listitem>
- <para>Describes the internals of Subversion, the
- Subversion filesystem, and the working copy
- administrative areas from a programmer's point of view.
- It also demonstrates how to use the public APIs to write a
- program that uses Subversion.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><xref linkend="svn.ref"/></term>
- <listitem>
- <para>Explains in great detail every subcommand of
- <command>svn</command>, <command>svnadmin</command>, and
- <command>svnlook</command> with plenty of examples for
- the whole family!</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><xref linkend="svn.intro"/></term>
- <listitem>
- <para>For the impatient, a whirlwind explanation of how to
- install Subversion and start using it immediately. You
- have been warned.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><xref linkend="svn.forcvs"/></term>
- <listitem>
- <para>Covers the similarities and differences between
- Subversion and CVS, with numerous suggestions on how to
- break all the bad habits you picked up from years of
- using CVS. Included are descriptions of Subversion
- revision numbers, versioned directories, offline
- operations, <command>update</command>
- versus <command>status</command>, branches, tags, metadata,
- conflict resolution, and authentication.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><xref linkend="svn.webdav"/></term>
- <listitem>
- <para>Describes the details of WebDAV and DeltaV and how
- you can configure your Subversion repository to be
- mounted read/write as a DAV share.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><xref linkend="svn.copyright"/></term>
- <listitem>
- <para>A copy of the Creative Commons Attribution License,
- under which this book is licensed.</para>
- </listitem>
- </varlistentry>
+ <variablelist>
+
+ <varlistentry>
+ <term><xref linkend="svn.basic"/></term>
+ <listitem>
+ <para>Explains the basics of version control and different
+ versioning models, along with Subversion's repository,
+ working copies, and revisions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <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 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>
+
+ <varlistentry>
+ <term><xref linkend="svn.branchmerge"/></term>
+ <listitem>
+ <para>Discusses branches, merges, and tagging, including
+ best practices for branching and merging, common
+ use cases, how to undo changes, and how to easily swing
+ from one branch to the next.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><xref linkend="svn.reposadmin"/></term>
+ <listitem>
+ <para>Describes the basics of the Subversion repository,
+ how to create, configure, and maintain a repository, and
+ the tools you can use to do all of this.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><xref linkend="svn.serverconfig"/></term>
+ <listitem>
+ <para>Explains how to configure your Subversion server and
+ offers different ways to access your repository:
+ <literal>HTTP</literal>, the <literal>svn</literal>
+ protocol, and local disk access. It also covers the details
+ of authentication, authorization and anonymous
+ access.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><xref linkend="svn.customization"/></term>
+ <listitem>
+ <para>Explores the Subversion client configuration files,
+ the handling of internationalized text, and how to make
+ external tools cooperate with Subversion.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><xref linkend="svn.developer"/></term>
+ <listitem>
+ <para>Describes the internals of Subversion, the
+ Subversion filesystem, and the working copy
+ administrative areas from a programmer's point of view.
+ It also demonstrates how to use the public APIs to write a
+ program that uses Subversion.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><xref linkend="svn.ref"/></term>
+ <listitem>
+ <para>Explains in great detail every subcommand of
+ <command>svn</command>, <command>svnadmin</command>, and
+ <command>svnlook</command> with plenty of examples for
+ the whole family!</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><xref linkend="svn.intro"/></term>
+ <listitem>
+ <para>For the impatient, a whirlwind explanation of how to
+ install Subversion and start using it immediately. You
+ have been warned.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><xref linkend="svn.forcvs"/></term>
+ <listitem>
+ <para>Covers the similarities and differences between
+ Subversion and CVS, with numerous suggestions on how to
+ break all the bad habits you picked up from years of
+ using CVS. Included are descriptions of Subversion
+ revision numbers, versioned directories, offline
+ operations, <command>update</command>
+ versus <command>status</command>, branches, tags, metadata,
+ conflict resolution, and authentication.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><xref linkend="svn.webdav"/></term>
+ <listitem>
+ <para>Describes the details of WebDAV and DeltaV and how
+ you can configure your Subversion repository to be
+ mounted read/write as a DAV share.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><xref linkend="svn.copyright"/></term>
+ <listitem>
+ <para>A copy of the Creative Commons Attribution License,
+ under which this book is licensed.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
@@ -893,9 +935,9 @@
</footnote>
</para>
- <para>Thanks to O'Reilly and our various editors: Chuck Toporek, Linda
- Mui, Tatiana Apandi, Mary Brady, and Mary Treseler. Their patience
and support
- has been tremendous.</para>
+ <para>Thanks to O'Reilly and our various editors: Chuck Toporek,
+ Linda Mui, Tatiana Apandi, Mary Brady, and Mary Treseler. Their
+ patience and support has been tremendous.</para>
<para>Finally, we thank the countless people who contributed to
this book with informal reviews, suggestions, and patches.
=======================================
--- /trunk/src/en/book/ch01-fundamental-concepts.xml Fri Oct 8 13:07:17
2010
+++ /trunk/src/en/book/ch01-fundamental-concepts.xml Thu Oct 14 14:58:06
2010
@@ -17,345 +17,543 @@
<!-- =================================================================
-->
<!-- =================================================================
-->
<!-- =================================================================
-->
- <sect1 id="svn.basic.repository">
- <title>The Repository</title>
-
- <para>
+ <sect1 id="svn.basic.version-control-basics">
+ <title>Version Control Basics</title>
+
+ <indexterm>
+ <primary>version control systems</primary>
+ </indexterm>
+
+ <para>A version control system (or revision control system) is a
+ system that tracks incremental versions (or revisions) of files
+ and, in some cases, directories over time. Of course, merely
+ tracking the various versions of a user's (or group of users')
+ files and directories isn't very interesting in itself. What
+ makes a version control system useful is the fact that it allows
+ you to explore the changes which resulted in each of those
+ versions and facilitates the arbitrary recall of the
+ same.</para>
+
+ <para>In this section, we'll introduce some fairly high-level
+ version control system components and concepts. We'll limit our
+ discussion to modern version control systems—in today's
+ interconnected world, there is very little point in
+ acknowledging version control systems which cannot
+ operate across wide-area networks.</para>
+
+ <!-- ===============================================================
-->
+ <sect2 id="svn.basic.repository">
+ <title>The Repository</title>
+
<indexterm>
<primary>repository</primary>
<secondary>defined</secondary>
</indexterm>
- 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
- <firstterm>filesystem tree</firstterm>—a typical hierarchy
- of files and directories. Any number of
- <firstterm>clients</firstterm> connect to the repository, and
- then read or write to these files. By writing data, a client
- makes the information available to others; by reading data, the
- client receives information from others. <xref
- linkend="svn.basic.repository.dia-1"/> illustrates this.</para>
-
- <figure id="svn.basic.repository.dia-1">
- <title>A typical client/server system</title>
- <graphic fileref="images/ch02dia1.png"/>
- </figure>
-
- <para>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
- 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
- directory tree itself, such as the addition, deletion, and
- rearrangement of files and directories.</para>
-
- <para>When a client reads data from the repository, it normally
- 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 such
- as <quote>What did this directory contain last
- Wednesday?</quote> and <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>
-
- <!-- =================================================================
-->
- <!-- =================================================================
-->
- <!-- =================================================================
-->
- <sect1 id="svn.basic.vsn-models">
- <title>Versioning Models</title>
-
- <para>
+ <para>At the core of the version control system is a repository,
+ which is the central store of that system's data. The
+ repository usually stores information in the form of a
+ <firstterm>filesystem tree</firstterm>—a hierarchy of
+ files and directories. Any number of
+ <firstterm>clients</firstterm> connect to the repository, and
+ then read or write to these files. By writing data, a client
+ makes the information available to others; by reading data,
+ the client receives information from others.
+ <xref linkend="svn.basic.repository.dia-1"/> illustrates
+ this.</para>
+
+ <figure id="svn.basic.repository.dia-1">
+ <title>A typical client/server system</title>
+ <graphic fileref="images/ch02dia1.png"/>
+ </figure>
+
+ <para>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 usual breed. What makes the repository special
+ is that these as the files in the repository are changed, the
+ repository remembers each version of those files.</para>
+
+ <para>When a client reads data from the repository, it normally
+ sees only the latest version of the filesystem tree. But what
+ makes a version control client interesting is that it also has
+ the ability to request previous states of the filesystem from
+ the repository. A version control client can ask historical
+ questions such as <quote>What did this directory contain last
+ Wednesday?</quote> and <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
+ version control system.</para>
+
+ </sect2>
+
+ <!-- ===============================================================
-->
+ <sect2 id="svn.basic.working-copy">
+ <title>The Working Copy</title>
+
<indexterm>
- <primary>version control</primary>
+ <primary>working copy</primary>
<secondary>defined</secondary>
</indexterm>
- If the primary mission of a version control system is to track
- the various versions of digital information over time, a very
- close secondary mission in any modern version control system is
- to enable collaborative editing and sharing of that data. But
- different 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>
+ <para>A version control system's value comes in the fact that it
+ tracks versions of files and directories, but the rest of the
+ software universe doesn't operate on <quote>versions of files
+ and directories</quote>. Most software programs understand
+ how to operate only on a <emphasis>single</emphasis> version
+ of a specific type of file. So how does a version control
+ user interact with an abstract—and, often,
+ remote—repository full of multiple versions of various
+ files in a concrete fashion? How does his or her word
+ processing software, presentation software, source code
+ editor, web design software, or some other program—all
+ of which trade in the currency of simple data files—get
+ access to such files? The answer is found in the version
+ control construct known as a <firstterm>working
+ copy</firstterm>.</para>
+
+ <para>A working copy is, quite literally, a local copy of a
+ particular version of a user's VCS-managed data upon which
+ that user is free to work. Working copies
+ <footnote>
+ <para>The term <quote>working copy</quote> can be generally
+ applied to any one file version's local instance. When
+ most folks use the term, though, they are referring to a
+ whole directory tree containing files and subdirectories
+ managed by the version control system.</para>
+ </footnote>
+ appear to other software just as any other local directory
+ full of files, so those programs don't have to
+ be <quote>version-control-aware</quote> in order to read from
+ and write to that data. The task of managing the working copy
+ and communicating changes made to its contents to and from the
+ repository falls squarely to the version control system's
+ client software.</para>
+
+ </sect2>
<!-- ===============================================================
-->
- <sect2 id="svn.basic.vsn-models.problem-sharing">
- <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
- each other's feet? It's all too easy for users to
- accidentally overwrite each other's changes in the
- repository.</para>
-
- <para>Consider the scenario shown in <xref
- linkend="svn.basic.vsn-models.problem-sharing.dia-1"/>.
- 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, it's
- possible that (a few moments later) Sally could accidentally
- overwrite them with her own new version of the file. While
- Harry's version of the file won't be lost forever (because the
- system remembers every change), any changes Harry made
- <emphasis>won't</emphasis> be present in Sally's newer version
- of the file, because she never saw Harry's changes to begin
- with. Harry's work is still effectively lost—or at
- least missing from the latest version of the file—and
- probably by accident. This is definitely a situation we want
- to avoid!</para>
-
- <figure id="svn.basic.vsn-models.problem-sharing.dia-1">
- <title>The problem to avoid</title>
- <graphic fileref="images/ch02dia2.png"/>
- </figure>
-
- </sect2>
-
- <!-- ===============================================================
-->
- <sect2 id="svn.basic.vsn-models.lock-unlock">
- <title>The Lock-Modify-Unlock Solution</title>
-
- <para>
+ <sect2 id="svn.basic.vsn-models">
+ <title>Versioning Models</title>
+
+ <para>If the primary mission of a version control system is to
+ track the various versions of digital information over time, a
+ very close secondary mission in any modern version control
+ system is to enable collaborative editing and sharing of that
+ data. But different 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>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.basic.vsn-models.problem-sharing">
+ <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 each other's feet? It's all too easy for users
+ to accidentally overwrite each other's changes in the
+ repository.</para>
+
+ <para>Consider the scenario shown in
+ <xref linkend="svn.basic.vsn-models.problem-sharing.dia-1"/>.
+ 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, it's
+ possible that (a few moments later) Sally could accidentally
+ overwrite them with her own new version of the file. While
+ Harry's version of the file won't be lost forever (because
+ the system remembers every change), any changes Harry made
+ <emphasis>won't</emphasis> be present in Sally's newer version
+ of the file, because she never saw Harry's changes to begin
+ with. Harry's work is still effectively lost—or at
+ least missing from the latest version of the file—and
+ probably by accident. This is definitely a situation we want
+ to avoid!</para>
+
+ <figure id="svn.basic.vsn-models.problem-sharing.dia-1">
+ <title>The problem to avoid</title>
+ <graphic fileref="images/ch02dia2.png"/>
+ </figure>
+
+ </sect3>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.basic.vsn-models.lock-unlock">
+ <title>The Lock-Modify-Unlock Solution</title>
+
<indexterm>
<primary>version control</primary>
<secondary>models</secondary>
<tertiary>lock-modify-unlock</tertiary>
</indexterm>
- 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
- model, the repository allows only one person to change a file
- at a time. This exclusivity policy is managed using locks.
- Harry must <quote>lock</quote> a file before he can begin
- making changes to it. If Harry has locked a file, 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
- 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
- users:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>Locking may cause administrative
- problems.</emphasis>
-
- Sometimes Harry will lock a file and then forget about it.
- Meanwhile, because Sally is still waiting to edit the file,
- her hands are tied. And then Harry goes on vacation. Now
- Sally has to get an administrator to release Harry's lock.
- The situation ends up causing a lot of unnecessary delay
- and wasted time.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Locking may cause unnecessary
- serialization.</emphasis>
-
- What if Harry is editing the beginning of a text file,
- and Sally simply wants to edit the end of the same file?
- 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
- situation.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Locking may create a false sense of
- security.</emphasis>
-
- 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 they need not bother discussing
- their incompatible changes early on. Locking often
- becomes a substitute for real communication.</para>
- </listitem>
- </itemizedlist>
-
- </sect2>
-
- <!-- ===============================================================
-->
- <sect2 id="svn.basic.vsn-models.copy-merge">
- <title>The Copy-Modify-Merge Solution</title>
-
- <para>
+ <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 model, the repository allows only one person to
+ change a file at a time. This exclusivity policy is managed
+ using locks. Harry must <quote>lock</quote> a file before
+ he can begin making changes to it. If Harry has locked a
+ file, 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 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
+ users:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Locking may cause administrative
+ problems.</emphasis>
+
+ Sometimes Harry will lock a file and then forget about it.
+ Meanwhile, because Sally is still waiting to edit the file,
+ her hands are tied. And then Harry goes on vacation. Now
+ Sally has to get an administrator to release Harry's lock.
+ The situation ends up causing a lot of unnecessary delay
+ and wasted time.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Locking may cause unnecessary
+ serialization.</emphasis>
+
+ What if Harry is editing the beginning of a text file,
+ and Sally simply wants to edit the end of the same file?
+ 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
+ situation.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Locking may create a false sense of
+ security.</emphasis>
+
+ 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 they need not bother discussing
+ their incompatible changes early on. Locking often
+ becomes a substitute for real communication.</para>
+ </listitem>
+ </itemizedlist>
+
+ </sect3>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.basic.vsn-models.copy-merge">
+ <title>The Copy-Modify-Merge Solution</title>
+
<indexterm>
<primary>version control</primary>
<secondary>models</secondary>
<tertiary>copy-modify-merge</tertiary>
</indexterm>
- 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
- 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
- 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
- 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
- <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; 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
- process.</para>
-
- <figure id="svn.basic.vsn-models.copy-merge.dia-1">
- <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"/>
- </figure>
-
- <para>But what if Sally's changes <emphasis>do</emphasis> overlap
- with Harry's changes? What then? This situation is called a
- <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
- 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
- manually resolved the overlapping changes—perhaps after
- a discussion with Sally—he can safely save the
- 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
- 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 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
- 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
- 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>
-
- <para>While the lock-modify-unlock model is considered
- generally harmful to collaboration, sometimes
- locking is appropriate.</para>
-
- <para>The copy-modify-merge model is based on the assumption
- 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
- impossible to merge conflicting changes. In these
- situations, it really is necessary for users to take strict
- turns when changing the file. Without serialized access,
- somebody ends up wasting time on changes that are ultimately
- discarded.</para>
-
- <para>While Subversion is primarily a copy-modify-merge
- system, it still recognizes the need to lock an occasional
- file, and thus provides mechanisms for this. We discuss
- this feature in <xref linkend="svn.advanced.locking"/>.</para>
-
- </sidebar>
-
-
+ <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
+ contacts the project repository and creates a personal
+ <firstterm>working copy</firstterm>—a local reflection
+ of the repository's files and directories, managed by the
+ version control system. 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
+ 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
+ <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; 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 process.</para>
+
+ <figure id="svn.basic.vsn-models.copy-merge.dia-1">
+ <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"/>
+ </figure>
+
+ <para>But what if Sally's changes <emphasis>do</emphasis> overlap
+ with Harry's changes? What then? This situation is called a
+ <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 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 manually resolved the overlapping
+ changes—perhaps after a discussion with Sally—he
+ can safely save the 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
+ 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 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 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 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>
+
+ <para>While the lock-modify-unlock model is considered
+ generally harmful to collaboration, sometimes
+ locking is appropriate.</para>
+
+ <para>The copy-modify-merge model is based on the assumption
+ 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
+ impossible to merge conflicting changes. In these
+ situations, it really is necessary for users to take strict
+ turns when changing the file. Without serialized access,
+ somebody ends up wasting time on changes that are ultimately
+ discarded.</para>
+
+ <para>While Subversion is primarily a copy-modify-merge
+ system, it still recognizes the need to lock an occasional
+ file, and thus provides mechanisms for this. We discuss
+ this feature in <xref linkend="svn.advanced.locking"/>.</para>
+
+ </sidebar>
+
+ </sect3>
</sect2>
-
</sect1>
<!-- =================================================================
-->
<!-- =================================================================
-->
<!-- =================================================================
-->
<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>
+ <title>Version Control the Subversion Way</title>
+
+ <para>We've mentioned already that Subversion is a modern,
+ network-aware version control system. As we described in the
+ high-level version control overview of
+ <xref linkend="svn.basic.version-control-basics"/>, a repository
+ serves as the core storage mechanism for Subversion's versioned
+ data, and its via working copies that users and their software
+ programs interact with that data. In this section, we'll begin
+ to introduce the specific ways in which Subversion implements
+ version control.</para>
<!-- ===============================================================
-->
- <sect2 id="svn.advanced.reposurls">
- <title>Subversion Repository URLs</title>
-
- <para>
+ <sect2 id="svn.basic.svn-repositories">
+ <title>Subversion Repositories</title>
+
+ <para>Subversion implements the concept of a version control
+ repository much as any other modern version control system
+ would. Unlike a working copy, a Subversion repository is an
+ abstract entity, able to be operated upon almost exclusively
+ by Subversion's own libraries and tools. As most of a user's
+ Subversion interactions involve the use of the Subversion
+ client and occur in the context of a working copy, we spend
+ the majority of this book discussing the Subversion working
+ copy and how to manipulate it. For the finer details of the
+ repository, though, check out
+ <xref linkend="svn.reposadmin"/>.</para>
+
+ </sect2>
+
+ <!-- ===============================================================
-->
+ <sect2 id="svn.basic.in-action.revs">
+ <title>Revisions</title>
+
+ <indexterm>
+ <primary>revisions</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+
+ <para>A Subversion client commits (that is, communicates changes
+ to) any number of files and directories as a single atomic
+ transaction. By atomic transaction, we mean simply this:
+ either all of the changes are accepted into the repository, or
+ none of them is. 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 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 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"/>
+ </figure>
+
+ <sidebar>
+ <title>Global Revision Numbers</title>
+
<indexterm>
- <primary>svn</primary>
- <secondary>syntax</secondary>
- <tertiary>URLs</tertiary>
+ <primary>revisions</primary>
+ <secondary>global</secondary>
</indexterm>
- <indexterm>
- <primary>svnsync</primary>
- <secondary>syntax</secondary>
- <tertiary>URLs</tertiary>
- </indexterm>
-
- 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>
+
+ <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! 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>
+
+ </sect2>
+
+ <!-- ===============================================================
-->
+ <sect2 id="svn.advanced.reposurls">
+ <title>Addressing the Repository</title>
+
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>syntax</secondary>
+ <tertiary>URLs</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>svnsync</primary>
+ <secondary>syntax</secondary>
+ <tertiary>URLs</tertiary>
+ </indexterm>
+
+ <para>Subversion client programs use 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
+ <para>Subversion repository URLs aren't limited to only
+ the <literal>http://</literal> variety. Because Subversion
+ offers several different ways for its clients to communicate
+ with its servers, the URLs used to address the repository
+ change subtly depending on which repository access mechanism
+ is employed. <xref linkend="svn.basic.in-action.wc.tbl-1"/>
+ describes how different URL schemes map to the available
+ repository access methods. For more details about
+ Subversion's server options, see
+ <xref linkend="svn.serverconfig"/>.</para>
+
+ <table id="svn.basic.in-action.wc.tbl-1">
+ <title>Repository access URLs</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Schema</entry>
+ <entry>Access method</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>file:///</literal></entry>
+ <entry>Direct repository access (on local disk)</entry>
+ </row>
+ <row>
+ <entry><literal>http://</literal></entry>
+ <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
+ SSL encryption.</entry>
+ </row>
+ <row>
+ <entry><literal>svn://</literal></entry>
+ <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
+ an SSH tunnel.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Subversion's handling of URLs has some notable nuances.
+ 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>
@@ -434,81 +632,18 @@
copy—the commandline client knows the repository's root
URL by looking at the working copy's metadata.</para>
- <sidebar id="svn.basic.in-action.wc.sb-1">
- <title>Repository URLs</title>
-
- <para>You can access Subversion repositories through many
- 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.
- <xref linkend="svn.basic.in-action.wc.tbl-1"/> describes how
- different URL schemes map to the available access
- methods.</para>
-
- <table id="svn.basic.in-action.wc.tbl-1">
- <title>Repository access URLs</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Schema</entry>
- <entry>Access method</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>file:///</literal></entry>
- <entry>Direct repository access (on local disk)</entry>
- </row>
- <row>
- <entry><literal>http://</literal></entry>
- <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
- SSL encryption.</entry>
- </row>
- <row>
- <entry><literal>svn://</literal></entry>
- <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
- an SSH tunnel.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>For more information on how Subversion parses URLs, see
- <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>
-
</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>
- <indexterm>
- <primary>working copy</primary>
- <secondary>defined</secondary>
- </indexterm>
-
- A Subversion working copy is an ordinary directory tree on
+ <title>Subversion Working Copies</title>
+
+ <indexterm>
+ <primary>working copy</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+
+ <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
files, you can compile your program from them in the usual
@@ -537,24 +672,109 @@
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
- top-level subdirectory, as shown in <xref
- linkend="svn.basic.in-action.wc.dia-1"/>.</para>
-
- <figure id="svn.basic.in-action.wc.dia-1">
- <title>The repository's filesystem</title>
- <graphic fileref="images/ch02dia6.png"/>
- </figure>
-
- <para>
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.basic.in-action.track-repos">
+ <title>How the working copy works</title>
+
+ <para>For each file in a working directory, Subversion records
+ (among other things) two essential pieces of
+ information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>What revision your working file is based on (this is
+ called the file's <firstterm>working
+ revision</firstterm>)</para>
+ </listitem>
+ <listitem>
+ <para>A timestamp recording when the local copy was last
+ updated by the repository</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Given this information, by talking to the repository,
+ Subversion can tell which of the following four states a
+ working file is in:</para>
+
+ <variablelist>
+ <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 to the
+ repository since its working revision. An <command>svn
+ commit</command> of the file will do nothing, and an
+ <command>svn update</command> of the file will do
+ 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 you last updated. There are local
+ changes that have not been committed to the repository;
***The diff for this file has been truncated for email.***
=======================================
--- /trunk/src/en/book/ch02-basic-usage.xml Thu Oct 14 09:13:08 2010
+++ /trunk/src/en/book/ch02-basic-usage.xml Thu Oct 14 14:58:06 2010
@@ -32,7 +32,6 @@
<secondary>subcommands</secondary>
<tertiary>help</tertiary>
</indexterm>
-
Before reading on, here is the most important command you'll
ever need when using Subversion: <command>svn help</command>.
The Subversion command-line client is self-documenting—at
@@ -69,7 +68,6 @@
<primary>svn</primary>
<secondary>options</secondary>
</indexterm>
-
The Subversion command-line client has numerous command
modifiers (which we call options), but there are two
distinct kinds of options: short options are a single hyphen
@@ -116,7 +114,6 @@
<secondary>subcommands</secondary>
<tertiary>import</tertiary>
</indexterm>
-
The <command>svn import</command> command is a quick way to
copy an unversioned tree of files into a repository, creating
intermediate directories as necessary. <command>svn
@@ -157,8 +154,8 @@
<para>Note that after the import is finished, the original local
directory is <emphasis>not</emphasis> converted into a working
copy. To begin working on that data in a versioned fashion,
- you still need to <command>svn checkout</command> a fresh
- working copy of that tree.</para>
+ you still need to create a fresh working copy of that
+ tree.</para>
</sect2>
@@ -179,7 +176,6 @@
<indexterm>
<primary>project root</primary>
</indexterm>
-
Subversion provides the ultimate flexibility in terms of
how you arrange your data. Because it simply versions
directories and files, and because it ascribes no particular
@@ -242,35 +238,9 @@
</sect2>
- </sect1>
-
- <!-- =================================================================
-->
- <!-- =================================================================
-->
- <!-- =================================================================
-->
- <sect1 id="svn.tour.initial">
- <title>Initial Checkout</title>
-
- <para>Most of the time, you will start using a Subversion
- repository by doing a <firstterm>checkout</firstterm> of your
- project. Checking out a repository creates a <quote>working
- copy</quote> of it on your local machine. This copy contains
- the <literal>HEAD</literal> (latest revision) of the Subversion
- repository that you specify on the command line:</para>
-
-
- <screen>
-$ svn checkout http://svn.collab.net/repos/svn/trunk
-A trunk/Makefile.in
-A trunk/ac-helpers
-A trunk/ac-helpers/install.sh
-A trunk/ac-helpers/install-sh
-A trunk/build.conf
-…
-Checked out revision 8810.
-</screen>
-
- <sidebar>
- <title>What's in a Name?</title>
+ <!-- ===============================================================
-->
+ <sect2 id="svn.tour.importing.naming">
+ <title>What's In a Name?</title>
<para>Subversion tries hard not to limit the type of data you
can place under version control. The contents of files and
@@ -313,45 +283,74 @@
use it will automatically escape illegal
path characters as needed in URLs that you type.</para>
- </sidebar>
-
- <para>Although the preceding example checks out the trunk directory,
- you can just as easily check out any deep subdirectory of a
- repository by specifying the subdirectory in the checkout
- URL:</para>
+ </sect2>
+ </sect1>
+
+ <!-- =================================================================
-->
+ <!-- =================================================================
-->
+ <!-- =================================================================
-->
+ <sect1 id="svn.tour.initial">
+ <title>Creating a Working Copy</title>
+
+ <para>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>checkout</tertiary>
+ </indexterm>
+ Most of the time, you will start using a Subversion repository
+ by performing a <firstterm>checkout</firstterm> of your project.
+ Checking out a directory from a repository creates a working
+ copy of that directory on your local machine. Unless otherwise
+ specified, this copy contains the youngest (that is, most
+ recently created or modified) versions of the directory and its
+ children found in the Subversion repository:</para>
<screen>
-$ svn checkout \
- http://svn.collab.net/repos/svn/trunk/subversion/tests/cmdline/
-A cmdline/revert_tests.py
-A cmdline/diff_tests.py
-A cmdline/autoprop_tests.py
-A cmdline/xmltests
-A cmdline/xmltests/svn-test.sh
+$ svn checkout http://host.example.com/svn/repo/trunk
+A trunk/README
+A trunk/INSTALL
+A trunk/src/main.c
+A trunk/src/header.h
…
Checked out revision 8810.
+$
</screen>
- <para>Since Subversion uses a copy-modify-merge
- model instead of lock-modify-unlock (see
- <xref linkend="svn.basic.vsn-models"/>), you can immediately
- make changes to the files and directories in your working
- copy. Your working copy is just like any other collection of
- files and directories on your system. You can edit and change
- it, move it around, even delete the entire working copy and
- forget about it.</para>
-
- <warning>
- <para>While your working copy is <quote>just like any other
- collection of files and directories on your system,</quote>
- you can edit files at will, but you must tell Subversion
- about <emphasis>everything else</emphasis> that you do. For
- example, if you want to copy or move an item in a working
- copy, you should use <command>svn copy</command> or
- <command>svn move</command> instead of the copy and move
- commands provided by your operating system. We'll talk more
- about them later in this chapter.</para>
- </warning>
+ <para>Although the preceding example checks out the trunk
+ directory, you can just as easily check out a deeper
+ subdirectory of a repository by specifying that subdirectory's
+ URL as the checkout URL:</para>
+
+ <screen>
+$ svn checkout http://host.example.com/svn/repo/trunk/src
+A src/main.c
+A src/header.h
+A src/lib/helpers.c
+…
+Checked out revision 8810.
+$
+</screen>
+
+ <para>Since Subversion uses a copy-modify-merge model instead of
+ lock-modify-unlock (see <xref linkend="svn.basic.vsn-models"/>),
+ you can immediately make changes to the files and directories in
+ your working copy. Your working copy is just like any other
+ collection of files and directories on your system. You can
+ edit and change it, move it around, even delete the entire
+ working copy and forget about it.</para>
+
+ <warning>
+ <para>While your working copy is <quote>just like any other
+ collection of files and directories on your system,</quote>
+ you can edit files at will, but you must tell Subversion
+ about <emphasis>everything else</emphasis> that you do. For
+ example, if you want to copy or move an item in a working
+ copy, you should use <command>svn copy</command> or
+ <command>svn move</command> instead of the copy and move
+ commands provided by your operating system. We'll talk more
+ about them later in this chapter.</para>
+ </warning>
<para>Unless you're ready to commit the addition of a new file or
directory or changes to existing ones, there's no need to
@@ -366,8 +365,9 @@
<filename>.svn</filename>. Usually, directory listing
commands won't show this subdirectory, but it is nevertheless
an important directory. Whatever you do, don't delete or
- change anything in the administrative area! Subversion
- depends on it to manage your working copy.</para>
+ change anything in the administrative area! Subversion use
+ that directory and its contents to manage your working
+ copy.</para>
<para>If you accidentally remove the <filename>.svn</filename>
subdirectory, the easiest way to fix the problem is to remove
@@ -378,66 +378,90 @@
new <filename>.svn</filename> area as well.</para>
</sidebar>
- <para>While you can certainly check out a working copy with the
- URL of the repository as the only argument, you can also specify
- a directory after your repository URL. This places your working
- copy in the new directory that you name. For example:</para>
+ <para>Notice that in the previous pair of examples, Subversion
+ chose to create a working copy in a directory named for the
+ final component of the checkout URL. This occurs only as a
+ convenience to the user when the checkout URL is the only bit of
+ information provided to the <command>svn checkout</command>
+ command. Subversion's command-line client gives you additional
+ flexibility, though, allowing you to optionally specify the
+ local directory name that Subversion should use for the working
+ copy it creates.For example:</para>
<screen>
-$ svn checkout http://svn.collab.net/repos/svn/trunk subv
-A subv/Makefile.in
-A subv/ac-helpers
-A subv/ac-helpers/install.sh
-A subv/ac-helpers/install-sh
-A subv/build.conf
+$ svn checkout http://host.example.com/svn/repo/trunk my-working-copy
+A my-working-copy/README
+A my-working-copy/INSTALL
+A my-working-copy/src/main.c
+A my-working-copy/src/header.h
…
Checked out revision 8810.
+$
</screen>
- <para>That will place your working copy in a directory named
- <literal>subv</literal> instead of a directory named
- <literal>trunk</literal> as we did previously. The directory
- <literal>subv</literal> will be created if it doesn't already
- exist.</para>
-
+ <para>If the local directory you specify doesn't yet
+ exist, that's okay—<command>svn checkout</command> will
+ create it for you.</para>
<sect2 id="svn.tour.initial.disabling-password-caching">
<title>Disabling Password Caching</title>
<para>When you perform a Subversion operation that requires you
to authenticate, by default Subversion tries to cache your
- authentication credentials on disk in encrypted form.
- On some systems, Subversion may be unable to encrypt your
- authentication data. You will then be asked whether you
- want to cache your credentials to disk in plaintext.
- You can choose to do so for convenience so that you don't have
- to continually reenter your password for future operations.
- If you're concerned about caching your Subversion passwords
- in plaintext and do not want to be asked about it again and
- again, you can disable caching of plaintext passwords either
- permanently, or on a server-per-server basis.</para>
+ authentication credentials on disk in encrypted form. On some
+ systems, Subversion may be unable to encrypt your
+ authentication data. In those situations, Subversion will ask
+ whether you want to cache your credentials to disk in
+ plaintext:</para>
+
+ <screen>
+$ svn checkout https://host.example.com:443/svn/private-repo
+-----------------------------------------------------------------------
+ATTENTION! Your password for authentication realm:
+
+ <https://host.example.com:443> Subversion Repository
+
+can only be stored to disk unencrypted! You are advised to configure
+your system so that Subversion can store passwords encrypted, if
+possible. See the documentation for details.
+
+You can avoid future appearances of this warning by setting the value
+of the 'store-plaintext-passwords' option to either 'yes' or 'no' in
+'/tmp/servers'.
+-----------------------------------------------------------------------
+Store password unencrypted (yes/no)?
+</screen>
+
+ <para>If you want the convenience of not having to continually
+ reenter your password for future operations, you can
+ answer <literal>yes</literal> to this prompt. You'll want to
+ consult any governing policies that are in place for your
+ client computer—many companies have strict rules about
+ the ways that their employees' authentication credentials
+ should be stored. If you're concerned about caching your
+ Subversion passwords in plaintext and do not want to be asked
+ about it again and again, you can disable caching of plaintext
+ passwords either permanently, or on a server-per-server
+ basis.</para>
<para>To permanently disable caching of passwords in plaintext,
- you can add the line
- <literal>store-plaintext-passwords = no</literal>
- to the global section in the <filename>servers</filename>
- configuration file on the local machine. To disable caching
- of plaintext passwords for a particular server, use the same
- setting in the appropriate group section in the
+ add the line <literal>store-plaintext-passwords = no</literal>
+ to the <literal>[global]</literal> section in
+ the <filename>servers</filename> configuration file on the
+ local machine. To disable plaintext password caching for
+ a particular server, use the same setting in the appropriate
+ group section in the
<filename>servers</filename> configuration file.
See <xref linkend="svn.advanced.confarea.opts"/>
in <xref linkend="svn.customization"/> for details.</para>
- <para>You can also disable caching of authentication credentials
- entirely, regardless of whether the credentials are stored
- in encrypted form or not.</para>
-
- <para>To disable password caching entirely for a particular one-time
- command, pass the <option>--no-auth-cache</option> option on
- the command line. To permanently disable caching entirely,
- you can add the line <literal>store-passwords = no</literal>
- to your local machine's Subversion configuration file. See <xref
- linkend="svn.serverconfig.netmodel.credcache"/> for
+ <para>To disable password caching entirely for any single
+ Subversion command-line operation, pass
+ the <option>--no-auth-cache</option> option to that command
+ line. To permanently disable caching entirely, add the
+ line <literal>store-passwords = no</literal> to your local
+ machine's Subversion configuration file. See
+ <xref linkend="svn.serverconfig.netmodel.credcache"/> for
details.</para>
</sect2>
=======================================
--- /trunk/src/en/book/ch03-advanced-topics.xml Wed Oct 13 06:26:32 2010
+++ /trunk/src/en/book/ch03-advanced-topics.xml Thu Oct 14 14:58:06 2010
@@ -71,43 +71,11 @@
<!-- ===============================================================
-->
<sect2 id="svn.tour.revs.keywords">
<title>Revision Keywords</title>
-
+
<indexterm>
<primary>revisions</primary>
<secondary>keywords</secondary>
</indexterm>
- <indexterm>
- <primary>HEAD</primary>
- </indexterm>
- <indexterm>
- <primary>revisions</primary>
- <secondary>keywords</secondary>
- <tertiary>HEAD</tertiary>
- </indexterm>
- <indexterm>
- <primary>BASE</primary>
- </indexterm>
- <indexterm>
- <primary>revisions</primary>
- <secondary>keywords</secondary>
- <tertiary>BASE</tertiary>
- </indexterm>
- <indexterm>
- <primary>COMMITTED</primary>
- </indexterm>
- <indexterm>
- <primary>revisions</primary>
- <secondary>keywords</secondary>
- <tertiary>COMMITTED</tertiary>
- </indexterm>
- <indexterm>
- <primary>PREV</primary>
- </indexterm>
- <indexterm>
- <primary>revisions</primary>
- <secondary>keywords</secondary>
- <tertiary>PREV</tertiary>
- </indexterm>
<para>The Subversion client understands a number of revision
keywords. These keywords can be used instead of integer
@@ -116,6 +84,39 @@
revision numbers by Subversion:</para>
<variablelist>
+
+ <indexterm>
+ <primary>HEAD</primary>
+ </indexterm>
+ <indexterm>
+ <primary>revisions</primary>
+ <secondary>keywords</secondary>
+ <tertiary>HEAD</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>BASE</primary>
+ </indexterm>
+ <indexterm>
+ <primary>revisions</primary>
+ <secondary>keywords</secondary>
+ <tertiary>BASE</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>COMMITTED</primary>
+ </indexterm>
+ <indexterm>
+ <primary>revisions</primary>
+ <secondary>keywords</secondary>
+ <tertiary>COMMITTED</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>PREV</primary>
+ </indexterm>
+ <indexterm>
+ <primary>revisions</primary>
+ <secondary>keywords</secondary>
+ <tertiary>PREV</tertiary>
+ </indexterm>
<varlistentry>
<term><literal>HEAD</literal></term>
@@ -297,6 +298,7 @@
<!-- =================================================================
-->
<sect1 id="svn.advanced.props">
<title>Properties</title>
+
<indexterm>
<primary>properties</primary>
</indexterm>
@@ -3964,8 +3966,8 @@
server responds with an appropriate answer. The details of
the network protocol are hidden from the user—the client
attempts to access a URL, and depending on the URL scheme, a
- particular protocol is used to contact the server (see the sidebar
<xref
- linkend="svn.basic.in-action.wc.sb-1"/>).</para>
+ particular protocol is used to contact the server (see <xref
+ linkend="svn.advanced.reposurls"/>).</para>
<tip><para>Run <userinput>svn --version</userinput> to see
which URL schemes and protocols the client knows how to
More information about the svnbook-dev
mailing list