Index: ch03.xml
===================================================================
--- ch03.xml (revision 6740)
+++ ch03.xml (working copy)
@@ -3,14 +3,14 @@
<simplesect>
- <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 an initial checkout of
+ <para>Now we will go into the details of using Subversion. By the
+ end of this chapter, you should be able to
+ perform almost all the tasks you will need to use Subversion in a
+ normal day's work. We'll start with an initial checkout of
your code, and walk 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>
+ into your working copy, examine them, and resolve any
+ conflicts between their changes and your own.</para>
<para>Note that this chapter is not meant to be an exhaustive list
of all Subversion's commands—rather, it's a conversational
@@ -32,7 +32,7 @@
<para>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 tries to be
- self-documenting—at any time, a quick <command>svn help
+ self-documenting— a quick <command>svn help
<subcommand></command> will describe the syntax, switches,
and behavior of the <command>subcommand</command>.</para>
@@ -67,20 +67,20 @@
in time. As you continue to commit and grow your repository,
you need a mechanism for identifying these snapshots.</para>
- <para>You specify these revisions by using the
+ <para>You specify a revision by using the
<option>--revision</option> (<option>-r</option>) switch plus
the revision you want (<command>svn --revision REV</command>) or
you can specify a range by separating two revisions with a colon
(<command>svn --revision REV1:REV2</command>). And Subversion
lets you refer to these revisions by number, keyword, or
- date.</para>
+ date/time.</para>
<sect2 id="svn-ch-3-sect-3.1">
<title>Revision Numbers</title>
<para>When you create a new Subversion repository, it begins its
life at revision zero and each successive commit increases the
- revision number by one. After your commit completes, the
+ repository's revision number by one. After a commit is
completed, the
Subversion client informs you of the new revision
number:</para>
@@ -92,7 +92,7 @@
</screen>
<para>If at any point in the future you want to refer to that
- revision (We'll see how and why we might want to do that later
+ revision (we'll see how and why we might want to do that later
in this chapter), you can refer to it as
<quote>3</quote>.</para>
@@ -110,12 +110,12 @@
<note>
<para>Each directory in your working copy contains an
<filename>.svn</filename> administrative area. For every file
- in a directory, Subversion keeps a copy of each file in the
+ in a directory, Subversion keeps a copy of it in the
administrative area. This copy is an unmodified (no keyword
expansion, no end-of-line translation, no nothing) copy of the
- file as it existed in the last revision (called the
- <quote>BASE</quote> revision) that you updated it to in your
- working copy. We refer to this file as a
+ file as it existed in the last revision that you used to update
your
+ working copy (called the <quote>BASE</quote> revision of the
file).
+ We refer to this file as a
<quote>pristine</quote> copy.</para>
</note>
@@ -275,11 +275,11 @@
<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. <quote>Checking out</quote> 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>
+ repository by first doing a <firstterm>checkout</firstterm> of
your
+ project. <quote>Checking out</quote> a project creates a
+ working copy of it on your local machine. This is a copy of the
+ <literal>HEAD</literal> (latest revision) of the repository
subtree
+ specified on the command line:</para>
<screen>
@@ -298,14 +298,14 @@
<para>If you're wondering what <literal>trunk</literal> is all
about in the above URL, it's part of the way we recommend
- you lay out your Subversion repository which we'll talk a lot
+ you lay out your Subversion repository, which we'll talk a lot
more about in <xref linkend="svn-ch-4"/>.</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
+ <para>The above example checks out the trunk directory, but
+ you can just as easily check out any subdirectory deep within a
+ repository by specifying the subdirectory path in the checkout
URL:</para>
<screen>
@@ -330,9 +330,8 @@
like any other collection of files and/or directories on your
system<footnote><para>Well, except for the fact that every
directory within your <quote>working copy</quote>also contains a
- <filename>.svn</filename> subdirectory. But that's getting a
- little ahead of ourselves.</para></footnote>. You can edit and
- change them, move them around, you can even delete the entire
+ <filename>.svn</filename> subdirectory.</para></footnote>.
+ You can edit them, move them around, you can even delete the
entire
working copy and forget about it.</para>
<note>
@@ -343,14 +342,14 @@
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>
+ provided by your operating system, or else the changes
+ will not get reflected in the repository. We'll talk more
about
+ this topic later in this chapter.</para>
</note>
- <para>Unless you're ready to <firstterm>commit</firstterm> a new
- file or directory, or changes to existing ones, there's no need
- to further notify the Subversion server that you've done
- anything.</para>
+ <para>Until you're ready to <firstterm>commit</firstterm> a newly
+ added file or directory (or changes you've made to existing files
or directories),
+ there's no need to notify Subversion of your activities.</para>
<sidebar>
<title>What's with the <filename>.svn</filename>
directory?</title>
@@ -365,10 +364,13 @@
</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 into the new directory that you name. For example:</para>
+ <para>If you check out a working copy by specifying the
+ repository URL as the only argument, then the last element of the
URL
+ (i.e., the last subdirectory name in the URL path) will be
+ the directory name into which the working copy is placed.
+ Optionally, you can supply a different directory name or path
following the URL,
+ which will place your working copy into that directory instead.
+ For example:</para>
<screen>
$ svn checkout http://svn.collab.net/repos/svn/trunk subv
@@ -381,9 +383,10 @@
Checked out revision 2499.
</screen>
- <para>That will place your working copy in a directory named
+ <para>This example places our working copy in a directory named
<literal>subv</literal> instead of a directory named
- <literal>trunk</literal> as we did previously.</para>
+ <literal>trunk</literal> (as would happen if no path
+ was supplied after the URL).</para>
</sect1>
@@ -489,10 +492,9 @@
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
- know what actions Subversion performed to bring your working
- copy up-to-date:</para>
+ more closely. The <command>update</command> command
+ prints a line for each item that is updated; each line begins
+ with a letter code that describes the action Subversion
performed to bring the item up-to-date:</para>
<variablelist>
@@ -529,8 +531,8 @@
<para>File or directory <filename>foo</filename> was
<computeroutput>R</computeroutput>eplaced in your working
copy; that is, <filename>foo</filename> was deleted, and
a
- new item with the same name was added. While they may
have
- the same name, the repository considers them to be
distinct
+ new item with the same name was added. While they may
share
+ the same name, within the repository they are actually
distinct
objects with distinct histories.</para>
</listitem>
</varlistentry>
@@ -540,21 +542,22 @@
<listitem>
<para>File <filename>foo</filename> received new changes
from the repository, but your local copy of the file had
- your modifications. The changes did not intersect,
- however, so Subversion has
+ your modifications. In this case the changes did not
conflict,
+ so Subversion successfully
mer<computeroutput>G</computeroutput>ed the repository's
- changes into the file without a problem.</para>
+ changes and yours into your local copy.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>C foo</computeroutput></term>
<listitem>
- <para>File <filename>foo</filename> received
- <computeroutput>C</computeroutput>onflicting changes from
- the server. The changes from the server directly overlap
- your own changes to the file. No need to panic, though.
- This overlap needs to be resolved by a human (you); we
+ <para>File <filename>foo</filename> received new changes
+ from the repository, but those changes
+ <computeroutput>C</computeroutput>onflicted with changes
+ you made to your local copy; therefore Subversion was not
+ able to automatically merge them. No need to panic,
though.
+ This conflict simply needs to be resolved by a human
(you); we
discuss this situation later in this chapter.</para>
</listitem>
</varlistentry>
@@ -569,13 +572,15 @@
<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
+ a new feature, fixing a bug, etc.
+ <!-- ###mblais: I don't understand the point of the previous
sentence -->
+ 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 a file (or files) that is already in Subversion, you
+ 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>
+ There are two kinds of changes you can make to your working
copy:</para>
<variablelist>
@@ -584,7 +589,7 @@
<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
+ just make your changes. Subversion can
automatically detect which files have been
changed.</para>
</listitem>
@@ -595,8 +600,8 @@
<listitem>
<para>You can ask Subversion to <quote>mark</quote> files
and directories for scheduled removal, addition,
- copying, or moving. While these changes may take place
- immediately in your working copy, no additions or
+ copying, or moving. These changes take place
+ immediately in your working copy, but no additions or
removals will happen in the repository until you commit
them.</para>
</listitem>
@@ -607,7 +612,7 @@
<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
- as it handles text files—and just as efficiently
+ as it handles text files—and just as efficiently,
too.</para>
<para>Here is an overview of the four Subversion subcommands
@@ -623,12 +628,12 @@
<para>Schedule <filename>foo</filename> to be added to the
repository. When you next commit,
<filename>foo</filename> will become a child of its
- parent directory. Note that if <filename>foo</filename>
- is a directory, everything underneath
<filename>foo</filename>
- will be scheduled for addition. If you only want to
- schedule <filename>foo</filename> itself, pass the
+ parent directory within the repository. Note that if
<filename>foo</filename>
+ is a directory, then by default all of
<filename>foo</filename>'s contents
+ are scheduled for addition as well. If you only want to
+ add <filename>foo</filename>, and none of its children,
specify the
<option>--nonrecursive</option> (<option>-N</option>)
- switch.</para>
+ switch to the <command>add</command> command.</para>
</listitem>
</varlistentry>
@@ -642,11 +647,21 @@
deleted, but Subversion schedules it for deletion. When
you commit your changes, <filename>foo</filename> will
be removed from your working copy and the repository.
- <footnote><para>Of course, nothing is ever totally
- deleted from the repository—just from the HEAD 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>
+<!-- ###mblais: This description of 'svn delete' differs quite a bit
from the
+'svn HELP delete' description -- might want to adjust this:
+ svn help delete:
+ If run on a working copy PATHs, each item is scheduled for
deletion
+ upon the next commit. Files, and directories that have not
been
+ committed, are immediately removed from the working copy. The
+ command will not remove PATHs that are, or contain, unversioned
+ or modified items; use the --force option to override this
+ behavior.
+-->
+ <footnote><para>Of course, nothing is ever
<emphasis>actually
+ deleted</emphasis> from the repository—just from
the HEAD of
+ the repository. You can recover any deleted item by
+ checking out (or updating your working copy to) a
revision
+ earlier than the one in which the deletion was
committed.</para>
</footnote></para>
</listitem>
</varlistentry>
@@ -684,7 +699,7 @@
<!-- pll - Fri 07 Feb 2003 12:55:07
-->
<!-- I find this sidebar rather confusing here, since you
really -->
<!-- haven't gone through explaining the svn command line
syntax -->
- <!-- anywhere. Maybe a short section explaining that
subversion -->
+ <!-- anywhere. Maybe a short section explaining that
Subversion -->
<!-- can be used both in networked and non-networked
environments, -->
<!-- and which types of commands need URLs, etc. This should
-->
<!-- probably be in chapter 2 (around the "Subversion in
action" -->
@@ -716,21 +731,20 @@
<sect2 id="svn-ch-3-sect-4.3">
<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
+ <para>Once you've finished making changes, you are almost ready
to commit
+ them to the repository. But before you do, it's usually a
good idea to take a look at exactly what you've changed. By
- examining your changes before you commit, you cannot only
- make a more accurate log message, but you may discover that
+ examining your changes before you commit, you can not only
+ compose a more accurate log message, but you may also discover
that
you've inadvertently changed a file, and this gives you a
chance to revert those changes before committing.
- Additionally, this is a good opportunity to review and
- scrutinize changes before publishing them. You can see
- exactly what changes you've made by using <command>svn
- status</command>, <command>svn diff</command>, and
- <command>svn revert</command>. You will usually use the first
- two commands to find out what files have changed in your
- working copy, and then perhaps the third to revert some (or
- all) of those changes.</para>
+ Additionally, it's always a good idea to review and
+ scrutinize your changes before publishing them. </para>
+
+ <para>You can see exactly what changes you've made by using
<command>svn
+ status</command>, <command>svn diff</command>.
+ If you need to revert some (or all) of your changes,
+ use the <command>svn revert</command>.</para>
<!-- pll - Fri 07 Feb 2003 12:55:07
-->
<!-- I find this following paragraph a little unclear. Mostly
for -->
@@ -768,7 +782,7 @@
<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
- updated your working copy. You'll have to break the habit
+ updated your working copy. Try to break the habit
of using the <command>update</command> command to see what
local modifications you've made.</para>
@@ -788,14 +802,17 @@
M ./bar.c # the content in bar.c has local
modifications
M ./baz.c # baz.c has property but no content
modifications
? ./foo.o # svn doesn't manage foo.o
-! ./some_dir # svn manages this, but it's either
missing or incomplete
-~ ./qux # versioned as dir, but is file, or vice
versa
+! ./some_dir # svn manages some_dir, but it's either
missing or incomplete
+~ ./qux # versioned as dir, but is a file, or vice
versa
A + ./moved_dir # added with history of where it came from
M + ./moved_dir/README # added with history and has local
modifications
D ./stuff/fish.c # this file is scheduled for deletion
A ./stuff/loot/bloo.h # this file is scheduled for addition
C ./stuff/loot/lump.c # this file has conflicts from an update
S ./stuff/squawk # this file or dir has been switched to a
branch
+
+ <!-- ###mblais: What about 'I' in 1st col? What does that
mean? -->
+
</screen>
<para>In this output format <command>svn status</command>
@@ -901,6 +918,8 @@
repository.</para>
</listitem>
</varlistentry>
+
+ <!-- ###mblais: What about 'I' in 1st col? What does that
mean? -->
</variablelist>
@@ -948,7 +967,7 @@
<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
- switch</command>) to a branch.</para>
+ switch</command>) to a different location in the
repository.</para>
<para>If you pass a specific path to <command>svn
status</command>, it gives you information about that item
@@ -985,12 +1004,12 @@
which the item last changed, and who changed it.</para>
<para>None of the above invocations to <command>svn
- status</command> contact the repository, they work only
+ status</command> contact the repository; they work only
locally by comparing the metadata in the
<filename>.svn</filename> directory with the working copy.
Finally, there is the <option>--show-updates</option>
(<option>-u</option>) switch, which contacts the repository
- and adds information about things that are
+ and adds information about items that are
<firstterm>out-of-date</firstterm>:</para>
<screen>
@@ -1009,7 +1028,7 @@
useful information—you'll need to update and get the
server changes on <filename>README</filename> before you
commit, or the repository will reject your commit for being
- out-of-date. (More on this subject later).</para>
+ out-of-date (we'll cover this situation in more detail
later).</para>
</sect3>
@@ -1022,7 +1041,7 @@
running <command>svn diff</command> with no arguments, which
prints out file changes in unified diff
format:<footnote><para>Subversion uses its internal diff
- engine, which produces unified diff format, by default. If
+ engine, which produces unified diff format by default. If
you want diff output in a different format, specify an
external diff program using <option>--diff-cmd</option> and
pass any flags you'd like to it using the
@@ -1033,6 +1052,9 @@
--extensions '-bc' foo.c</quote>.</para>
</footnote></para>
+ <!-- ###mblais: "--diff-cmd" doesn't work for me (using Araxis
Merge on WinXP) -->
+ <!-- Can someone document how it is invoked ? -->
+
<screen>
$ svn diff
Index: ./bar.c
@@ -1179,9 +1201,9 @@
connection such as traveling on an airplane, riding a
commuter train or hacking on the beach.</para>
- <para>Subversion does this by keeping private caches of
- pristine versions of each versioned file inside of the
- <filename>.svn</filename> administrative areas. This allows
+ <para>Subversion does this by keeping a private cache of
+ the pristine version of each versioned file inside the
+ <filename>.svn</filename> administrative area. This allows
Subversion to report—and revert—local
modifications to those files <emphasis>without network
access</emphasis>. This cache (called the "text-base") also
@@ -1220,17 +1242,17 @@
but were <computeroutput>U</computeroutput>pdated with changes
from the repository. The <computeroutput>G</computeroutput>
stands for mer<computeroutput>G</computeroutput>ed, which
- means that the file had local changes to begin with, but the
+ means that the file had local changes to begin with, but
because the
changes coming from the repository didn't overlap in any
- way.</para>
+ way, Subversion was able to automatically merge them with the
+ local changes in the working copy.</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
+ <emphasis>conflict</emphasis>. This means that the changes
from the server overlapped
+ with your own, and you will have to manually resolve
them.</para>
- <para>Whenever a conflict occurs, your Subversion client does
- the three things:</para>
+ <para>Whenever a conflict occurs, your Subversion client does
three things:</para>
<itemizedlist>
@@ -1248,7 +1270,7 @@
<listitem>
<para>For every conflicted file, Subversion places three
- extra files in your working copy:</para>
+ extra files into your working copy:</para>
<variablelist>
@@ -1257,7 +1279,7 @@
<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
+ is, without any conflict markers. This file has your
latest changes in it and nothing else.</para>
</listitem>
</varlistentry>
@@ -1277,28 +1299,28 @@
<listitem>
<para>This is the file that your Subversion client
just received from the server when you updated your
- working copy. This file corresponds to the HEAD
- revision of the repository.</para>
+ working copy; it is the current HEAD
+ revision of the file in the repository.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Here <literal>*</literal> represents some random
- digits that Subversion chooses,
+ digits that Subversion chooses, <!-- ###mblais: Not in the
example below...? -->
<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 HEAD.
+ current repository HEAD.
</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
+ <filename>sandwich.txt</filename> in her working copy. Harry
has also
+ just changed <filename>sandwich.txt</filename> in his working
copy and checked it in.
+ Before committing her changes, Sally updates her working copy
and Subversion reports
a conflict:</para>
<screen>
@@ -1315,8 +1337,8 @@
<!-- ###TODO What happens if the revnum is gt 99999?-->
<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>
+ allow Sally to commit the file
<filename>sandwich.txt</filename>
+ until the conflict is resolved and the three temporary files
are removed.</para>
<screen>
$ svn commit --message "Add a few more things"
@@ -1340,8 +1362,7 @@
</listitem>
<listitem>
- <para>Copy one of the temporary files on top of your
- working file.
+ <para>Copy one of the temporary files over your working
file.
</para>
</listitem>
@@ -1369,17 +1390,17 @@
<sect3 id="svn-ch-3-sect-4.4.1">
<title>Merging Conflicts by Hand</title>
- <para>Merging conflicts by hand can be quite intimidating the
- first time you attempt it, but with a little practice, it
+ <para>Merging conflicts by hand can be a little intimidating
the
+ first time you try it, but with a little practice it
can become as easy as falling off a bike.</para>
<para>Here's an example. Let's say that, due to a
miscommunication between you and your collaborator, Sally,
- both edit the file named <filename>sandwich.txt</filename>
+ you both edit the same part of
<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 <filename>sandwich.txt</filename> to
- resolve the conflicts. First, let's take a look at the
+ update your working copy, you get a conflict. You'll
+ need to edit <filename>sandwich.txt</filename> to
+ resolve the conflict. First, let's take a look at the
file:</para>
<screen>
@@ -1428,12 +1449,14 @@
<para>Usually you won't want to just delete the conflict
markers and Sally's changes—she's going to be awfully
surprised when the sandwich arrives and it's not what she
- wanted. So this is where you pick up the phone or walk across
+ wanted
+ (i.e., when she updates again and notices that her edits are
all gone).
+ So this is where you pick up the phone or walk across
the office and explain to Sally that you can't get sauerkraut
from an Italian deli.<footnote><para>And if you ask them for
it, they may very well ride you out of town on a
rail</para></footnote> Once you've agreed on the changes you
- will check in, edit your file and remove the conflict
markers.</para>
+ will check in, you edit your file appropriately and remove the
conflict markers.</para>
<screen>
Top piece of bread
@@ -1448,7 +1471,7 @@
Bottom piece of bread
</screen>
- <para>Now run <command>svn resolved</command> and you're now
+ <para>Then run <command>svn resolved</command> and you're now
ready to commit your changes:</para>
<screen>
@@ -1499,15 +1522,17 @@
sandwich.txt
</screen>
- <para>Note that when you revert a conflicted file, you don't
- have to run <command>svn resolved</command>.</para>
+ <para>Note that when you revert a conflicted file
+ using <command>svn revert</command>, you don't
+ have to run <command>svn resolved</command>; this is done
+ for you automatically.</para>
</sect3>
<para>Now you're ready to check in your changes. Note that
- <command>svn resolved</command>, unlike most of the other
+ <command>svn resolved</command>, unlike many of the other
commands we've dealt with in this chapter, requires an
- argument. In any case, you want to be careful and only run
+ argument. In any case, you want to be careful to only run
<command>svn resolved</command> when you're certain that you've
fixed the conflict in your file—once the temporary files
are removed, Subversion will let you commit the file even if
@@ -1524,7 +1549,7 @@
<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>,
+ you must supply a <firstterm>log message</firstterm>,
describing your change. Your log message will be attached
to the new revision you create. If your log message is
brief, you may wish to supply it on the command line using
@@ -1554,8 +1579,9 @@
<option>--message</option> or <option>--file</option> switch,
then Subversion will automatically launch your favorite editor
(as defined in the environment variable
- <literal>$EDITOR</literal>) for composing a log
- message.</para>
+ <literal>$EDITOR</literal>) for you to compose the log
+ message. After you save your log message and exit the editor,
+ Subversion commits your file.</para>
<tip>
@@ -1576,7 +1602,7 @@
<para>The repository doesn't know or care if your changes make
any sense as a whole; it only checks to make sure that nobody
- else has changed any of the same files that you did when you
+ else changed any of the same files when you
weren't looking. If somebody <emphasis>has</emphasis> done
that, the entire commit will fail with a message informing you
that one or more of your files is out-of-date:</para>
@@ -1592,9 +1618,9 @@
$
</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>If this happens you will need to run <command>svn
+ update</command>, deal appropriately with any merges or
conflicts that
+ result, and then attempt your commit again.</para>
<para>That covers the basic work cycle for using Subversion.
@@ -1605,8 +1631,7 @@
</sect2>
- </sect1
->
+ </sect1>
<!--
================================================================= -->
<!-- ======================== SECTION 6
============================== -->
@@ -1617,10 +1642,10 @@
<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 (or restore an existing working copy) the repository
- exactly as it was at any date or revision number in the past.
+ versions of files and directories as well as the metadata
(properties)
+ associated with them. With a single Subversion command, you can
+ check out (or restore an existing working copy to) a snapshot of
the repository
+ 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>
@@ -1642,8 +1667,8 @@
<varlistentry>
<term><command>svn diff </command></term>
<listitem>
- <para>Shows you the specific details of how a file changed
- over time.</para>
+ <para>Shows you the specific details of how a file or
directory changed
+ between any two revisions.</para>
</listitem>
</varlistentry>
@@ -1659,8 +1684,8 @@
<varlistentry>
<term><command>svn list </command></term>
<listitem>
- <para>Displays the files in a directory for any given
- revision.</para>
+ <para>Lists the contents of a repository directory
+ as it existed at a specific revision.</para>
</listitem>
</varlistentry>
@@ -1673,10 +1698,9 @@
<para>To find out information about the history of a file or
directory, use the <command>svn log</command>
command. <command>svn log</command> will provide you with a
- record of who made changes to a file or directory, at what
- revision it changed, the time and date of that revision, and,
- if it was provided, the log message that accompanied the
- commit.</para>
+ record of who made changes to a file or directory, at which
+ revision numbers it was changed (committed), and the time,
date, and log
+ message associated with each commit.</para>
<screen>
$ svn log
@@ -1698,16 +1722,16 @@
<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
+ particular order, or just a single revision, use 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 --revision 5:19 # shows all logs for revisions 5 through
19 in chronological order
-$ svn log -r 19:5 # shows logs 5 through 19 in reverse order
+$ svn log -r 19:5 # shows all logs for revisions 5 through
19 in reverse chronological order
-$ svn log -r 8 # shows log for revision 8
+$ svn log -r 8 # shows all logs for revision 8
</screen>
<para>You can also examine the log history of a single file or
directory.
@@ -1721,7 +1745,7 @@
</screen>
<para>These will display log messages <emphasis>only</emphasis>
- for those revisions in which the working file (or URL)
+ for those revisions in which the specified file (or URL)
changed.</para>
<para>If you want even more information about a file or
@@ -1730,9 +1754,9 @@
Because Subversion allows you to move and copy files and
directories, it is important to be able to track path changes
in the file system, so in verbose mode, <command>svn
- log</command> will include a list of
- <firstterm>changed-paths</firstterm> in a revision in its
- output:</para>
+ log</command> will also list any
+ <firstterm>changed-paths</firstterm> that occurred in a
revision:
+ </para>
<screen>
$ svn log -r 8 -v
@@ -1764,12 +1788,12 @@
<para>At first glance, this seems like an error, but you need
to remember that while revisions are repository-wide,
<command>svn log</command> operates on a path in the
- repository (If you supply no path, Subversion defaults to
+ repository (if you don't supply a path, Subversion defaults
to
<literal>"."</literal>). As a result, if you're operating
in a subdirectory of your working copy and attempt to log a
revision where nothing beneath your current directory
changed, Subversion will give you an empty log. If you want
- to see what changed in that revision, try running the same
+ to see a list of everything that changed in that revision,
try running the same
command from the top directory of your working copy.</para>
</sidebar>
@@ -1781,7 +1805,7 @@
<para>We've already seen <command>svn diff</command>
before—it displays file differences in unified diff
- format; it was used to show the local modifications made to
+ 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
@@ -1861,7 +1885,7 @@
<para>If two revision numbers, separated by a colon, are
passed via <option>--revision</option>
- (<option>-r</option>), then the two revisions are directly
+ (<option>-r</option>), then these two revisions are directly
compared.</para>
<screen>
@@ -1883,8 +1907,8 @@
compare files in your working copy to the repository, but
if you supply a URL argument, you can examine the
differences between items in the repository without even
- having a working copy. This is especially useful if you
- wish to inspect changes in a file when you don't have a
+ having a working copy. This allows you
+ to inspect changes between revisions in a repository item
when you don't happen to have a
working copy on your local machine:</para>
<screen>
@@ -1900,8 +1924,8 @@
<sect2 id="svn-ch-3-sect-5.3">
<title><command>svn cat</command></title>
- <para>If you want to examine an earlier version of a file and
- not necessarily the differences between two files, you can use
+ <para>If you want to examine a particular version of a file
+ (as opposed to the differences between two versions), you can
use
<command>svn cat</command>:</para>
<screen>
@@ -1933,6 +1957,7 @@
you'll need to grab a copy of the old revision, redirect it to
a file, and pass both that and the file in your working copy
to your external diff program.</para>
+ <!-- ###mblais: Does 'svn diff --diff-cmd' do this for you? -->
<para>Sometimes it's easier to look at an older version of a
file in its entirety as opposed to just the differences
@@ -1943,8 +1968,8 @@
<sect2 id="svn-ch-3-sect-5.4">
<title><command>svn list</command></title>
- <para>The <command>svn list</command> command shows you what
- files are in a repository directory without actually
+ <para>The <command>svn list</command> command shows you a listing
of
+ all the files in a repository directory without actually
downloading the files to your local machine:</para>
<screen>
@@ -1969,10 +1994,10 @@
_ 2785 sally 0 Jul 29 19:07 trunk/
</screen>
- <para>The columns tell you if a file has any properties
+ <para>The columns tell you if an item has any properties
(<quote>P</quote> if it does, <quote>_</quote> if it doesn't),
- the revision it was last updated at, the user who last updated
- it, the size if it is a file, the date it was last updated,
+ the revision at which it was last updated, the user who last
updated
+ it, its size (if a file), the date it was last updated,
and the item's name.</para>
</sect2>
@@ -2020,8 +2045,8 @@
to a journaled file system). If a Subversion operation is
interrupted (If you hit Control-C, or if the machine crashes,
for example), the logfiles remain on disk. By re-executing
- the logfiles, Subversion can complete the previously started
- operation, and your working copy can get itself back into a
+ the logfiles, Subversion can complete the interrupted
+ operation, and restore your working copy to a
consistent state.</para>
<para>And this is exactly what <command>svn cleanup</command>
@@ -2048,8 +2073,8 @@
<sect2 id="svn-ch-3-sect-7.3">
<title><command>svn import</command></title>
- <para>The import command is a quick way to move an unversioned
- tree of files into a repository.</para>
+ <para>The import command is a quick way to add an entire
unversioned
+ tree of files to a repository in a single operation.</para>
<screen>
$ svnadmin create /usr/local/svn/newrepos
@@ -2073,6 +2098,10 @@
/fooproject/subdir/quux.h
</screen>
+<!-- ###mblais: This illustrates a confusing asymmetry between 'import'
and 'checkout': -->
+<!-- 'checkout' USES the last element of the source URL as the name of
the checkout dir, -->
+<!-- whereas 'import' IGNORES the last element of the supplied source
path. -->
+
</sect2>
<sect2 id="svn-ch-3-sect-7.4">
@@ -2083,7 +2112,7 @@
branching and merging (see <xref linkend="svn-ch-4"/>) and
properties (see <xref linkend="svn-ch-6-sect-2"/>).
However, you may want to take a moment to skim through <xref
- linkend="svn-ch-8"/> to get an idea of all the many
+ linkend="svn-ch-8"/> to get an idea of the many
different commands that Subversion has—and how you can
use them to make your work easier.</para>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Fri Aug 15 19:50:40 2003