[svnbook] r3808 committed - * src/en/book/ch02-basic-usage.xml...
svnbook at googlecode.com
svnbook at googlecode.com
Thu Oct 21 16:18:15 CDT 2010
Revision: 3808
Author: cmpilato at gmail.com
Date: Thu Oct 21 14:14:32 2010
Log: * src/en/book/ch02-basic-usage.xml
A bunch of textual updates and index management tweaks.
http://code.google.com/p/svnbook/source/detail?r=3808
Modified:
/trunk/src/en/book/ch02-basic-usage.xml
=======================================
--- /trunk/src/en/book/ch02-basic-usage.xml Thu Oct 21 10:40:34 2010
+++ /trunk/src/en/book/ch02-basic-usage.xml Thu Oct 21 14:14:32 2010
@@ -529,6 +529,12 @@
<sect2 id="svn.tour.cycle.update">
<title>Update Your Working Copy</title>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>update</tertiary>
+ </indexterm>
+
<para>When working on a project that is being modified via
multiple working copies, you'll want to update your working
copy to receive any changes committed from other working
@@ -572,30 +578,23 @@
<title>Make Your Changes </title>
<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, and so on. The Subversion commands that you
- will use here are <command>svn add</command>, <command>svn
- delete</command>, <command>svn copy</command>, <command>svn
- move</command>, and <command>svn mkdir</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.</para>
-
- <para>You can make two kinds of changes to your
- working copy: <firstterm>file changes</firstterm>
- and <firstterm>tree changes</firstterm>. You don't need to
- tell Subversion that you intend to change a file; just make
- your changes using your text editor, word processor, graphics
- program, or whatever tool you would normally use. Subversion
- automatically detects which files have been changed, and in
- addition, it handles binary files just as easily as it handles
- text files—and just as efficiently, too. For tree
- changes, you can ask Subversion to <quote>mark</quote> files
- and directories for scheduled removal, addition, copying, or
- moving. These changes may take place immediately in your
- working copy, but no additions or removals will happen in the
- repository until you commit them.</para>
+ copy. You can make two kinds of changes to your working
+ copy: <firstterm>file changes</firstterm> and <firstterm>tree
+ changes</firstterm>. You don't need to tell Subversion that
+ you intend to change a file; just make your changes using your
+ text editor, word processor, graphics program, or whatever
+ tool you would normally use. Subversion automatically detects
+ which files have been changed, and in addition, it handles
+ binary files just as easily as it handles text files—and
+ just as efficiently, too. Tree changes are different, and
+ involve changes to a directory's structure. Such changes
+ include adding and removing files, renaming files or
+ directories, and copying files or directories to new
+ locations. For tree changes, you use Subversion operations
+ to <quote>schedule</quote> files and directories for removal,
+ addition, copying, or moving. These changes may take place
+ immediately in your working copy, but no additions or removals
+ will happen in the repository until you commit them.</para>
<sidebar>
<title>Versioning Symbolic Links</title>
@@ -628,41 +627,68 @@
<variablelist>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>add</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>delete</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>copy</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>move</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>mkdir</tertiary>
+ </indexterm>
+
<varlistentry>
- <term><userinput>svn add foo</userinput></term>
+ <term><userinput>svn add FOO</userinput></term>
<listitem>
- <para>Schedule file, directory, or symbolic link
- <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
+ <para>Use this to schedule the file, directory, or
+ symbolic link <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 want only to add
- <filename>foo</filename> itself, pass the
- <option>--depth empty</option> option.</para>
+ <filename>FOO</filename> itself, pass the
+ <option>--depth=empty</option> option.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><userinput>svn delete foo</userinput></term>
+ <term><userinput>svn delete FOO</userinput></term>
<listitem>
- <para>Schedule file, directory, or symbolic link
- <filename>foo</filename> to be deleted from the
- repository. If <filename>foo</filename> is a file or
- link, it is immediately deleted from your working copy.
- If <filename>foo</filename> is a directory, it is not
- deleted, but Subversion schedules it for deletion. When
- you commit your changes, <filename>foo</filename> will
- be entirely removed from your working copy and the
- repository.
+ <para>Use this to schedule the file, directory, or
+ symbolic link <filename>FOO</filename> to be deleted
+ from the repository. If <filename>FOO</filename> is a
+ file or link, it is immediately deleted from your
+ working copy. If <filename>FOO</filename> is a
+ directory, it is not deleted, but Subversion schedules
+ it for deletion. When you commit your
+ changes, <filename>FOO</filename> will be entirely
+ removed from your working copy and the repository.
<footnote>
<para>Of course, nothing is ever totally deleted from
- the repository—just from the
- <literal>HEAD</literal> of the repository. You can
- get back anything you delete by checking out (or
- updating your working copy to) a revision earlier
- than the one in which you deleted it. Also see <xref
- linkend="svn.branchmerge.basicmerging.resurrect"
+ the repository—just from
+ its <literal>HEAD</literal> revision. You may
+ continue to access the deleted item in previous
+ revisions. Should you desire to resurrect the item
+ so that it is again present in <literal>HEAD</literal>,
+ see <xref
linkend="svn.branchmerge.basicmerging.resurrect"
/>.</para>
</footnote>
</para>
@@ -670,14 +696,14 @@
</varlistentry>
<varlistentry>
- <term><userinput>svn copy foo bar</userinput></term>
+ <term><userinput>svn copy FOO BAR</userinput></term>
<listitem>
- <para>Create a new item <filename>bar</filename> as a
- duplicate of <filename>foo</filename> and automatically
- schedule <filename>bar</filename> for addition. When
- <filename>bar</filename> is added to the repository on
+ <para>Create a new item <filename>BAR</filename> as a
+ 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>).
+ originally come from <filename>FOO</filename>).
<command>svn copy</command> does not create intermediate
directories unless you pass the
<option>--parents</option> option.</para>
@@ -685,13 +711,13 @@
</varlistentry>
<varlistentry>
- <term><userinput>svn move foo bar</userinput></term>
+ <term><userinput>svn move FOO BAR</userinput></term>
<listitem>
<para>This command is exactly the same as running
- <userinput>svn copy foo bar; svn delete foo</userinput>.
- That is, <filename>bar</filename> is scheduled for
- addition as a copy of <filename>foo</filename>, and
- <filename>foo</filename> is scheduled for removal.
+ <userinput>svn copy FOO BAR; svn delete FOO</userinput>.
+ That is, <filename>BAR</filename> is scheduled for
+ addition as a copy of <filename>FOO</filename>, and
+ <filename>FOO</filename> is scheduled for removal.
<command>svn move</command> does not create intermediate
directories unless you pass the
<option>--parents</option> option.</para>
@@ -699,11 +725,11 @@
</varlistentry>
<varlistentry>
- <term><userinput>svn mkdir blort</userinput></term>
+ <term><userinput>svn mkdir FOO</userinput></term>
<listitem>
<para>This command is exactly the same as running
- <userinput>mkdir blort; svn add blort</userinput>. That is,
- a new directory named <filename>blort</filename> is
+ <userinput>mkdir FOO; svn add FOO</userinput>. That is,
+ a new directory named <filename>FOO</filename> is
created and scheduled for addition.</para>
</listitem>
</varlistentry>
@@ -713,23 +739,31 @@
<sidebar>
<title>Changing the Repository Without a Working Copy</title>
- <para>There <emphasis>are</emphasis> some use cases that
- immediately commit tree changes to the repository. This
- happens only when a subcommand is operating directly on a
- URL, rather than on a working-copy path. In particular,
- specific uses of <command>svn mkdir</command>, <command>svn
+ <para>Subversion <emphasis>does</emphasis> offer ways to
+ immediately commit tree changes to the repository without an
+ explicit commit action. 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 (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
- sort of <quote>staging area</quote> to set up your changes
- before committing them to the repository. Commands that
- operate on URLs don't have this luxury, so when you operate
- directly on a URL, any of the aforementioned actions represents
an
- immediate commit.</para>
+ <command>svn delete</command> can operation directly on
+ repository URLs as well as on working copy paths. Of
+ course, as previously mentioned, <command>svn
+ import</command> always makes direct changes to the
+ repository.</para>
+
+ <para>There are pros and cons to performing URL-based
+ operations. One obvious advantage to doing so is speed:
+ sometimes, checking out a working copy that you don't
+ already have solely to perform some seemingly simple action
+ is an overbearing cost. A disadvantage is that you are
+ generally limited to a single, or single type of, operation
+ at a time when operating directly on URLs. Finally, the
+ primary advantage of a working copy is in its utility as a
+ sort of <quote>staging area</quote> for changes. You can
+ make sure that the changes you are about to commit make
+ sense in the larger scope of your project before committing
+ them. And, of course, these staged changes can be as
+ complex or as a simple as they need to be, yet result in but
+ a single new revision when committed.</para>
</sidebar>
@@ -739,97 +773,94 @@
<sect2 id="svn.tour.cycle.examine">
<title>Review Your Changes</title>
+ <indexterm>
+ <primary>log message</primary>
+ </indexterm>
+
<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
- examining your changes before you commit, you can make a more
- accurate log message. 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 an overview of the changes
- you've made by using <command>svn status</command>, and dig
- into the details of those changes by using <command>svn
- diff</command>.</para>
+ examining your changes before you commit, you can compose a
+ more accurate <firstterm>log message</firstterm> (a
+ human-readable description of the committed changes stored
+ alongside those changes in the repository). You may also
+ discover that you've inadvertently changed a file, and that
+ you need to undo that change before committing. Additionally,
+ this is a good opportunity to review and scrutinize changes
+ before publishing them. You can see an overview of the
+ changes you've made by using the <command>svn status</command>
+ command, and you can dig into the details of those changes by
+ using the <command>svn diff</command> command.</para>
<sidebar>
<title>Look Ma! No Network!</title>
<para>You can use the commands <command>svn status</command>,
<command>svn diff</command>, and <command>svn
- revert</command> without any network access even
- if your repository <emphasis>is</emphasis> across the
- network. This makes it easy to manage your
- changes-in-progress when you are somewhere without a network
- connection, such as traveling on an airplane, riding a
- commuter train, or hacking on the beach.
- <footnote>
- <para>And you don't have a WLAN card. Thought
- you got us, huh?</para>
- </footnote>
- </para>
+ revert</command> without any network access even if your
+ repository <emphasis>is</emphasis> across the network. This
+ makes it easy to manage and review your changes-in-progress
+ when you are working offline or are otherwise unable to
+ contact your repository over the network.</para>
+
+ <indexterm>
+ <primary>text-base</primary>
+ </indexterm>
+ <indexterm>
+ <primary>delta</primary>
+ </indexterm>
<para>Subversion does this by keeping private caches of
- pristine versions of each versioned file inside the
- <filename>.svn</filename> administrative areas. This allows
+ pristine, unmodified versions of each versioned file inside
+ its working copy administrative areas. This allows
Subversion to report—and revert—local
modifications to those files <emphasis>without network
access</emphasis>. This cache (called the
- <quote>text-base</quote>) also allows Subversion to send the
- user's local modifications during a commit to the server as
- a compressed <firstterm>delta</firstterm> (or
+ <firstterm>text-base</firstterm>) also allows Subversion to
+ send the user's local modifications during a commit to the
+ server as a compressed <firstterm>delta</firstterm> (or
<quote>difference</quote>) against the pristine version.
Having this cache is a tremendous benefit—even if you
- have a fast Internet connection, it's much faster to send only a
- file's changes rather than the whole file to the
- server.</para>
+ have a fast Internet connection, it's generally much faster
+ to send only a file's changes rather than the whole file to
+ the server.</para>
</sidebar>
- <para>Subversion has been optimized to help you with this task,
- and it is able to do many things without communicating with
- the repository. In particular, your working copy contains a
- hidden cached <quote>pristine</quote> copy of each
version-controlled
- file within the <filename>.svn</filename> area.
- 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
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>status</tertiary>
+ </indexterm>
+
+ <para>To get an overview of your changes, 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
- all the information you need regarding what has changed in
- your working copy—without accessing the repository
- or potentially incorporating new changes published by
- other users.</para>
-
- <para>In Subversion, <command>svn update</command> does just
- that—it updates your working copy with any changes
- committed to the repository since the last time you
- updated your working copy. You may have to break the
- habit of using the <command>update</command> command to
- 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. Here are a few examples of
- the most common status codes that <command>svn
- status</command> can return. (Note that the text following
- <literal>#</literal> is not
+ <tip>
+ <para>Because the <command>cvs status</command> command's
+ output was so noisy, and because <command>cvs
+ update</command> not only performs an update, but also
+ reports the status of your local changes, most CVS users
+ have grown accustomed to using <command>cvs
+ update</command> to report their changes. In Subversion,
+ the update and status reporting facilities are completely
+ separate. See
+ <xref linkend="svn.forcvs.status-vs-update"/> for more
+ details.</para>
+ </tip>
+
+ <para>If you run <userinput>svn status</userinput> at the top
+ of your working copy with no additional arguments, it will
+ detect and report all file and tree changes you've made.
+ Here are a few examples of the most common status codes
+ that <command>svn status</command> can return. (Note that
+ the text following <literal>#</literal> is not
actually printed by <command>svn status</command>.)</para>
<screen>
@@ -860,7 +891,6 @@
<varlistentry>
<term><computeroutput>C item</computeroutput></term>
<listitem>
-
<para>The file <filename>item</filename> is in a state
of conflict. That is, changes received from the
server during an update overlap with local changes
@@ -868,7 +898,6 @@
resolved during the update). You must resolve this
conflict before committing your changes to the
repository.</para>
-
</listitem>
</varlistentry>
@@ -927,12 +956,17 @@
and who changed it.</para>
<para>None of the prior invocations to <command>svn
- status</command> contact the repository—instead, they
- compare the metadata in the <filename>.svn</filename>
- directory with the working copy. Finally, there is the
+ status</command> contact the repository—they merely
+ report what is known about the working copy items based on
+ the records stored in the working copy administrative area
+ and on the timestamps and contents of modified files. But
+ sometimes it is useful to see which of the items in your
+ working copy have been modified in the repository since the
+ last time you updated your working copy. For
+ this, <command>svn status</command> offers the
<option>--show-updates</option> (<option>-u</option>)
option, which contacts the repository and adds information
- about things that are out of date:</para>
+ about items that are out of date:</para>
<screen>
$ svn status -u -v
@@ -944,20 +978,22 @@
Status against revision: 46
</screen>
- <para>Notice the two asterisks: if you were to run
- <userinput>svn update</userinput> at this point, you would
- receive changes to <filename>README</filename>
+ <para>Notice in the previous example the two asterisks: if you
+ were to run <userinput>svn update</userinput> at this point,
+ you would receive changes to <filename>README</filename>
and <filename>trout.c</filename>. This tells you some very
- 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>
-
- <para><command>svn status</command> can display much more
- information about the files and directories in your
- working copy than we've shown here—for an exhaustive
- description of <command>svn status</command> and its
- output, see <xref linkend="svn.ref.svn.c.status"/>.</para>
+ useful information—because one of those items is also
+ one that you have locally modified (the
+ file <filename>README</filename>), you'll need to update and
+ get the servers changes for that file before you commit, or
+ the repository will reject your commit for being out of
+ date. We discuss this in more detail later.</para>
+
+ <para><command>svn status</command> can display much more
+ information about the files and directories in your working
+ copy than we've shown here—for an exhaustive
+ description of <command>svn status</command> and its output,
+ see <xref linkend="svn.ref.svn.c.status"/>.</para>
</sect3>
@@ -965,12 +1001,34 @@
<sect3 id="svn.tour.cycle.examine.diff">
<title>Examine the details of your local modifications</title>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>diff</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>unified diff</primary>
+ </indexterm>
+
<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
- running <userinput>svn diff</userinput> with no arguments, which
- prints out file changes in <firstterm>unified diff
- format</firstterm>:</para>
+ <command>svn diff</command> command, which displays
+ differences in file content. When you run <userinput>svn
+ diff</userinput> at the top of your working copy with no
+ arguments, Subversion will print the changes you've made to
+ human-readable files in your working copy. It displays
+ those changes in <firstterm>unified diff</firstterm> format,
+ a format which describes changes as <quote>hunks</quote>
+ (or <quote>snippets</quote>) of a file's content where each
+ line of text is prefixed with a single-character code: a
+ space, which means the line was unchanged; a minus sign
+ (<literal>-</literal>), which means the line was removed
+ from the file; or a plus sign (<literal>+</literal>), which
+ means the line was added to the file. In the context
+ of <command>svn diff</command>, those minus-sign- and
+ plus-sign-prefixed lines show how the lines looked before
+ and after your modifications, respectively.</para>
+
+ <para>Here's an example:</para>
<screen>
$ svn diff
@@ -1013,40 +1071,50 @@
+things about bloo.
</screen>
+ <indexterm>
+ <primary>patches</primary>
+ </indexterm>
+
<para>The <command>svn diff</command> command produces this
- output by comparing your working files against the cached
- <quote>pristine</quote> copies within the
- <filename>.svn</filename> area. Files scheduled for
- addition are displayed as all added text, and files
- scheduled for deletion are displayed as all deleted
- text.</para>
-
- <para>Output is displayed in unified diff format. That is,
- removed lines are prefaced with <literal>-</literal>, and
- added lines are prefaced with
- <literal>+</literal>. <command>svn diff</command> also
- prints filename and offset information useful to the
- <command>patch</command> program, so you can generate
- <quote>patches</quote> by redirecting the diff output to a
- file:</para>
+ output by comparing your working files against its pristine
+ text-base. Files scheduled for addition are displayed as
+ files in which every line was added; files scheduled for
+ deletion are displayed as if every line was removed from
+ those files. The output from <command>svn diff</command> is
+ compatible with the <command>patch</command> program.
+ The <command>patch</command> program reads and
+ applies <firstterm>patch files</firstterm>
+ (or <quote>patches</quote>), which are files that describe
+ differences made to one or more files. Because of this, you
+ can share the changes you've made in your working copy with
+ someone else without first committing those changes by
+ creating a patch file from the redirected output
+ of <command>svn diff</command>:</para>
<screen>
$ svn diff > patchfile
+$
</screen>
- <para>You could, for example, email the patch file to another
- developer for review or testing prior to a commit.</para>
-
<para>Subversion uses its internal diff 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 <option>--extensions</option>
- (<option>-x</option>) option. For example, to see local
- differences in file <filename>foo.c</filename> in context
- output format while ignoring case differences, you might run
- <userinput>svn diff --diff-cmd /usr/bin/diff -x "-i"
- foo.c</userinput>.</para>
+ <option>--diff-cmd</option> and pass any additional flags
+ that it needs via the <option>--extensions</option>
+ (<option>-x</option>) option. For example, you might want
+ Subversion to defer its difference calculation and display
+ to the GNU <command>diff</command> program, asking that
+ program to print local modifications made to the
+ file <filename>foo.c</filename> in context diff format
+ (another flavor of difference format) while ignoring changes
+ made only to the case of the letters used in the file's
+ contents:</para>
+
+ <screen>
+$ svn diff --diff-cmd /usr/bin/diff -x "-i" foo.c
+…
+$
+</screen>
</sect3>
@@ -1057,78 +1125,103 @@
<sect2 id="svn.tour.cycle.revert">
<title>Fix Your Mistakes</title>
-
<para>Suppose while viewing the output of <command>svn
diff</command> you determine that all the changes you made to
a particular file are mistakes. Maybe you shouldn't have
changed the file at all, or perhaps it would be easier to make
- different changes starting from scratch.</para>
-
- <para>This is a perfect opportunity to use <command>svn
- revert</command>:</para>
+ different changes starting from scratch. You could edit the
+ file again and unmake all those changes. You could try to
+ find an copy of how the file looked before you changed it, and
+ then copy the unchanged contents atop your changed ones. You
+ could attempt to apply those changes to the file again in
+ reverse using <userinput>patch -R</userinput>. And there are
+ probably other approaches you could take.</para>
+
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>revert</tertiary>
+ </indexterm>
+
+ <para>Fortunately in Subversion, undoing your work and starting
+ over from scratch doesn't require such acrobatics. Just use
+ the <command>svn revert</command> command:</para>
<screen>
+$ svn status README
+M foo
$ svn revert README
Reverted 'README'
+$ svn status README
+$
</screen>
- <para>Subversion reverts the file to its premodified state by
- overwriting it with the cached <quote>pristine</quote> copy
- from the <filename>.svn</filename> area. But also note that
+ <para>In this example, Subversion has reverted the file to its
+ premodified state by overwriting it with the pristine version
+ of the file cached in the text-base area. But note that
<command>svn revert</command> can undo
- <emphasis>any</emphasis> scheduled operations—for
+ <emphasis>any</emphasis> scheduled operation—for
example, you might decide that you don't want to add a new
file after all:</para>
<screen>
$ svn status foo
? foo
-
$ svn add foo
A foo
-
$ svn revert foo
Reverted 'foo'
-
$ svn status foo
? foo
+$
</screen>
- <note>
- <para><userinput>svn revert
<replaceable>item</replaceable></userinput> has exactly the same
- effect as deleting <replaceable>item</replaceable> from
- your working copy and then running <userinput>svn update -r
- BASE <replaceable>item</replaceable></userinput>. However,
- if you're reverting a file, <command>svn revert</command>
- has one very noticeable difference—it doesn't have
- to communicate with the repository to restore your
- file.</para>
- </note>
-
<para>Or perhaps you mistakenly removed a file from version
control:</para>
<screen>
$ svn status README
-
$ svn delete README
D README
-
$ svn revert README
Reverted 'README'
-
$ svn status README
+$
</screen>
+ <para>The <command>svn revert</command> command offers salvation
+ for imperfect people. It can save you huge amounts of time
+ and energy that would otherwise be spent manually unmaking
+ changes or, worse, disposing of your working copy and checking
+ out a fresh one just to have a clean slate to work with
+ again.</para>
+
</sect2>
<!-- ===============================================================
-->
<sect2 id="svn.tour.cycle.resolve">
<title>Resolve Any Conflicts</title>
- <para>We've already seen how <userinput>svn status -u</userinput>
- can predict conflicts. Suppose you run <userinput>svn
- update</userinput> and some interesting things occur:</para>
+ <indexterm>
+ <primary>conflicts</primary>
+ <secondary>resolving</secondary>
+ </indexterm>
+
+ <para>We've already seen how <userinput>svn status
+ -u</userinput> can predict conflicts, but dealing with those
+ conflicts is still something that remains to be done.
+ Conflicts can occur any time you attempt to merge or integrate
+ (in a very general sense) changes from the repository into
+ your working copy. By now you know that <command>svn
+ update</command> creates exactly that sort of
+ scenario—that command's very purpose is to bring your
+ working copy up to date with the repository by merging all the
+ changes made since your last update into your working
+ copy. So how does Subversion report these conflicts to you,
+ and how do you deal with them?</para>
+
+ <para>Suppose you run <userinput>svn update</userinput> and you
+ see this sort of interesting output:</para>
<screen>
$ svn update
@@ -1150,12 +1243,19 @@
with, but the changes coming from the repository didn't
overlap with those local changes.</para>
- <para>But the next two lines are part of a feature (new in
- Subversion 1.5) called <firstterm>interactive conflict
- resolution</firstterm>. This means that the changes from the
- server overlapped with your own, and you have the opportunity
- to resolve this conflict. The most commonly used options are
- displayed, but you can see all of the options by
+ <para>It's the next few lines which are interesting. First,
+ Subversion reports to you that in its attempt to merge
+ outstanding server changes into the
+ file <filename>bar.c</filename>, it has detected that some of
+ those changes clash with local modifications you've made to
+ that file in your working copy but have not yet committed.
+ Perhaps someone has changed the same line of text you also
+ changed. Whatever the reason, Subversion instantly flags this
+ file as being in a state of conflict. It then asks you what
+ you want to do about the problem, allowing you to
+ interactively choose an action to take toward resolving the
+ conflict. The most commonly used options are displayed, but
+ you can see all of the options by
typing <replaceable>h</replaceable>:</para>
<screen>
@@ -1177,90 +1277,70 @@
<varlistentry>
<term><computeroutput>(p) postpone</computeroutput></term>
<listitem>
-
<para>Leave the file in a conflicted state for you to
resolve after your update is complete.</para>
-
</listitem>
</varlistentry>
-
-
<varlistentry>
<term><computeroutput>(df) diff-full</computeroutput></term>
<listitem>
-
<para>Display the differences between the base revision
and the conflicted file itself in unified diff format.</para>
-
</listitem>
</varlistentry>
-
<varlistentry>
<term><computeroutput>(e) edit</computeroutput></term>
<listitem>
-
<para>Open the file in conflict with your favorite editor,
as set in the environment variable
<literal>EDITOR</literal>.</para>
-
</listitem>
</varlistentry>
-
<varlistentry>
<term><computeroutput>(r) resolved</computeroutput></term>
<listitem>
-
<para>After editing a file, tell
<command>svn</command> that you've resolved the
conflicts in the file and that it should accept the
current contents—basically that you've
<quote>resolved</quote> the conflict.</para>
-
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>(mf) mine-full</computeroutput></term>
<listitem>
-
<para>Discard the newly received changes from the server
and use only your local changes for the file under
review.</para>
-
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>(tf) theirs-full</computeroutput></term>
<listitem>
-
<para>Discard your local changes to the file under review
and use only the newly received changes from the
server.</para>
-
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>(l) launch</computeroutput></term>
<listitem>
-
<para>Launch an external program to perform the conflict
- resolution. This requires a bit of preparation
- beforehand.</para>
-
+ resolution. This requires a bit of preparation
+ beforehand.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>(h) help</computeroutput></term>
<listitem>
-
<para>Show the list of all possible commands you can use
- in interactive conflict resolution.</para>
-
+ in interactive conflict resolution.</para>
</listitem>
</varlistentry>
@@ -1269,7 +1349,6 @@
<para>We'll cover these commands in more detail now, grouping
them together by related functionality.</para>
-
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
<sect3 id="svn.tour.cycle.resolve.diff">
@@ -1324,7 +1403,7 @@
the file by hand in your favorite text editor is a somewhat
low-tech way of remedying conflicts (see <xref
linkend="svn.tour.cycle.resolve.byhand"/> for a
- walkthrough), so some people like to use fancy graphical
+ walkthrough), so some people prefer to use fancy graphical
merge tools instead.</para>
<para>To use a merge tool, you need to either set the
@@ -1369,11 +1448,11 @@
encounter a conflict that you're not prepared to review or
resolve, you can type <userinput>p</userinput> to postpone
resolving a conflict on a file-by-file basis when you run
- <userinput>svn update</userinput>. If you're running an update
- and don't want to resolve any conflicts, you can pass the
- <option>--non-interactive</option> option to <command>svn
- update</command>, and any file in conflict will be marked
- with a <computeroutput>C</computeroutput>
+ <userinput>svn update</userinput>. If you know in advance
+ that you don't want to resolve any conflicts interactively,
+ you can pass the <option>--non-interactive</option> option
+ to <command>svn update</command>, and any file in conflict
+ will be marked with a <computeroutput>C</computeroutput>
automatically.</para>
<para>The <computeroutput>C</computeroutput>
@@ -1698,10 +1777,10 @@
<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>
- 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 the
+ need to supply a log message 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 the
<option>--message</option> (<option>-m</option>)
option:</para>
More information about the svnbook-dev
mailing list