[svnbook commit] r2659 - branches/fitz-ripping-up-ch-02/src/en/book
fitz
noreply at red-bean.com
Tue Feb 6 01:37:46 CST 2007
Author: fitz
Date: Tue Feb 6 01:37:46 2007
New Revision: 2659
Modified:
branches/fitz-ripping-up-ch-02/src/en/book/ch-advanced-topics.xml
branches/fitz-ripping-up-ch-02/src/en/book/ch-basic-usage.xml
Log:
Chapter 2 now ready for review.
* src/en/book/ch-basic-usage.xml: Refine.
* src/en/book/ch-advanced-topics.xml: Tweak a weird title.
Modified: branches/fitz-ripping-up-ch-02/src/en/book/ch-advanced-topics.xml
==============================================================================
--- branches/fitz-ripping-up-ch-02/src/en/book/ch-advanced-topics.xml (original)
+++ branches/fitz-ripping-up-ch-02/src/en/book/ch-advanced-topics.xml Tue Feb 6 01:37:46 2007
@@ -1755,7 +1755,7 @@
larger locking feature.</para>
<sidebar id="svn.advanced.locking.meanings">
- <title>Three meanings of <quote>lock</quote></title>
+ <title>The three meanings of <quote>lock</quote></title>
<para>In this section, and almost everywhere in this book, the
words <quote>lock</quote> and <quote>locking</quote> describe
Modified: branches/fitz-ripping-up-ch-02/src/en/book/ch-basic-usage.xml
==============================================================================
--- branches/fitz-ripping-up-ch-02/src/en/book/ch-basic-usage.xml (original)
+++ branches/fitz-ripping-up-ch-02/src/en/book/ch-basic-usage.xml Tue Feb 6 01:37:46 2007
@@ -3,13 +3,13 @@
<para>Now we will go into the details of using Subversion. By the
time you reach the end of this chapter, you will be able to
- perform almost all the tasks you need to use Subversion in a
- normal day's work. You'll start with getting your files into
- Subversion, followed by an initial checkout of your code. We'll
- then walk you through making changes and examining those changes.
- You'll also see how to bring changes made by others into your
- working copy, examine them, and work through any conflicts that
- might arise.</para>
+ perform all the tasks you need to use Subversion in a normal day's
+ work. You'll start with getting your files into Subversion,
+ followed by an initial checkout of your code. We'll then walk you
+ through making changes and examining those changes. You'll also
+ see how to bring changes made by others into your working copy,
+ examine them, and work through any conflicts that might
+ arise.</para>
<para>Note that this chapter is not meant to be an exhaustive list
of all Subversion's commands—rather, it's a conversational
@@ -30,7 +30,7 @@
ever need when using Subversion: <command>svn help</command>.
The Subversion command-line client is
self-documenting—at any time, a quick <command>svn help
- <subcommand></command> will describe the syntax, switches,
+ <subcommand></command> will describe the syntax, options,
and behavior of the <command>subcommand</command>.</para>
</sect1>
@@ -99,7 +99,7 @@
even <command>svn revert</command> them) before committing your
changes. This is especially useful if the unversioned files
you're adding are part of a logical change that you're making to
- files that are already in your working copy:</para>
+ files that are already under Subversion's control:</para>
<screen>
$ svn st
@@ -114,7 +114,7 @@
</screen>
<para>We've added our new tree to our working copy which already
- has a modified file in it. Now we're ready to commit our
+ had a modified file in it. Now we're ready to commit our
changes:</para>
<screen>
@@ -141,7 +141,7 @@
<quote>main line</quote> of development, a
<filename>branches</filename> directory to contain branch
copies, and a <filename>tags</filename> directory to contain tag
- copies:</para>
+ copies, for example:</para>
<screen>
$ svn list file:///usr/local/svn/repos
@@ -150,11 +150,11 @@
/tags
</screen>
- <para>For details and how to setup multiple projects, see <xfer
+ <para>For details and how to setup multiple projects, see <xref
linkend="svn.branchmerge.maint.layout"/> and <xref
linkend="svn.reposadmin.projects.chooselayout"/> to read more
- about <quote>project roots</quote></para>
-
+ about <quote>project roots</quote>.</para>
+
</sect2>
</sect1>
@@ -167,23 +167,23 @@
<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 copy 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>
-
+ 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/subversion.dsw
-A trunk/svn_check.dsp
-A trunk/COMMITTERS
-A trunk/configure.in
-A trunk/IDEAS
+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 2499.
+Checked out revision 8810.
</screen>
-
+
<sidebar>
<title>What's in a Name?</title>
@@ -211,9 +211,9 @@
in WebDAV exchanges, as well in as some of Subversion's
housekeeping files. This means that path names can only
contain legal XML (1.0) characters. Subversion also prohibits
- TAB, CR, and LF characters in path names, so they aren't
- broken up in diffs, or in the output of commands like <xref
- linkend="svn.ref.svn.c.log"/> or <xref
+ TAB, CR, and LF characters in path names to prevent paths from
+ being broken up in diffs, or in the output of commands like
+ <xref linkend="svn.ref.svn.c.log"/> or <xref
linkend="svn.ref.svn.c.status"/>.</para>
<para>While it may seem like a lot to remember, in practice
@@ -226,33 +226,24 @@
<quote>legally correct</quote> versions for internal
use.</para>
- <para>Experienced users of Subversion have also developed a set
- of best-practice conventions for laying out paths in the
- repository. While these aren't strict requirements like the
- syntax described above, they help to organize frequently
- performed tasks. The <literal>/trunk</literal> part of URLs
- you'll find throughout this book is one of these conventions;
- we'll talk a lot more about it and related recommendations in
- <xref linkend="svn.branchmerge"/>.</para>
-
</sidebar>
<para>Although the above 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>
-
+
<screen>
-$ svn checkout http://svn.collab.net/repos/svn/trunk/doc/book/tools
-A tools/readme-dblite.html
-A tools/fo-stylesheet.xsl
-A tools/svnbook.el
-A tools/dtd
-A tools/dtd/dblite.dtd
+$ svn co -r 8810 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
…
-Checked out revision 2499.
+Checked out revision 8810.
</screen>
-
+
<para>Since Subversion uses a <quote>copy-modify-merge</quote>
model instead of <quote>lock-modify-unlock</quote> (see <xref
linkend="svn.basic"/>), you're already able to start making
@@ -295,18 +286,18 @@
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>
-
+
<screen>
-$ svn checkout http://svn.collab.net/repos/svn/trunk subv
-A subv/subversion.dsw
-A subv/svn_check.dsp
-A subv/COMMITTERS
-A subv/configure.in
-A subv/IDEAS
+$ svn -r 8810 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
…
-Checked out revision 2499.
+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.</para>
@@ -314,17 +305,17 @@
<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 caches your
authentication credentials on disk. If you're concerned about
caching your Subversion passwords,<footnote><para>Of course,
- you're not terribly worried because a)you know that you can't
- <emphasis>really</emphasis> delete anything from Subversion
- and b)your Subversion password isn't the same as any of the
- other three million passwords you have, right?
- Right?</para></footnote> you can disable caching either
- permanently or on a case-by-case basis.</para>
+ you're not terribly worried—first because you know that
+ you can't <emphasis>really</emphasis> delete anything from
+ Subversion and, secondly, because your Subversion password
+ isn't the same as any of the other three million passwords you
+ have, right? Right?</para></footnote> you can disable caching
+ either permanently or on a case-by-case basis.</para>
<para>To disable password caching for a particular one-time
command, pass the <option >--no-auth-cache</option > option on
@@ -338,7 +329,7 @@
<sect2 id="svn.tour.initial.different-user">
<title>Authenticating as a Different User</title>
-
+
<para>Since Subversion caches auth credentials by default (both
username and password), it conveniently remembers who you were
acting as the last time you modified you working copy. But
@@ -364,7 +355,7 @@
use a few of them. In this section we'll run through the most
common things that you might find yourself doing with Subversion
in the course of a day's work.</para>
-
+
<para>The typical work cycle looks like this:</para>
<itemizedlist>
@@ -375,9 +366,9 @@
<para><command>svn update</command></para>
</listitem>
</itemizedlist>
-
+
</listitem>
-
+
<listitem>
<para>Make changes</para>
<itemizedlist>
@@ -419,7 +410,7 @@
<listitem>
- <para>Resolving Conflicts (Merging Others' Changes)</para>
+ <para>Resolve Conflicts (Merge Others' Changes)</para>
<itemizedlist>
<listitem>
<para><command>svn update</command></para>
@@ -449,19 +440,19 @@
your last update by other developers on the project. Use
<command>svn update</command> to bring your working copy into
sync with the latest revision in the repository.</para>
-
+
<screen>
$ svn update
U foo.c
U bar.c
Updated to revision 2.
</screen>
-
+
<para>In this case, someone else checked in modifications to
both <filename>foo.c</filename> and <filename>bar.c</filename>
since the last time you updated, and Subversion has updated
your working copy to include those changes.</para>
-
+
<para>Let's examine the output of <command>svn update</command>
a bit more. When the server sends changes to your working
copy, a letter code is displayed next to each item to let you
@@ -496,7 +487,7 @@
copy.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><computeroutput>R foo</computeroutput></term>
<listitem>
@@ -541,28 +532,27 @@
<!-- =============================================================== -->
<sect2 id="svn.tour.cycle.edit">
<title>Make Changes to Your Working Copy</title>
-
- <para>Now you can get to work and make changes in your
- working copy. It's usually most convenient to decide on a
- particular change (or set of changes) to make, such as writing
- a new feature, fixing a bug, etc. The Subversion commands
- that you will use here are <command>svn add</command>,
- <command>svn delete</command>, <command>svn copy</command>,
- and <command>svn move</command>. However, if you are merely
+
+ <para>Now you can get to work and make changes in your working
+ copy. It's usually most convenient to decide on a discrete
+ change (or set of changes) to make, such as writing a new
+ feature, fixing a bug, etc. The Subversion commands that you
+ will use here are <command>svn add</command>, <command>svn
+ delete</command>, <command>svn copy</command>, and
+ <command>svn move</command>. However, if you are merely
editing files that are already in Subversion, you may not need
- to use any of these commands until you commit. Changes you can
- make to your working copy:</para>
-
+ to use any of these commands until you commit. Changes you
+ can make to your working copy:</para>
+
<variablelist>
-
+
<varlistentry>
<term>File changes</term>
<listitem>
<para>This is the simplest sort of change. You don't need
to tell Subversion that you intend to change a file;
- just make your changes. Subversion will be able to
- automatically detect which files have been
- changed.</para>
+ just make your changes. Subversion automatically detects
+ which files have been changed.</para>
</listitem>
</varlistentry>
@@ -579,7 +569,7 @@
</varlistentry>
</variablelist>
-
+
<para>To make file changes, use your text editor, word
processor, graphics program, or whatever tool you would
normally use. Subversion handles binary files just as easily
@@ -588,14 +578,13 @@
<para>Here is an overview of the four Subversion subcommands
that you'll use most often to make tree changes (we'll cover
- <command>svn import</command> and <command>svn mkdir</command>
- later).</para>
+ <command>svn mkdir</command> later).</para>
<sidebar>
<title>Versioning symbolic links</title>
- <para>On platforms which support them, Subversion is able to
- version files of the special type <firstterm>symbolic
+ <para>On non-Windows platforms, Subversion is able to version
+ files of the special type <firstterm>symbolic
link</firstterm> (or, <quote>symlink</quote>). A symlink is
a file which acts as a sort of transparent reference to some
other object in the filesystem, allowing programs to read
@@ -603,21 +592,20 @@
operations on the symlink itself.</para>
<para>When a symlink is committed into a Subversion
- repository, Subversion retains the fact that the file was in
- fact a symlink, as well as to what object the symlink
+ repository, Subversion remembers that the file was in fact a
+ symlink, as well as to what object the symlink
<quote>points</quote>. When that symlink is checked out to
another working copy on a supporting system, Subversion
reconstructs a real filesystem-level symbolic link from the
versioned symlink. But that doesn't in any way limit the
usability of working copies on systems such as Windows which
do not support symlinks. On such systems, Subversion simply
- constructs a regular text file whose contents are the path
- to which to the original symlink pointed. While that file
+ creates a regular text file whose contents are the path to
+ which to the original symlink pointed. While that file
can't be used as a symlink on a Windows system, it also
won't prevent Windows users from performing their other
- Subversion-related activities.</para>
- </sidebar>
-
+ Subversion-related activities.</para> </sidebar>
+
<warning>
<para>While you can edit your files with whatever tool you
like, you shouldn't change the structure of your working
@@ -627,9 +615,9 @@
to change the structure of your working copy, and use the
<command>svn add</command> command to place new files and
directories under version control.</para> </warning>
-
+
<variablelist>
-
+
<varlistentry>
<term><command>svn add foo</command></term>
<listitem>
@@ -663,7 +651,8 @@
<literal>HEAD</literal> of the repository. You can get
back anything you delete by checking out (or updating
your working copy) a revision earlier than the one in
- which you deleted it.</para></footnote></para>
+ which you deleted it. Also see <xref
+ linkend="svn.branchmerge.commonuses.resurrect"/>></para></footnote></para>
</listitem>
</varlistentry>
@@ -671,9 +660,9 @@
<term><command>svn copy foo bar</command></term>
<listitem>
<para>Create a new item <filename>bar</filename> as a
- duplicate of <filename>foo</filename>.
- <filename>bar</filename> is automatically scheduled for
- addition. When <filename>bar</filename> is added to the
+ duplicate of <filename>foo</filename> and automatically
+ schedule <filename>bar</filename> for addition.
+ When <filename>bar</filename> is added to the
repository on the next commit, its copy history is
recorded (as having originally come from
<filename>foo</filename>). <command>svn copy</command>
@@ -707,7 +696,7 @@
<!-- and which types of commands need URLs, etc. This should -->
<!-- probably be in chapter 2 (around the "Subversion in action" -->
<!-- though, so that this sidebar makes more sense. -->
-
+
<para>Earlier in this chapter, we said that you have to commit
any changes that you make in order for the repository to
reflect these changes. That's not entirely true—there
@@ -717,7 +706,9 @@
than on a working-copy path. In particular, specific uses
of <command>svn mkdir</command>, <command>svn
copy</command>, <command>svn move</command>, and
- <command>svn delete</command> can work with URLs.</para>
+ <command>svn delete</command> can work with URLs (And don't
+ forget that <command>svn import</command> always makes
+ changes to a URL).</para>
<para>URL operations behave in this manner because commands
that operate on a working copy can use the working copy as a
@@ -734,7 +725,7 @@
<!-- =============================================================== -->
<sect2 id="svn.tour.cycle.examine">
<title>Examine Your Changes</title>
-
+
<para>Once you've finished making changes, you need to commit
them to the repository, but before you do so, it's usually a
good idea to take a look at exactly what you've changed. By
@@ -754,11 +745,13 @@
<para>All three of these commands (<command>svn
status</command>, <command>svn diff</command>, and
<command>svn revert</command>) can be used without any
- network access (assuming, of course, that you're not using a
- local repository). This makes it easy to manage your
- changes-in-progress when you are somewhere without a network
- connection, such as travelling on an airplane, riding a
- commuter train or hacking on the beach.</para>
+ network access (assuming, of course, that your repository is
+ across the network and not local). This makes it easy to
+ manage your changes-in-progress when you are somewhere
+ without a network connection, such as travelling on an
+ airplane, riding a commuter train or hacking on the
+ beach.<footnote><para>And also that you don't have a WAN
+ card. Thought you got us, huh?</para></footnote></para>
<para>Subversion does this by keeping private caches of
pristine versions of each versioned file inside of the
@@ -785,18 +778,18 @@
Because of this, Subversion can quickly show you how your
working files have changed, or even allow you to undo your
changes without contacting the repository.</para>
-
+
<sect3 id="svn.tour.cycle.examine.status">
<title>See an overview of your changes</title>
-
+
<para>To get an overview of your changes, you'll use the
<command>svn status</command> command. You'll probably use
<command>svn status</command> more than any other Subversion
command.</para>
-
+
<sidebar>
<title>CVS Users: Hold That Update!</title>
-
+
<para>You're probably used to using <command>cvs
update</command> to see what changes you've made to your
working copy. <command>svn status</command> will give you
@@ -804,7 +797,7 @@
your working copy—without accessing the repository
or potentially incorporating new changes published by
other users.</para>
-
+
<para>In Subversion, <command>update</command> does just
that—it updates your working copy with any changes
committed to the repository since the last time you've
@@ -813,7 +806,7 @@
see what local modifications you've made.</para>
</sidebar>
-
+
<para>If you run <command>svn status</command> at the top of
your working copy with no arguments, it will detect all file
and tree changes you've made. Below are examples of
@@ -821,7 +814,7 @@
status</command> can return. (Note that the text following
<literal>#</literal> is not
actually printed by <command>svn status</command>.)</para>
-
+
<screen>
L some_dir # svn left a lock in the .svn area of some_dir
M bar.c # the content in bar.c has local modifications
@@ -839,13 +832,13 @@
C stuff/loot/glub.c # file has property conflicts from an update
R xyz.c # file is scheduled for replacement
S stuff/squawk # file or dir has been switched to a branch
- K dog.jpg # file is locked locally; lock-token present
+ K dog.jpg # file is locked locally; lock-token present
O cat.jpg # file is locked in the repository by other user
B bird.jpg # file is locked locally, but lock has been broken
T fish.jpg # file is locked locally, but lock has been stolen
</screen>
-
+
<para>In this output format <command>svn status</command>
prints six columns of characters, followed by several
whitespace characters, followed by a file or directory name.
@@ -990,8 +983,8 @@
state of conflict, which must be resolved before committing
the changes to the repository. Otherwise a whitespace will
be printed.</para>
-
- <para>The third column will only show whitespace or an
+
+ <para>The third column show either whitespace or an
<computeroutput>L</computeroutput> which means that
Subversion has locked the directory's
<filename>.svn</filename> working area. You will see an
@@ -1002,29 +995,28 @@
presumably Subversion was interrupted and the lock needs to
be cleaned up by running <command>svn cleanup</command>
(more about that later in this chapter).</para>
-
- <para>The fourth column will only show whitespace or a
+
+ <para>The fourth column will show either whitespace or a
<computeroutput>+</computeroutput> which means that the file
or directory is scheduled to be added or modified with
- additional attached history. This typically happens when you
- <command>svn move</command> or <command>svn copy</command> a file
- or directory. If you see
+ additional attached history. This typically happens when
+ you <command>svn move</command> or <command>svn
+ copy</command> a file or directory. If you see
<computeroutput>A +</computeroutput>, this means
- the item is scheduled for addition-with-history. It could be
- a file, or the root of a copied directory.
- <computeroutput>+</computeroutput>
- means the item is part of a subtree scheduled for
- addition-with-history, i.e. some parent got copied, and it's
- just coming along for the ride.
- <computeroutput>M +</computeroutput> means the item
- is part of a subtree scheduled for addition-with-history,
- <emphasis>and</emphasis> it has local modifications. When you
- commit, first the parent will be added-with-history (copied),
- which means this file will automatically exist in the copy.
- Then the local modifications will be uploaded into the
- copy.</para>
+ the item is scheduled for addition-with-history. It could
+ be a file, or the root of a copied directory.
+ <computeroutput>+</computeroutput> means the item is part of
+ a subtree scheduled for addition-with-history, i.e. some
+ parent got copied, and it's just coming along for the ride.
+ <computeroutput>M +</computeroutput> means the
+ item is part of a subtree scheduled for
+ addition-with-history, <emphasis>and</emphasis> it has local
+ modifications. When you commit, first the parent will be
+ added-with-history (copied) (which means this file will
+ automatically exist in the copy), and then the local
+ modifications will be applied to the copy.</para>
- <para>The fifth column will only show whitespace or an
+ <para>The fifth column will show either whitespace or an
<computeroutput>S</computeroutput>. This signifies that the
file or directory has been switched from the path of the
rest of the working copy (using <command>svn
@@ -1035,22 +1027,22 @@
(These are not the same locks as the ones indicated by an
<computeroutput>L</computeroutput> in the third column;
see <xref linkend="svn.advanced.locking.meanings"/>.)</para>
-
+
<para>If you pass a specific path to <command>svn
- status</command>, it gives you information about that item
+ status</command>, you get information about that item
alone:</para>
-
+
<screen>
$ svn status stuff/fish.c
D stuff/fish.c
</screen>
-
+
<para><command>svn status</command> also has a
<option>--verbose</option> (<option>-v</option>) switch,
which will show you the status of <emphasis>every</emphasis>
item in your working copy, even if it has not been
changed:</para>
-
+
<screen>
$ svn status --verbose
M 44 23 sally README
@@ -1063,12 +1055,14 @@
A 0 ? ? stuff/things/bloo.h
44 36 harry stuff/things/gloo.c
</screen>
-
+
<para>This is the <quote>long form</quote> output of
- <command>svn status</command>. The first column remains
- the same, but the second column shows the working-revision of
+ <command>svn status</command>. The first column remains the
+ same, but the second column shows the working-revision of
the item. The third and fourth columns show the revision in
- which the item last changed, and who changed it.</para>
+ which the item last changed, and who changed it (these
+ columns are not to be confused with the columns of
+ characters that we just discussed).</para>
<para>None of the above invocations to <command>svn
status</command> contact the repository, they work only
@@ -1078,7 +1072,7 @@
(<option>-u</option>) switch, which contacts the repository
and adds information about things that are
out-of-date:</para>
-
+
<screen>
$ svn status --show-updates --verbose
M * 44 23 sally README
@@ -1088,7 +1082,7 @@
A 0 ? ? stuff/things/bloo.h
Status against revision: 46
</screen>
-
+
<para>Notice the two asterisks: if you were to run
<command>svn update</command> at this point, you would
receive changes to <filename>README</filename>
@@ -1102,7 +1096,7 @@
<sect3 id="svn.tour.cycle.examine.diff">
<title>Examine the details of your local modifications</title>
-
+
<para>Another way to examine your changes is with the
<command>svn diff</command> command. You can find out
<emphasis>exactly</emphasis> how you've modified things by
@@ -1119,7 +1113,7 @@
might run <command>svn diff --diff-cmd /usr/bin/diff
--extensions '-bc' foo.c</command>.</para>
</footnote></para>
-
+
<screen>
$ svn diff
Index: bar.c
@@ -1143,7 +1137,7 @@
===================================================================
--- README (revision 3)
+++ README (working copy)
-@@ -193,3 +193,4 @@
+@@ -193,3 +193,4 @@
+Note to self: pick up laundry.
Index: stuff/fish.c
@@ -1160,7 +1154,7 @@
+Here is a new file to describe
+things about bloo.
</screen>
-
+
<para>The <command>svn diff</command> command produces this
output by comparing your working files against the cached
<quote>pristine</quote> copies within the
@@ -1198,15 +1192,15 @@
that your changes to <filename>README</filename> are a
mistake; perhaps you accidentally typed that text into the
wrong file in your editor.</para>
-
+
<para>This is a perfect opportunity to use <command>svn
revert</command>:</para>
-
+
<screen>
$ svn revert README
Reverted 'README'
</screen>
-
+
<para>Subversion reverts the file to its pre-modified state by
overwriting it with the cached <quote>pristine</quote> copy
from the <filename>.svn</filename> area. But also note that
@@ -1245,10 +1239,10 @@
control:</para>
<screen>
-$ svn status README
+$ svn status README
README
-$ svn delete README
+$ svn delete README
D README
$ svn revert README
@@ -1263,11 +1257,11 @@
<!-- =============================================================== -->
<sect2 id="svn.tour.cycle.resolve">
<title>Resolve Conflicts (Merging Others' Changes)</title>
-
+
<para>We've already seen how <command>svn status -u</command>
can predict conflicts. Suppose you run <command>svn
update</command> and some interesting things occur:</para>
-
+
<screen>
$ svn update
U INSTALL
@@ -1275,7 +1269,7 @@
C bar.c
Updated to revision 46.
</screen>
-
+
<para>The <computeroutput>U</computeroutput> and
<computeroutput>G</computeroutput> codes are no cause for
concern; those files cleanly absorbed changes from the
@@ -1287,15 +1281,15 @@
means that the file had local changes to begin with, but the
changes coming from the repository didn't overlap with the local
changes.</para>
-
+
<para>But the <computeroutput>C</computeroutput> stands for
conflict. This means that the changes from the server overlapped
with your own, and now you have to manually choose between
them.</para>
-
+
<para>Whenever a conflict occurs, three things typically occur
to assist you in noticing and resolving that conflict:</para>
-
+
<itemizedlist>
<listitem>
@@ -1305,8 +1299,8 @@
</listitem>
<listitem>
- <para>If Subversion considers the file to be of a mergeable
- type, it places <firstterm>conflict
+ <para>If Subversion considers the file to be mergeable,
+ it places <firstterm>conflict
markers</firstterm>—special strings of text which
delimit the <quote>sides</quote> of the
conflict—into the file to visibly demonstrate the
@@ -1321,21 +1315,20 @@
extra unversioned files in your working copy:</para>
<variablelist>
-
+
<varlistentry>
<term><filename>filename.mine</filename></term>
<listitem>
<para>This is your file as it existed in your working
copy before you updated your working copy—that
- is, without conflict markers. This file has your
- latest changes in it and nothing else. (If
- Subversion considers the file to be unmergeable,
- then the <filename>.mine</filename> file isn't
- created, since it would be identical to the working
- file.)</para>
+ is, without conflict markers. This file has only
+ your latest changes in it. (If Subversion considers
+ the file to be unmergeable, then the
+ <filename>.mine</filename> file isn't created, since
+ it would be identical to the working file.)</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><filename>filename.rOLDREV</filename></term>
<listitem>
@@ -1359,21 +1352,21 @@
</varlistentry>
</variablelist>
-
+
<para>Here <literal>OLDREV</literal> is the revision number
of the file in your <filename>.svn</filename> directory
and <literal>NEWREV</literal> is the revision number of
the repository <literal>HEAD</literal>.</para>
</listitem>
-
+
</itemizedlist>
-
+
<para>For example, Sally makes changes to the file
<filename>sandwich.txt</filename> in the repository. Harry has
just changed the file in his working copy and checked it in.
Sally updates her working copy before checking in and she gets
a conflict:</para>
-
+
<screen>
$ svn update
C sandwich.txt
@@ -1384,7 +1377,7 @@
sandwich.txt.r1
sandwich.txt.r2
</screen>
-
+
<para>At this point, Subversion will <emphasis>not</emphasis>
allow you to commit the file <filename>sandwich.txt</filename>
until the three temporary files are removed.</para>
@@ -1443,7 +1436,7 @@
Sally, your collaborator, both edit the file
<filename>sandwich.txt</filename> at the same time. Sally
commits her changes, and when you go to update your working
- copy, you get a conflict and we're going to have to edit
+ copy, you get a conflict and you're going to have to edit
<filename>sandwich.txt</filename> to resolve the conflicts.
First, let's take a look at the file:</para>
@@ -1531,7 +1524,7 @@
you've fixed the conflict in your file—once the
temporary files are removed, Subversion will let you commit
the file even if it still contains conflict markers.</para>
-
+
<para>If you ever get confused while editing the conflicted
file, you can always consult the three files that Subversion
creates for you in your working copy—including your
@@ -1581,15 +1574,15 @@
</sect3>
</sect2>
-
+
<!-- =============================================================== -->
<sect2 id="svn.tour.cycle.commit">
<title>Commit Your Changes</title>
-
+
<para>Finally! Your edits are finished, you've merged all
changes from the server, and you're ready to commit your
changes to the repository.</para>
-
+
<para>The <command>svn commit</command> command sends all of
your changes to the repository. When you commit a change, you
need to supply a <firstterm>log message</firstterm>,
@@ -1598,21 +1591,21 @@
you may wish to supply it on the command line using the
<option>--message</option> (or <option>-m</option>)
option:</para>
-
+
<screen>
$ svn commit --message "Corrected number of cheese slices."
Sending sandwich.txt
Transmitting file data .
Committed revision 3.
</screen>
-
+
<para>However, if you've been composing your log message as you
work, you may want to tell Subversion to get the message from
a file by passing the filename with the
- <option>--file</option> switch:</para>
+ <option>--file</option> (<option>-F</option>) switch:</para>
<screen>
-$ svn commit --file logmsg
+$ svn commit --file logmsg
Sending sandwich.txt
Transmitting file data .
Committed revision 4.
@@ -1624,14 +1617,14 @@
(see the <literal>editor-cmd</literal> section in
<xref linkend="svn.advanced.confarea.opts.config"/>) for composing a log
message.</para>
-
-
+
+
<tip>
<para>If you're in your editor writing a commit message and
decide that you want to cancel your commit, you can just
quit your editor without saving changes. If you've already
- saved your commit message, simply delete the text and save
- again.</para>
+ saved your commit message, simply delete the text, save
+ again, then quit.</para>
<screen>
$ svn commit
@@ -1655,19 +1648,21 @@
$ svn commit --message "Add another rule"
Sending rules.txt
svn: Commit failed (details follow):
-svn: Out of date: 'rules.txt' in transaction 'g'
+svn: Your file or directory 'sandwich.txt' is probably out-of-date
+…
</screen>
<para>At this point, you need to run <command>svn
update</command>, deal with any merges or conflicts that
result, and attempt your commit again.</para>
-
<para>That covers the basic work cycle for using Subversion.
There are many other features in Subversion that you can use
- to manage your repository and working copy, but you can get by
- quite easily using only the commands that we've discussed so
- far in this chapter.</para>
+ to manage your repository and working copy, but most of your
+ day-to-day use of Subversion will involve only the commands
+ that we've discussed so far in this chapter. We will,
+ however, cover a few more commands that you'll use just fairly
+ often.</para>
</sect2>
@@ -1679,17 +1674,16 @@
<sect1 id="svn.tour.history">
<title>Examining History</title>
- <para>As we mentioned earlier, the repository is like a time
- machine. It keeps a record of every change ever committed,
- and allows you to explore this history by examining previous
- versions of files and directories as well as the metadata that
- accompanies them. With a single Subversion command, you can
- check out the repository (or restore an existing working copy)
- exactly as it was at any date or revision number in the past.
- However, sometimes you just want to <emphasis>peer
- into</emphasis> the past instead of <emphasis>going
- into</emphasis> the past.</para>
-
+ <para>Your Subversion repository is like a time machine. It keeps
+ a record of every change ever committed, and allows you to
+ explore this history by examining previous versions of files and
+ directories as well as the metadata that accompanies them. With
+ a single Subversion command, you can check out the repository
+ (or restore an existing working copy) exactly as it was at any
+ date or revision number in the past. However, sometimes you
+ just want to <emphasis>peer into</emphasis> the past instead of
+ <emphasis>going into</emphasis> the past.</para>
+
<para>There are several commands that can provide you with
historical data from the repository:</para>
@@ -1743,7 +1737,7 @@
revision it changed, the time and date of that revision, and,
if it was provided, the log message that accompanied the
commit.</para>
-
+
<screen>
$ svn log
------------------------------------------------------------------------
@@ -1760,36 +1754,36 @@
Initial import
------------------------------------------------------------------------
</screen>
-
+
<para>Note that the log messages are printed in
<emphasis>reverse chronological order</emphasis> by default.
If you wish to see a different range of revisions in a
particular order, or just a single revision, pass the
<option>--revision</option> (<option>-r</option>)
switch:</para>
-
+
<screen>
$ svn log --revision 5:19 # shows logs 5 through 19 in chronological order
-$ svn log -r 19:5 # shows logs 5 through 19 in reverse order
+$ svn log --revision 19:5 # shows logs 5 through 19 in reverse order
-$ svn log -r 8 # shows log for revision 8
+$ svn log --revision 8 # shows log for revision 8
</screen>
-
+
<para>You can also examine the log history of a single file or
directory. For example:</para>
-
+
<screen>
$ svn log foo.c
…
$ svn log http://foo.com/svn/trunk/code/foo.c
…
</screen>
-
+
<para>These will display log messages <emphasis>only</emphasis>
for those revisions in which the working file (or URL)
changed.</para>
-
+
<para>If you want even more information about a file or
directory, <command>svn log</command> also takes a
<option>--verbose</option> (<option>-v</option>) switch.
@@ -1800,7 +1794,7 @@
revision in its output:</para>
<screen>
-$ svn log -r 8 -v
+$ svn log --revision 8 --verbose
------------------------------------------------------------------------
r8 | sally | 2002-07-14 08:15:29 -0500 | 1 line
Changed paths:
@@ -1822,7 +1816,7 @@
<sidebar>
<title>Why Does <command>svn log</command> Give Me an Empty
Response?</title>
-
+
<para>After working with Subversion for a bit, most users will
come across something like this:</para>
@@ -1846,7 +1840,7 @@
http://svn.collab.net/repos/svn</command>.</para>
</sidebar>
-
+
</sect2>
<!-- =============================================================== -->
@@ -1857,7 +1851,7 @@
before—it displays file differences in unified diff
format; it was used to show the local modifications made to
our working copy before committing to the repository.</para>
-
+
<para>In fact, it turns out that there are
<emphasis>three</emphasis> distinct uses of <command>svn
diff</command>:</para>
@@ -1877,7 +1871,7 @@
</listitem>
</itemizedlist>
-
+
<sect3 id="svn.tour.history.diff.local">
<title>Examining Local Changes</title>
@@ -1885,7 +1879,7 @@
no switches will compare your working files to the cached
<quote>pristine</quote> copies in
the <filename>.svn</filename> area:</para>
-
+
<screen>
$ svn diff
Index: rules.txt
@@ -1901,7 +1895,7 @@
+Listen when others are speaking
$
</screen>
-
+
</sect3>
<sect3 id="svn.tour.history.diff.wcrepos">
@@ -1911,9 +1905,9 @@
(<option>-r</option>) number is passed, then your
working copy is compared to the specified revision in the
repository.</para>
-
+
<screen>
-$ svn diff --revision 3 rules.txt
+$ svn diff --revision 3 rules.txt
Index: rules.txt
===================================================================
--- rules.txt (revision 3)
@@ -1927,19 +1921,19 @@
+Listen when others are speaking
$
</screen>
-
+
</sect3>
<sect3 id="svn.tour.history.diff.reposrepos">
<title>Comparing Repository to Repository</title>
-
+
<para>If two revision numbers, separated by a colon, are
passed via <option>--revision</option>
(<option>-r</option>), then the two revisions are directly
compared.</para>
-
+
<screen>
-$ svn diff --revision 2:3 rules.txt
+$ svn diff --revision 2:3 rules.txt
Index: rules.txt
===================================================================
--- rules.txt (revision 2)
@@ -1952,7 +1946,7 @@
Chew with your mouth open
$
</screen>
-
+
<para>Not only can you use <command>svn diff</command> to
compare files in your working copy to the repository, but if
you supply a URL argument, you can examine the differences
@@ -1960,9 +1954,9 @@
working copy. This is especially useful if you wish to
inspect changes in a file when you don't have a working copy
on your local machine:</para>
-
+
<screen>
-$ svn diff --revision 4:5 http://svn.red-bean.com/repos/example/trunk/text/rules.txt
+$ svn diff --revision 4:5 http://svn.example.com/repos/example/trunk/text/rules.txt
…
$
</screen>
@@ -1990,7 +1984,7 @@
<command>svn cat</command>:</para>
<screen>
-$ svn cat --revision 2 rules.txt
+$ svn cat --revision 2 rules.txt
Be kind to others
Freedom = Chocolate Ice Cream
Everything in moderation
@@ -2027,11 +2021,11 @@
<sect3 id="svn.tour.history.browsing.list">
<title><command>svn list</command></title>
-
+
<para>The <command>svn list</command> command shows you what
files are in a repository directory without actually
downloading the files to your local machine:</para>
-
+
<screen>
$ svn list http://svn.collab.net/repos/svn
README
@@ -2047,18 +2041,18 @@
<screen>
$ svn list --verbose http://svn.collab.net/repos/svn
- 2755 harry 1331 Jul 28 02:07 README
- 2773 sally Jul 29 15:07 branches/
- 2769 sally Jul 29 12:07 clients/
- 2698 harry Jul 24 18:07 tags/
- 2785 sally Jul 29 19:07 trunk/
+ 20620 harry 1084 Jul 13 2006 README
+ 23339 harry Feb 04 01:40 branches/
+ 21282 sally Aug 27 09:41 developer-resources/
+ 23198 harry Jan 23 17:17 tags/
+ 23351 sally Feb 05 13:26 trunk/
</screen>
<para>The columns tell you the revision at which the file or
directory was last modified, the user who modified it, the size
if it is a file, the date it was last modified, and the item's
name.</para>
-
+
</sect3>
</sect2>
@@ -2136,7 +2130,7 @@
<screen>
$ svn status
L somedir
-M somedir/foo.c
+M somedir/foo.c
$ svn cleanup
$ svn status
@@ -2157,7 +2151,7 @@
<!-- ================================================================= -->
<sect1 id="svn.tour.summary">
<title>Summary</title>
-
+
<para>Now we've covered most of the Subversion client commands.
Notable exceptions are those dealing with branching and
merging (see <xref linkend="svn.branchmerge"/>) and properties (see
@@ -2172,7 +2166,7 @@
</chapter>
<!--
-local variables:
+local variables:
sgml-parent-document: ("book.xml" "chapter")
end:
-->
More information about the svnbook-dev
mailing list