[svnbook] r3809 committed - * src/en/book/ch02-basic-usage.xml...
svnbook at googlecode.com
svnbook at googlecode.com
Tue Oct 26 13:25:26 CDT 2010
Revision: 3809
Author: cmpilato at gmail.com
Date: Tue Oct 26 10:24:44 2010
Log: * src/en/book/ch02-basic-usage.xml
Just continuing my read-through and general update...
http://code.google.com/p/svnbook/source/detail?r=3809
Modified:
/trunk/src/en/book/ch02-basic-usage.xml
=======================================
--- /trunk/src/en/book/ch02-basic-usage.xml Thu Oct 21 14:14:32 2010
+++ /trunk/src/en/book/ch02-basic-usage.xml Tue Oct 26 10:24:44 2010
@@ -1354,6 +1354,11 @@
<title>Viewing conflict differences interactively</title>
+ <indexterm>
+ <primary>conflicts</primary>
+ <secondary>reviewing</secondary>
+ </indexterm>
+
<para>Before deciding how to attack a conflict interactively,
odds are that you'd like to see exactly what is in conflict,
and the <firstterm>diff-full</firstterm> command
@@ -1390,6 +1395,12 @@
<title>Resolving conflict differences interactively</title>
+ <indexterm>
+ <primary>conflicts</primary>
+ <secondary>resolution</secondary>
+ <tertiary>interactive</tertiary>
+ </indexterm>
+
<para>There are four different ways to resolve conflicts
interactively—two of which allow you to selectively
merge and edit changes, and two of which allow you to simply
@@ -1442,6 +1453,12 @@
<title>Postponing conflict resolution</title>
+ <indexterm>
+ <primary>conflicts</primary>
+ <secondary>resolution</secondary>
+ <tertiary>postponing</tertiary>
+ </indexterm>
+
<para>This may sound like an appropriate section for avoiding
marital disagreements, but it's actually still about
Subversion, so read on. If you're doing an update and
@@ -1465,6 +1482,11 @@
<itemizedlist>
+ <indexterm>
+ <primary>conflicts</primary>
+ <secondary>conflict markers</secondary>
+ </indexterm>
+
<listitem>
<para>Subversion prints a <computeroutput>C</computeroutput>
during the update and remembers that the file is in a
@@ -1611,6 +1633,12 @@
<sect3 id="svn.tour.cycle.resolve.byhand">
<title>Merging conflicts by hand</title>
+ <indexterm>
+ <primary>conflicts</primary>
+ <secondary>resolution</secondary>
+ <tertiary>manual</tertiary>
+ </indexterm>
+
<para>Merging conflicts by hand can be quite intimidating the
first time you attempt it, but with a little practice, it
can become as easy as falling off a bike.</para>
@@ -1723,12 +1751,20 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
<sect3 id="svn.tour.cycle.resolve.theirsfull">
- <title>Discarding your changes in favor of a newly fetched
revision</title>
+ <title>Discarding your changes in favor of a newly fetched
+ revision</title>
+
+ <indexterm>
+ <primary>conflicts</primary>
+ <secondary>resolution</secondary>
+ </indexterm>
<para>If you get a conflict and decide that you want to throw
- out your changes, you can run <userinput>svn resolve --accept
- theirs-full
<replaceable>CONFLICTED-PATH</replaceable></userinput> and Subversion will
discard your edits
- and remove the temporary files:</para>
+ out your changes, you can run <userinput>svn resolve
+ --accept theirs-full
+ <replaceable>CONFLICTED-PATH</replaceable></userinput> and
+ Subversion will discard your edits and remove the temporary
+ files:</para>
<screen>
$ svn update
@@ -1741,6 +1777,7 @@
sandwich.txt sandwich.txt.mine sandwich.txt.r2 sandwich.txt.r1
$ svn resolve --accept theirs-full sandwich.txt
Resolved conflicted state of 'sandwich.txt'
+$
</screen>
</sect3>
@@ -1758,6 +1795,7 @@
Reverted 'sandwich.txt'
$ ls sandwich.*
sandwich.txt
+$
</screen>
<para>Note that when you revert a conflicted file, you don't
@@ -1780,9 +1818,8 @@
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>
+ command line using the <option>--message</option>
+ (<option>-m</option>) option:</para>
<screen>
$ svn commit -m "Corrected number of cheese slices."
@@ -1791,10 +1828,11 @@
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> (<option>-F</option>) option:</para>
+ <para>However, if you've been composing your log message in some
+ other text file as you work, you may want to tell Subversion
+ to get the message from that file by passing its filename as
+ the value of the <option>--file</option> (<option>-F</option>)
+ option:</para>
<screen>
$ svn commit -F logmsg
@@ -1815,7 +1853,7 @@
<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, save
+ saved your commit message, simply delete all the text, save
again, and then abort:</para>
<screen>
@@ -1880,8 +1918,8 @@
just want to <emphasis>peer into</emphasis> the past instead of
<emphasis>going into</emphasis> it.</para>
- <para>Several commands can provide you with
- historical data from the repository:</para>
+ <para>Several commands can provide you with historical data from
+ the repository:</para>
<variablelist>
@@ -1956,13 +1994,33 @@
<option>--revision</option> (<option>-r</option>)
option:</para>
- <screen>
-$ svn log -r 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 -r 8 # shows log for revision 8
-</screen>
+ <table id="svn.tour.history.log.tbl-1">
+ <title>Common log requests</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Command</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><userinput>svn log -r 5:19</userinput></entry>
+ <entry>Display logs for revisions 5 through 19 in
+ chronological order</entry>
+ </row>
+ <row>
+ <entry><userinput>svn log -r 19:5</userinput></entry>
+ <entry>Display logs for revisions 5 through 19 in
+ reverse chronological order</entry>
+ </row>
+ <row>
+ <entry><userinput>svn log -r 8</userinput></entry>
+ <entry>Display logs for revision 8 only</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>You can also examine the log history of a single file or
directory. For example:</para>
@@ -2057,8 +2115,8 @@
nor any of its children was changed, Subversion will show you
an empty log. If you want to see what changed in that
revision, try pointing <command>svn log</command> directly at
- the topmost URL of your repository, as in <userinput>svn log -r 2
- http://svn.collab.net/repos/svn</userinput>.</para>
+ the topmost URL of your repository, as in <userinput>svn log
+ -r 2 ^/</userinput>.</para>
</sidebar>
@@ -2216,7 +2274,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
<sect3 id="svn.tour.history.browsing.cat">
- <title>svn cat</title>
+ <title>svn cat</title>
<para>If you want to examine an earlier version of a file and
@@ -2278,13 +2336,14 @@
name.</para>
<warning>
- <para>The <userinput>svn list</userinput> command with no
arguments
- defaults to the <emphasis>repository URL</emphasis> of the
- current working directory, <emphasis>not</emphasis> the
- local working copy directory. After all, if you want a
- listing of your local directory, you could use just plain
- <command>ls</command> (or any reasonable non-Unixy
- equivalent).</para>
+ <para>The <userinput>svn list</userinput> command with no
+ arguments defaults to the <emphasis>repository
+ URL</emphasis> of the current working
+ directory, <emphasis>not</emphasis> the local working copy
+ directory. After all, if you want a listing of your local
+ directory, you could use just plain
+ <command>ls</command> (or any reasonable non-Unixy
+ equivalent).</para>
</warning>
</sect3>
@@ -2357,8 +2416,8 @@
tasks relating to your working copy.</para>
+ <!-- ===============================================================
-->
<sect2 id="svn.tour.cleanup.disposal">
-
<title>Disposing of a Working Copy</title>
<para>Subversion doesn't track either the state or the existence of
@@ -2374,58 +2433,60 @@
for use.</para>
<para>However, if you're definitely not going to use a working
- copy again, you can safely delete the entire thing, but you'd
- be well served to take a look through the working copy for
- unversioned files. To find these files, run <userinput>svn
- status</userinput> and review any files that are prefixed with a
+ copy again, you can safely delete the entire thing using
+ whatever directory removal capabilities your operating system
+ offers. We recommend that before you do so you
+ run <userinput>svn status</userinput> and review any files
+ listed in its output that are prefixed with a
<literal>?</literal> to make certain that they're not of
- importance. After you're done reviewing, you can safely
- delete your working copy.</para>
+ importance.</para>
</sect2>
+ <!-- ===============================================================
-->
<sect2 id="svn.tour.cleanup.interruption">
-
<title>Recovering from an Interruption</title>
- <para>When Subversion modifies your working copy (or any
- information within <filename>.svn</filename>), it tries to do
+ <para>When Subversion modifies your working copy—either
+ your files or its own administative state—it tries to do
so as safely as possible. Before changing the working copy,
- Subversion writes its intentions to a logfile. Next, it
- executes the commands in the logfile to apply the requested
- change, holding a lock on the relevant part of the working
- copy while it works—to prevent other Subversion clients
- from accessing the working copy mid-change. Finally,
- Subversion removes the logfile. Architecturally, this is
- similar to a journaled filesystem. If a Subversion operation
- is interrupted (e.g, if the process is killed or if the machine
- crashes), the logfiles remain on disk. By
- reexecuting the logfiles, Subversion can complete the
- previously started operation, and your working copy can get
- itself back into a consistent state.</para>
-
- <para>And this is exactly what <command>svn cleanup</command>
- does: it searches your working copy and runs any leftover
- logs, removing working copy locks in the process.
- If Subversion ever tells you that some part of your working copy
- is <quote>locked,</quote> this is the command that you
- should run. Also, <command>svn status</command> will display
- an <literal>L</literal> next to locked items:</para>
+ Subversion logs its intentions in a private <quote>to-do
+ list</quote>, of sorts. Next, it performs those actions to
+ affect the desired change, holding a lock on the relevant part
+ of the working copy while it works. This prevents other
+ Subversion clients from accessing the working copy mid-change.
+ Finally, Subversion releases its lock and cleans up its
+ private to-do list. Architecturally, this is similar to a
+ journaled filesystem. If a Subversion operation is
+ interrupted (e.g, if the process is killed or if the machine
+ crashes), the private to-do list remains on disk. This allows
+ Subversion to return to that list later to complete any
+ unfinished operations and return your working copy to a
+ consistent state.</para>
+
+ <para>This is exactly what <command>svn cleanup</command> does:
+ it searches your working copy and runs any leftover to-do
+ items, removing working copy locks as it completes those
+ operations. If Subversion ever tells you that some part of
+ your working copy is <quote>locked,</quote> run <command>svn
+ cleanup</command> to remedy the problem. The <command>svn
+ status</command> command will inform you about administrative
+ locks in the working copy, too, by displaying
+ an <literal>L</literal> next to those locked paths:</para>
<screen>
$ svn status
L somedir
M somedir/foo.c
-
$ svn cleanup
$ svn status
M somedir/foo.c
</screen>
- <para>Don't confuse these working copy locks with the ordinary
- locks that Subversion users create when using
- the lock-modify-unlock model of concurrent
- version control; see the sidebar
+ <para>Don't confuse these working copy administrative locks with
+ the user-managed locks that Subversion users create when using
+ the lock-modify-unlock model of concurrent version control;
+ see the sidebar
<xref linkend="svn.advanced.locking.meanings"/> for
clarification.</para>
@@ -2439,72 +2500,76 @@
<sect1 id="svn.tour.treeconflicts">
<title>Dealing with Structural Conflicts</title>
- <para>So far, we have only talked about conflicts at the level
- of file content. When you and your collaborators make overlapping
- changes within the same file, Subversion forces you to merge those
- changes before you can commit.<footnote><para>Well, you could mark
- files containing conflict markers as resolved and commit them,
- if you really wanted to. But this is rarely done in
practice.</para>
- </footnote></para>
-
- <para>But what happens if your collaborators move or delete a file
- that you are still working on? Maybe there was a miscommunication,
- and one person thinks the file should be deleted, while another
- person still wants to commit changes to the file. Or maybe your
- collaborators did some refactoring, renaming files and moving
- around directories in the process. If you were still working on
- these files, those modifications may need to be applied to the
- files at their new location. Such conflicts manifest themselves at
- the directory tree structure level rather than at the file content
- level, and are known as <firstterm>tree
conflicts</firstterm>.</para>
-
- <sidebar>
- <title>Tree conflicts prior to Subversion 1.6</title>
-
- <para>Prior to Subversion 1.6, tree conflicts could yield
- rather unexpected results. For example, if a file was
- locally modified, but had been renamed in the repository,
- running <command>svn update</command> would make Subversion
- carry out the following steps:</para>
-
- <itemizedlist>
- <listitem><para>Check the file to be renamed for local
- modifications.</para></listitem>
-
- <listitem><para>Delete the file at its old location, and
- if it had local modifications, keep an on-disk copy
- of the file at the old location. This on-disk copy
- now appears as an unversioned file in the working
- copy.</para></listitem>
-
- <listitem><para>Add the file, as it exists in the repository,
- at its new location.</para></listitem>
- </itemizedlist>
-
- <para>When this situation arises, there is the possibility
- that the user makes a commit without realizing that local
- modifications have been left in a now-unversioned file in
- the working copy, and have not reached the repository.
- This gets more and more likely (and tedious) if the number
- of files affected by this problem is large.</para>
-
- <para>Since Subversion 1.6, this and other similar situations
- are flagged as conflicts in the working copy.</para>
-
- </sidebar>
-
- <para>As with textual conflicts, tree conflicts prevent a commit
- from being made from the conflicted state, giving the user the
- opportunity to examine the state of the working copy for potential
- problems arising from the tree conflict, and resolving any such
- problems before committing.</para>
-
- <!-- TODO: example -->
+ <para>So far, we have only talked about conflicts at the level
+ of file content. When you and your collaborators make overlapping
+ changes within the same file, Subversion forces you to merge those
+ changes before you can commit.
+ <footnote>
+ <para>Well, you <emphasis>could</emphasis> mark files
+ containing conflict markers as resolved and commit them,
+ if you really wanted to. But this is rarely done in
+ practice.</para>
+ </footnote>
+ </para>
+
+ <para>But what happens if your collaborators move or delete a file
+ that you are still working on? Maybe there was a
+ miscommunication, and one person thinks the file should be
+ deleted, while another person still wants to commit changes to
+ the file. Or maybe your collaborators did some refactoring,
+ renaming files and moving around directories in the process. If
+ you were still working on these files, those modifications may
+ need to be applied to the files at their new location. Such
+ conflicts manifest themselves at the directory tree structure
+ level rather than at the file content level, and are known
+ as <firstterm>tree conflicts</firstterm>.</para>
+
+ <sidebar>
+ <title>Tree conflicts prior to Subversion 1.6</title>
+
+ <para>Prior to Subversion 1.6, tree conflicts could yield rather
+ unexpected results. For example, if a file was locally
+ modified, but had been renamed in the repository,
+ running <command>svn update</command> would make Subversion
+ carry out the following steps:</para>
+
+ <itemizedlist>
+ <listitem><para>Check the file to be renamed for local
+ modifications.</para></listitem>
+
+ <listitem><para>Delete the file at its old location, and if it
+ had local modifications, keep an on-disk copy of the file at
+ the old location. This on-disk copy now appears as an
+ unversioned file in the working copy.</para></listitem>
+
+ <listitem><para>Add the file, as it exists in the repository,
+ at its new location.</para></listitem>
+ </itemizedlist>
+
+ <para>When this situation arises, there is the possibility that
+ the user makes a commit without realizing that local
+ modifications have been left in a now-unversioned file in the
+ working copy, and have not reached the repository. This gets
+ more and more likely (and tedious) if the number of files
+ affected by this problem is large.</para>
+
+ <para>Since Subversion 1.6, this and other similar situations
+ are flagged as conflicts in the working copy.</para>
+
+ </sidebar>
+
+ <para>As with textual conflicts, tree conflicts prevent a commit
+ from being made from the conflicted state, giving the user the
+ opportunity to examine the state of the working copy for
+ potential problems arising from the tree conflict, and resolving
+ any such problems before committing.</para>
+
+ <!-- ===============================================================
-->
<sect2 id="svn.tour.treeconflicts.example">
<title>An example Tree Conflict</title>
<para>Suppose a software project you were working on currently
- looked like this:</para>
+ looked like this:</para>
<screen>
$ svn ls -Rv svn://svn.example.com/trunk/
@@ -2518,10 +2583,10 @@
</screen>
<para>Your collaborator Harry has renamed the file
- <filename>bar.c</filename> to <filename>baz.c</filename>.
- You are still working on <filename>bar.c</filename> in your
- working copy, but you don't know yet that the file has
- been renamed in the repository.</para>
+ <filename>bar.c</filename> to <filename>baz.c</filename>. You
+ are still working on <filename>bar.c</filename> in your
+ working copy, but you don't know yet that the file has been
+ renamed in the repository.</para>
<para>The log message to Harry's commit looked like this:</para>
@@ -2626,12 +2691,12 @@
surprising. But why is <filename>baz.c</filename> reported as
locally modified?</para>
- <para>
- The answer is that despite the limitations of the move
implementation,
- Subversion was smart enough to transfer your local edits in
- <filename>bar.c</filename> into <filename>baz.c</filename>:</para>
-
- <screen>
+ <para>The answer is that despite the limitations of the move
+ implementation, Subversion was smart enough to transfer your
+ local edits in <filename>bar.c</filename>
+ into <filename>baz.c</filename>:</para>
+
+ <screen>
$ svn diff code/baz.c
Index: code/baz.c
===================================================================
@@ -2654,18 +2719,16 @@
Otherwise, Subversion will resort to retreiving
<filename>baz.c</filename> from the repository, and will not
try to transfer your local modifications to it. You will have
- to do so manually.
- </para>
+ to do so manually.</para>
</warning>
<para><command>svn info</command> shows the URLs of the items
- involved in the conflict. The <emphasis>left</emphasis>
- URL shows the source of the local side of the conflict,
- while the <emphasis>right</emphasis> URL shows the source
- of the incoming side of the conflict. These URLs indicate
- where you should start searching the repository's history
- for the change which conflicts with your local change.
- </para>
+ involved in the conflict. The <emphasis>left</emphasis> URL
+ shows the source of the local side of the conflict, while
+ the <emphasis>right</emphasis> URL shows the source of the
+ incoming side of the conflict. These URLs indicate where you
+ should start searching the repository's history for the change
+ which conflicts with your local change.</para>
<screen>
$ svn info code/bar.c | tail -n 4
@@ -2782,8 +2845,8 @@
</screen>
<para>In either case, you have now resolved your first tree
- conflict! You can commit your changes and tell Harry during
- tea break about all the extra work he caused for you.</para>
+ conflict! You can commit your changes and tell Harry during
+ tea break about all the extra work he caused for you.</para>
</sect2>
</sect1>
More information about the svnbook-dev
mailing list