[svnbook] r4415 committed - Indexing work. Most of this is syntactic: the way we were doing index...
svnbook at googlecode.com
svnbook at googlecode.com
Fri Feb 8 08:50:11 CST 2013
Revision: 4415
Author: cmpilato at gmail.com
Date: Fri Feb 8 06:49:58 2013
Log: Indexing work. Most of this is syntactic: the way we were doing
index
tagging left gaping whitespace holes in the PDF versions of the book.
Some is semantic, trying to ensure that anywhere we have a <firstterm>
tag, we also have an index reference, etc.
* en/book/ch00-preface.xml,
* en/book/ch01-fundamental-concepts.xml
http://code.google.com/p/svnbook/source/detail?r=4415
Modified:
/trunk/en/book/ch00-preface.xml
/trunk/en/book/ch01-fundamental-concepts.xml
=======================================
--- /trunk/en/book/ch00-preface.xml Thu Feb 7 12:43:50 2013
+++ /trunk/en/book/ch00-preface.xml Fri Feb 8 06:49:58 2013
@@ -12,22 +12,21 @@
own shadow during design.</quote></para>
</blockquote>
- <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
- operation allowed dozens of geographically dispersed programmers
- to share their work. It fit the collaborative nature of the
- open source world very well. CVS and its semi-chaotic development
- model have since become cornerstones of open source
+ <para>
+ <indexterm>
+ <primary>Concurrent Versions System</primary>
+ </indexterm>
+ <indexterm>
+ <primary>CVS</primary>
+ <see>Concurrent Versions System</see>
+ </indexterm>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 operation allowed dozens of geographically dispersed
+ programmers to share their work. It fit the collaborative nature
+ of the open source world very well. CVS and its semi-chaotic
+ development model have since become cornerstones of open source
culture.</para>
<para>But CVS was not without its flaws, and simply fixing those
@@ -57,28 +56,26 @@
<!-- =================================================================
-->
<!-- =================================================================
-->
<sect1 id="svn.intro.whatis">
-
<title>What Is Subversion?</title>
- <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>
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>version control system</primary>
+ </indexterm>
+ <indexterm>
+ <primary>VCS</primary>
+ <see>version control system</see>
+ </indexterm>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
@@ -90,22 +87,21 @@
losing that conduit—if some incorrect change is made to
the data, just undo that change.</para>
- <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
+ <para>
+ <indexterm>
+ <primary>software configuration management</primary>
+ </indexterm>
+ <indexterm>
+ <primary>SCM</primary>
+ <see>software configuration management</see>
+ </indexterm>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
@@ -114,7 +110,6 @@
<!-- ===============================================================
-->
<sect2 id="svn.intro.righttool">
-
<title>Is Subversion the Right Tool?</title>
<para>If you're a user or system administrator pondering the use
@@ -167,21 +162,34 @@
overhead of tracking changes, such as <command>rsync</command>
or <command>unison</command>.</para>
- <para>Once you've decided that you need a version control
- solution, you'll find no shortage of available options. When
- Subversion was first designed and released, the predominant
- methodology of version control was <firstterm>centralized
- version control</firstterm>—a single remote master
- storehouse of versioned data with individual users operating
- locally against shallow copies of that data's version history.
- Subversion quickly emerged after its initial introduction as
- the clear leader in this field of version control, earning
- widespread adoption and supplanting installations of many
- older version control systems. It continues to hold that
- prominent position today.</para>
+ <para>
+ <indexterm>
+ <primary>centralized version control</primary>
+ </indexterm>Once you've decided that you need a version
+ control solution, you'll find no shortage of available
+ options. When Subversion was first designed and released, the
+ predominant methodology of version control
+ was <firstterm>centralized version control</firstterm>—a
+ single remote master storehouse of versioned data with
+ individual users operating locally against shallow copies of
+ that data's version history. Subversion quickly emerged after
+ its initial introduction as the clear leader in this field of
+ version control, earning widespread adoption and supplanting
+ installations of many older version control systems. It
+ continues to hold that prominent position today.</para>
- <para>Much as changed since that time, though. In the years
- since the Subversion project began its life, a newer
+ <para>
+ <indexterm>
+ <primary>changesets</primary>
+ </indexterm>
+ <indexterm>
+ <primary>distributed version control</primary>
+ </indexterm>
+ <indexterm>
+ <primary>DVCS</primary>
+ <see>distributed version control</see>
+ </indexterm>Much as changed since that time, though. In the
+ years since the Subversion project began its life, a newer
methodology of version control called <firstterm>distributed
version control</firstterm> has likewise garnered widespread
attention and adoption. Tools such as Git
@@ -240,15 +248,14 @@
<title>Subversion's History</title>
- <indexterm>
- <primary>Subversion</primary>
- <secondary>history of</secondary>
- </indexterm>
- <indexterm>
- <primary>CollabNet</primary>
- </indexterm>
-
- <para>In early 2000, CollabNet,
+ <para>
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>history of</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>CollabNet</primary>
+ </indexterm>In early 2000, CollabNet,
Inc. (<ulink url="http://www.collab.net"/>) began seeking
developers to write a replacement for CVS. CollabNet
offered<footnote><para>CollabNet Enterprise Edition has since
@@ -303,9 +310,13 @@
<quote>self-hosting</quote> on August 31, 2001. That is,
Subversion developers stopped using CVS to manage Subversion's
own source code and started using Subversion instead.</para>
-
- <para>While CollabNet started the project, and still funds a
- large chunk of the work (it pays the salaries of a few
+
+ <para>
+ <indexterm>
+ <primary>Apache Subversion</primary>
+ <seealso>Subversion</seealso>
+ </indexterm>While CollabNet started the project, and still
+ funds a large chunk of the work (it pays the salaries of a few
full-time Subversion developers), Subversion is run like most
open source projects, governed by a loose, transparent set of
rules that encourage meritocracy. In 2009, CollabNet worked
@@ -327,14 +338,13 @@
<sect2 id="svn.intro.architecture">
<title>Subversion's Architecture</title>
-
- <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
+
+ <para>
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>architecture</secondary>
+ </indexterm><xref linkend="svn.intro.architecture.dia-1"/>
+ illustrates a <quote>mile-high</quote> view of Subversion's
design.</para>
<figure id="svn.intro.architecture.dia-1">
@@ -357,21 +367,19 @@
<sect2 id="svn.intro.components">
<title>Subversion's Components</title>
-
- <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
+
+ <para>
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>components</secondary>
+ </indexterm>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>
<variablelist>
-
<indexterm>
<primary>svn</primary>
</indexterm>
@@ -386,7 +394,7 @@
</indexterm>
<indexterm>
<primary>mod_dav_svn</primary>
- </indexterm>
+ </indexterm>
<indexterm>
<primary>svnserve</primary>
</indexterm>
@@ -396,6 +404,12 @@
<indexterm>
<primary>svnsync</primary>
</indexterm>
+ <indexterm>
+ <primary>svnrdump</primary>
+ </indexterm>
+ <indexterm>
+ <primary>svnmucc</primary>
+ </indexterm>
<varlistentry>
<term>svn</term>
@@ -430,7 +444,7 @@
<varlistentry>
<term>mod_dav_svn</term>
<listitem>
- <para>A plug-in module for the Apache HTTP Server, used to
+ <para>A plug-in module for the Apache HTTP Server, used to
make your repository available to others over a
network</para>
</listitem>
@@ -456,8 +470,8 @@
<varlistentry>
<term>svnsync</term>
<listitem>
- <para>A program for incrementally mirroring one
- repository to another over a network</para>
+ <para>A program for incrementally mirroring one repository
+ to another over a network</para>
</listitem>
</varlistentry>
@@ -469,6 +483,15 @@
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>svnmucc</term>
+ <listitem>
+ <para>A program for performing multiple repository
+ URL-based operations in a single commit and without the
+ use of a working copy</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect2>
@@ -478,14 +501,13 @@
<title>What's New in Subversion</title>
- <indexterm>
- <primary>Subversion</primary>
- <secondary>history of</secondary>
- </indexterm>
-
- <para>The first edition of this book was published by O'Reilly
- Media in 2004, shortly after Subversion had reached 1.0.
- Since that time, the Subversion project has continued to
+ <para>
+ <indexterm>
+ <primary>Subversion</primary>
+ <secondary>history of</secondary>
+ </indexterm>The first edition of this book was published by
+ O'Reilly Media in 2004, shortly after Subversion had reached
+ 1.0. Since that time, the Subversion project has continued to
release new major releases of the software. 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
@@ -672,23 +694,23 @@
<sect1 id="svn.preface.howread">
<title>How to Read This Book</title>
- <para>Technical books always face a certain dilemma: whether to
- cater to <firstterm>top-down</firstterm>
- or to <firstterm>bottom-up</firstterm> learners. A top-down
- learner prefers to read or skim documentation, getting a large
- overview of how the system works; only then does she actually
- start using the software. A bottom-up learner is a <quote>learn by
- doing</quote> person—someone who just wants to dive into the
- software and figure it out as she goes, referring to book
- sections when necessary. Most books tend to be written for one
- type of person or the other, and this book is undoubtedly biased
- toward top-down learners. (And if you're actually reading this
+ <para>Technical books always face a certain dilemma: whether to
+ cater to <quote>top-down</quote> or to <quote>bottom-up</quote>
+ learners. A top-down learner prefers to read or skim
+ documentation, getting a large overview of how the system works;
+ only then does she actually start using the software. A
+ bottom-up learner is a <quote>learn by doing</quote>
+ person—someone who just wants to dive into the software
+ and figure it out as she goes, referring to book sections when
+ necessary. Most books tend to be written for one type of person
+ or the other, and this book is undoubtedly biased toward
+ top-down learners. (And if you're actually reading this
section, you're probably already a top-down learner yourself!)
However, if you're a bottom-up person, don't despair. While the
book may be laid out as a broad survey of Subversion topics, the
- content of each section tends to be heavy with specific
- examples that you can try-by-doing. For the impatient folks who
- just want to get going, you can jump right to
+ content of each section tends to be heavy with specific examples
+ that you can try-by-doing. For the impatient folks who just
+ want to get going, you can jump right to
<xref linkend="svn.intro"/>.</para>
<para>Regardless of your learning style, this book aims to be
=======================================
--- /trunk/en/book/ch01-fundamental-concepts.xml Thu Feb 7 12:43:50 2013
+++ /trunk/en/book/ch01-fundamental-concepts.xml Fri Feb 8 06:49:58 2013
@@ -21,18 +21,17 @@
<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
+ <para>
+ <indexterm>
+ <primary>version control system</primary>
+ </indexterm>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
@@ -46,14 +45,21 @@
<sect2 id="svn.basic.repository">
<title>The Repository</title>
- <indexterm>
- <primary>repository</primary>
- <secondary>defined</secondary>
- </indexterm>
-
- <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
+ <para>
+ <indexterm>
+ <primary>repository</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>repository</primary>
+ <secondary>filesystem tree</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>version control system</primary>
+ <secondary>clients</secondary>
+ </indexterm>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
@@ -92,26 +98,25 @@
<sect2 id="svn.basic.working-copy">
<title>The Working Copy</title>
- <indexterm>
- <primary>working copy</primary>
- <secondary>defined</secondary>
- </indexterm>
-
- <para>A version control system's value comes from 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>
+ <indexterm>
+ <primary>working copy</primary>
+ <secondary>defined</secondary>
+ </indexterm>A version control system's value comes from 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
@@ -185,13 +190,12 @@
<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>
-
- <para>Many version control systems use a
+ <para>
+ <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
@@ -266,37 +270,38 @@
<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>
-
- <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
- working copy. Users then work simultaneously and
+ <para>
+ <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 working copy. 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.
+ <para>
+ <indexterm>
+ <primary>out of date</primary>
+ </indexterm>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 merge 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>
@@ -311,12 +316,13 @@
<graphic fileref="images/ch02dia5.png"/>
</figure>
- <indexterm>
- <primary>conflicts</primary>
- </indexterm>
-
- <para>But what if Sally's changes <emphasis>do</emphasis> overlap
- with Harry's changes? What then? This situation is called a
+ <para>
+ <indexterm>
+ <primary>conflicts</primary>
+ <secondary>defined</secondary>
+ </indexterm>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
@@ -414,11 +420,6 @@
<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 the
changes made to) any number of files and directories as a
single atomic transaction. By atomic transaction, we mean
@@ -427,8 +428,12 @@
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
+ <para>
+ <indexterm>
+ <primary>revision</primary>
+ <secondary>defined</secondary>
+ </indexterm>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 assigned to
the previous revision. The initial revision of a freshly
@@ -450,19 +455,18 @@
<sidebar>
<title>Global Revision Numbers</title>
- <indexterm>
- <primary>revisions</primary>
- <secondary>global</secondary>
- </indexterm>
-
- <para>Unlike most version control systems, Subversion's
- revision numbers apply to <emphasis>the entire repository
- tree</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>
+ <indexterm>
+ <primary>revision</primary>
+ <secondary>global</secondary>
+ </indexterm>Unlike most version control systems,
+ Subversion's revision numbers apply to <emphasis>the entire
+ repository tree</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
@@ -479,22 +483,31 @@
<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>
+ <para>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>syntax</secondary>
+ <tertiary>URLs</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>svnmucc</primary>
+ <secondary>syntax</secondary>
+ <tertiary>URLs</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>svnsync</primary>
+ <secondary>syntax</secondary>
+ <tertiary>URLs</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>svnrdump</primary>
+ <secondary>syntax</secondary>
+ <tertiary>URLs</tertiary>
+ </indexterm>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>
<informalexample>
<itemizedlist spacing="compact">
@@ -654,19 +667,18 @@
<sect2 id="svn.basic.in-action.wc">
<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
- way. Your working copy is your own private work area:
- Subversion will never incorporate other people's changes, nor
- make your own changes available to others, until you
- explicitly tell it to do so. You can even have multiple
+ <para>
+ <indexterm>
+ <primary>working copy</primary>
+ <secondary>defined</secondary>
+ </indexterm>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 way. Your working copy is your own private work
+ area: Subversion will never incorporate other people's
+ changes, nor make your own changes available to others, until
+ you explicitly tell it to do so. You can even have multiple
working copies of the same project.</para>
<para>After you've made some changes to the files in your
@@ -682,15 +694,23 @@
directly from working copy to working copy in the typical
workflow.</para>
- <para>A working copy also contains some extra files, created and
- maintained by Subversion, to help it carry out these commands.
- In particular, each working copy contains a subdirectory
- named <filename>.svn</filename>, also known as the working
- copy's <firstterm>administrative directory</firstterm>. The
- files in the administrative directory help Subversion
- recognize which of your versioned files contain unpublished
- changes, and which files are out of date with respect to
- others' work.</para>
+ <para>
+ <indexterm>
+ <primary>administrative directory</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>.svn</primary>
+ <see>administrative directory</see>
+ </indexterm>A working copy also contains some extra files,
+ created and maintained by Subversion, to help it carry out
+ these commands. In particular, each working copy contains a
+ subdirectory named <filename>.svn</filename>, also known as
+ the working copy's <firstterm>administrative
+ directory</firstterm>. The files in the administrative
+ directory help Subversion recognize which of your versioned
+ files contain unpublished changes, and which files are out of
+ date with respect to others' work.</para>
<note>
<para>Prior to version 1.7, Subversion
@@ -728,6 +748,11 @@
(among other things) two essential pieces of information:</para>
<itemizedlist>
+ <indexterm>
+ <primary>revision</primary>
+ <secondary>working</secondary>
+ </indexterm>
+
<listitem>
<para>What revision your working file is based on (this is
called the file's <firstterm>working
@@ -822,21 +847,20 @@
<graphic fileref="images/ch02dia6.png"/>
</figure>
- <indexterm>
- <primary>svn</primary>
- <secondary>subcommands</secondary>
- <tertiary>checkout</tertiary>
- </indexterm>
- <indexterm>
- <primary>working copy</primary>
- <secondary>creation</secondary>
- </indexterm>
- <indexterm>
- <primary>checkout</primary>
- <see>working copy, creation</see>
- </indexterm>
-
- <para>To get a working copy, you must <firstterm>check
+ <para>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>checkout</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>checking out</primary>
+ </indexterm>
+ <indexterm>
+ <primary>working copy</primary>
+ <secondary>creation</secondary>
+ <see>checking out</see>
+ </indexterm>To get a working copy, you must <firstterm>check
out</firstterm> some subtree of the repository. (The term
<emphasis>check out</emphasis> may sound like it has something
to do
with locking or reserving resources, but it doesn't; it simply
@@ -865,31 +889,34 @@
holds the extra information needed by Subversion, as mentioned
earlier.</para>
- <para>Suppose you make changes to <filename>button.c</filename>.
- Since the <filename>.svn</filename> directory remembers the
- file's original modification date and contents, Subversion can
- tell that you've changed the file. However, Subversion does
- not make your changes public until you explicitly tell it to.
+ <para>
+ <indexterm>
+ <primary>committing</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>checking in</primary>
+ <see>committing</see>
+ </indexterm>Suppose you make changes
+ to <filename>button.c</filename>. Since
+ the <filename>.svn</filename> directory remembers the file's
+ original modification date and contents, Subversion can tell
+ that you've changed the file. However, Subversion does not
+ make your changes public until you explicitly tell it to.
The act of publishing your changes is more commonly known as
<firstterm>committing</firstterm> (or <firstterm>checking
in</firstterm>) changes to the repository.</para>
- <indexterm>
- <primary>svn</primary>
- <secondary>subcommands</secondary>
- <tertiary>commit</tertiary>
- </indexterm>
- <indexterm>
- <primary>committing</primary>
- <see>working copy, commit</see>
- </indexterm>
- <indexterm>
- <primary>working copy</primary>
- <secondary>commit</secondary>
- </indexterm>
-
- <para>To publish your changes, you can use Subversion's
- <command>svn commit</command> command:</para>
+ <para>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>commit</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>committing</primary>
+ </indexterm>To publish your changes, you can use
+ Subversion's <command>svn commit</command> command:</para>
<informalexample>
<screen>
@@ -915,25 +942,25 @@
unchanged; Subversion modifies working copies only at the
user's request.</para>
- <indexterm>
- <primary>svn</primary>
- <secondary>subcommands</secondary>
- <tertiary>update</tertiary>
- </indexterm>
- <indexterm>
- <primary>updating</primary>
- <see>working copy, update</see>
- </indexterm>
- <indexterm>
- <primary>working copy</primary>
- <secondary>update</secondary>
- </indexterm>
-
- <para>To bring her project up to date, Sally can ask Subversion
- to <firstterm>update</firstterm> her working copy, by using
- the <command>svn update</command> command. This will incorporate
- your changes into her working copy, as well as any others that
- have been committed since she checked it out.</para>
+ <para>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>update</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>updating</primary>
+ </indexterm>
+ <indexterm>
+ <primary>working copy</primary>
+ <secondary>update</secondary>
+ <see>updating</see>
+ </indexterm>To bring her project up to date, Sally can ask
+ Subversion to <firstterm>update</firstterm> her working
+ copy, by using the <command>svn update</command> command.
+ This will incorporate your changes into her working copy, as
+ well as any others that have been committed since she
+ checked it out.</para>
<informalexample>
<screen>
@@ -963,19 +990,19 @@
<sect3 id="svn.basic.in-action.mixedrevs">
<title>Mixed-revision working copies</title>
- <indexterm>
- <primary>working copy</primary>
- <secondary>mixed-revision</secondary>
- </indexterm>
-
- <para>As a general principle, Subversion tries to be as flexible
- as possible. One special kind of flexibility is the ability
- to have a working copy containing files and directories with a
- mix of different working revision numbers. Subversion working
- copies do not always correspond to any single revision in the
- repository; they may contain files from several different
- revisions. For example, suppose you check out a working copy
- from a repository whose most recent revision is 4:</para>
+ <para>
+ <indexterm>
+ <primary>working copy</primary>
+ <secondary>mixed-revision</secondary>
+ </indexterm>As a general principle, Subversion tries to be
+ as flexible as possible. One special kind of flexibility is
+ the ability to have a working copy containing files and
+ directories with a mix of different working revision
+ numbers. Subversion working copies do not always correspond
+ to any single revision in the repository; they may contain
+ files from several different revisions. For example,
+ suppose you check out a working copy from a repository whose
+ most recent revision is 4:</para>
<informalexample>
<literallayout>
@@ -1110,19 +1137,22 @@
<sect4 id="svn.basic.in-action.mixedrevs.useful">
<title>Mixed revisions are useful</title>
- <para>If your project is sufficiently complex, you'll discover
- that it's sometimes nice to
+ <para>
+ <indexterm>
+ <primary>backdating</primary>
+ </indexterm>If your project is sufficiently complex, you'll
+ discover that it's sometimes nice to
forcibly <firstterm>backdate</firstterm> (or update to a
revision older than the one you already have) portions of
your working copy to an earlier revision; you'll learn how
to do that in <xref linkend="svn.tour"/>. Perhaps you'd
- like to test an earlier version of a submodule contained in
- a subdirectory, or perhaps you'd like to figure out when a
- bug first came into existence in a specific file. This is
- the <quote>time machine</quote> aspect of a version control
- system—the feature that allows you to move any
- portion of your working copy forward and backward in
- history.</para>
+ like to test an earlier version of a submodule contained
+ in a subdirectory, or perhaps you'd like to figure out
+ when a bug first came into existence in a specific file.
+ This is the <quote>time machine</quote> aspect of a
+ version control system—the feature that allows you
+ to move any portion of your working copy forward and
+ backward in history.</para>
</sect4>
More information about the svnbook-dev
mailing list