[svnbook commit] r2699 - trunk/src/en/book
fitz
noreply at red-bean.com
Sat Feb 24 23:22:59 CST 2007
Author: fitz
Date: Sat Feb 24 23:22:58 2007
New Revision: 2699
Modified:
trunk/src/en/book/ch-basic-usage.xml
Log:
Incorporate changes from Mike's review. Thanks Mike!
* book/ch-basic-usage.xml: Tighten up chapter and remove reference
stuff.
Modified: trunk/src/en/book/ch-basic-usage.xml
==============================================================================
--- trunk/src/en/book/ch-basic-usage.xml (original)
+++ trunk/src/en/book/ch-basic-usage.xml Sat Feb 24 23:22:58 2007
@@ -43,7 +43,9 @@
<para>There are two ways to get new files into your Subversion
repository: <command>svn import</command> and <command>svn
- add</command>.</para>
+ add</command>. We'll discuss <command>svn import</command> here
+ and <command>svn add</command> later in this chapter when we
+ review a typical day with Subversion.</para>
<!-- =============================================================== -->
<sect2 id="svn.tour.importing.import">
@@ -88,50 +90,6 @@
</sect2>
<!-- =============================================================== -->
- <sect2 id="svn.tour.importing.add">
- <title>svn add</title>
-
- <para><command>svn add</command> on the other hand requires a
- working copy and merely schedules the added files for addition
- in your working copy. <command>svn add</command> doesn't
- contact the repository in any way, nor does it commit the files,
- which means that you can continue to make changes to them (or
- even <command>svn revert</command> them) before committing your
- changes. This is especially useful if the unversioned files
- you're adding are part of a logical change that you're making to
- files that are already under Subversion's control:</para>
-
- <screen>
-$ svn st
-M Makefile
-
-$ svn add mytree
-A mytree
-A mytree/bar.c
-A mytree/foo.c
-A mytree/subdir
-A mytree/subdir/quux.h
-</screen>
-
- <para>We've added our new tree to our working copy which already
- had a modified file in it. Now we're ready to commit our
- changes:</para>
-
- <screen>
-$ svn commit -m "Adding new tree to existing working copy with a local change"
-Adding mytree
-Adding mytree/bar.c
-Adding mytree/foo.c
-Adding mytree/subdir
-Adding mytree/subdir/quux.h
-Sending Makefile
-Transmitting file data ...
-Committed revision 17.
-</screen>
-
- </sect2>
-
- <!-- =============================================================== -->
<sect2 id="svn.tour.importing.layout">
<title>Recommended repository layout</title>
@@ -453,79 +411,12 @@
since the last time you updated, and Subversion has updated
your working copy to include those changes.</para>
- <para>Let's examine the output of <command>svn update</command>
- a bit more. When the server sends changes to your working
- copy, a letter code is displayed next to each item to let you
- know what actions Subversion performed to bring your working
- copy up-to-date:</para>
-
- <variablelist>
-
- <varlistentry>
- <term><computeroutput>U foo</computeroutput></term>
- <listitem>
- <para>File <filename>foo</filename> was
- <computeroutput>U</computeroutput>pdated (received changes
- from the server).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>A foo</computeroutput></term>
- <listitem>
- <para>File or directory <filename>foo</filename> was
- <computeroutput>A</computeroutput>dded to your working
- copy.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>D foo</computeroutput></term>
- <listitem>
- <para>File or directory <filename>foo</filename> was
- <computeroutput>D</computeroutput>eleted from your working
- copy.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>R foo</computeroutput></term>
- <listitem>
- <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
- objects with distinct histories.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>G foo</computeroutput></term>
- <listitem>
- <para>File <filename>foo</filename> received new changes
- from the repository, but your local copy of the file had
- your modifications. Either the changes did not intersect,
- or the changes were exactly the same as your local
- modifications, so Subversion has successfully
- mer<computeroutput>G</computeroutput>ed the repository's
- changes into the file without a problem.</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
- discuss this situation later in this chapter.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
+ <para>When the server sends changes to your working copy via
+ <command>svn update</command>, 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. To find out what these
+ letters mean, see <xref linkend
+ ="svn.ref.svn.c.update"/></para>
</sect2>
@@ -538,47 +429,28 @@
change (or set of changes) to make, such as writing a new
feature, fixing a bug, etc. The Subversion commands that you
will use here are <command>svn add</command>, <command>svn
- delete</command>, <command>svn copy</command>, and
- <command>svn move</command>. However, if you are merely
- editing files that are already in Subversion, you may not need
- to use any of these commands until you commit. Changes you
- can make to your working copy:</para>
-
- <variablelist>
-
- <varlistentry>
- <term>File changes</term>
- <listitem>
- <para>This is the simplest sort of change. You don't need
- to tell Subversion that you intend to change a file;
- just make your changes. Subversion automatically detects
- which files have been changed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Tree changes</term>
- <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
- removals will happen in the repository until you commit
- them.</para>
- </listitem>
- </varlistentry>
+ 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>
- </variablelist>
+ <para>There are two kinds of changes you can make to your
+ working copy: file changes and tree changes. 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 wulrd normally use. Subversion
+ automatically detects which files have been changed, and in
+ addition 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. While these changes may take place immediately in
+ your working copy, no additions or removals will happen in the
+ repository until you commit them.</para>
- <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
- too.</para>
-
- <para>Here is an overview of the four Subversion subcommands
- that you'll use most often to make tree changes (we'll cover
- <command>svn mkdir</command> later).</para>
+ <para>Here is an overview of the five Subversion subcommands
+ that you'll use most often to make tree changes.</para>
<sidebar>
<title>Versioning symbolic links</title>
@@ -683,28 +555,26 @@
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><command>svn mkdir blort</command></term>
+ <listitem>
+ <para>This command is exactly the same as running
+ <command>mkdir blort; svn add blort</command>. That is,
+ a new directory named <filename>blort</filename> is
+ created and scheduled for addition.</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
<sidebar>
<title>Changing the Repository Without a Working Copy</title>
- <!-- ### 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 -->
- <!-- 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" -->
- <!-- though, so that this sidebar makes more sense. -->
-
- <para>Earlier in this chapter, we said that you have to commit
- any changes that you make in order for the repository to
- reflect these changes. That's not entirely true—there
- <emphasis>are</emphasis> some use cases that immediately
- commit tree changes to the repository. This only happens
- 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>There <emphasis>are</emphasis> some use cases that
+ immediately commit tree changes to the repository. This
+ only happens 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
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
@@ -742,16 +612,16 @@
<sidebar>
<title>Look Ma! No Network!</title>
- <para>All three of these commands (<command>svn
- status</command>, <command>svn diff</command>, and
- <command>svn revert</command>) can be used without any
- network access (assuming, of course, that your repository is
- across the network and not local). This makes it easy to
- manage your changes-in-progress when you are somewhere
- without a network connection, such as travelling on an
- airplane, riding a commuter train or hacking on the
- beach.<footnote><para>And also that you don't have a WAN
- card. Thought you got us, huh?</para></footnote></para>
+ <para>The commands (<command>svn status</command>,
+ <command>svn diff</command>, and <command>svn
+ revert</command>) can be used without any network access
+ (assuming, of course, that your repository is across the
+ network and not local). This makes it easy to manage your
+ changes-in-progress when you are somewhere without a network
+ connection, such as travelling on an airplane, riding a
+ commuter train or hacking on the beach.<footnote><para>And
+ also that you don't have a WAN card. Thought you got us,
+ huh?</para></footnote></para>
<para>Subversion does this by keeping private caches of
pristine versions of each versioned file inside of the
@@ -810,41 +680,24 @@
<para>If you run <command>svn status</command> at the top of
your working copy with no arguments, it will detect all file
- and tree changes you've made. Below are examples of
- the different status codes that <command>svn
+ and tree changes you've made. Below 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>
- L some_dir # svn left a lock in the .svn area of some_dir
-M bar.c # the content in bar.c has local modifications
- M baz.c # baz.c has property but no content modifications
-X 3rd_party # dir is part of an externals definition
-? foo.o # svn doesn't manage foo.o
-! some_dir # svn manages this, but it's missing or incomplete
-~ qux # versioned as file/dir/link, but type has changed
-I .screenrc # svn doesn't manage this, and is set to ignore it
-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 # file is scheduled for deletion
A stuff/loot/bloo.h # file is scheduled for addition
C stuff/loot/lump.c # file has textual conflicts from an update
- C stuff/loot/glub.c # file has property conflicts from an update
-R xyz.c # file is scheduled for replacement
- S stuff/squawk # file or dir has been switched to a branch
- K dog.jpg # file is locked locally; lock-token present
- O cat.jpg # file is locked in the repository by other user
- B bird.jpg # file is locked locally, but lock has been broken
- T fish.jpg # file is locked locally, but lock has been stolen
-
+D stuff/fish.c # file is scheduled for deletion
+M bar.c # the content in bar.c has local modifications
</screen>
<para>In this output format <command>svn status</command>
prints six columns of characters, followed by several
whitespace characters, followed by a file or directory name.
The first column tells the status of a file or directory
- and/or its contents. The codes printed here are:</para>
+ and/or its contents. The codes we listed are:</para>
<variablelist>
@@ -886,149 +739,8 @@
</listitem>
</varlistentry>
- <varlistentry>
- <term><computeroutput>R item</computeroutput></term>
- <listitem>
- <para>The file, directory, or symbolic link
- <filename>item</filename> has been scheduled to
- replace <filename>item</filename> in the repository.
- This means that the object is first deleted, then
- another object of the same name is added, all within a
- single revision.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>X item</computeroutput></term>
- <listitem>
- <para>The directory <filename>item</filename> is
- unversioned, but is related to a Subversion externals
- definition. To find out more about externals
- definitions, see <xref
- linkend="svn.advanced.externals"/>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>? item</computeroutput></term>
- <listitem>
- <para>The file, directory, or symbolic link
- <filename>item</filename> is not under version
- control. You can silence the question marks by either
- passing the <option>--quiet</option>
- (<option>-q</option>) switch to <command>svn
- status</command>, or by setting the
- <literal>svn:ignore</literal> property on the parent
- directory. For more information on ignored files, see
- <xref linkend="svn.advanced.props.special.ignore" />.</para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>! item</computeroutput></term>
- <listitem>
- <para>The file, directory, or symbolic link
- <filename>item</filename> is under version control but
- is missing or somehow incomplete. The item can be
- missing if it's removed using a non-Subversion
- command. In the case of a directory, it can be
- incomplete if you happened to interrupt a checkout or
- update. A quick <command>svn update</command> will
- refetch the file or directory from the repository, or
- <command>svn revert file</command> will restore a
- missing file.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>~ item</computeroutput></term>
- <listitem>
- <para>The file, directory, or symbolic link
- <filename>item</filename> is in the repository as one
- kind of object, but what's actually in your working
- copy is some other kind. For example, Subversion
- might have a file in the repository, but you removed
- the file and created a directory in its place, without
- using the <command>svn delete</command> or
- <command>svn add</command> command.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>I item</computeroutput></term>
- <listitem>
- <para>The file, directory, or symbolic link
- <filename>item</filename> is not under version control,
- and Subversion is configured to ignore it during
- <command>svn add</command>, <command>svn import</command>
- and <command>svn status</command> operations. For more
- information on ignored files, see <xref
- linkend="svn.advanced.props.special.ignore"/>. Note that this
- symbol only shows up if you pass the
- <option>--no-ignore</option> switch to <command>svn
- status</command>—otherwise the file would be
- ignored and not listed at all!</para>
- </listitem>
- </varlistentry>
-
</variablelist>
- <para>The second column tells the status of a file or
- directory's properties (see <xref
- linkend="svn.advanced.props"/> for more information on
- properties). If an <computeroutput>M</computeroutput>
- appears in the second column, then the properties have been
- modified. If a <computeroutput>C</computeroutput> appears
- in that column, then the properties for the file are in a
- state of conflict, which must be resolved before committing
- the changes to the repository. Otherwise a whitespace will
- be printed.</para>
-
- <para>The third column show either whitespace or an
- <computeroutput>L</computeroutput> which means that
- Subversion has locked the directory's
- <filename>.svn</filename> working area. You will see an
- <computeroutput>L</computeroutput> if you run <command>svn
- status</command> in a directory where an <command>svn
- commit</command> is in progress—perhaps when you are
- editing the log message. If Subversion is not running, then
- presumably Subversion was interrupted and the lock needs to
- be cleaned up by running <command>svn cleanup</command>
- (more about that later in this chapter).</para>
-
- <para>The fourth column will show either whitespace or a
- <computeroutput>+</computeroutput> which means that the file
- or directory is scheduled to be added or modified with
- additional attached history. This typically happens when
- you <command>svn move</command> or <command>svn
- copy</command> a file or directory. If you see
- <computeroutput>A +</computeroutput>, this means
- the item is scheduled for addition-with-history. It could
- be a file, or the root of a copied directory.
- <computeroutput>+</computeroutput> means the item is part of
- a subtree scheduled for addition-with-history, i.e. some
- parent got copied, and it's just coming along for the ride.
- <computeroutput>M +</computeroutput> means the
- item is part of a subtree scheduled for
- addition-with-history, <emphasis>and</emphasis> it has local
- modifications. When you commit, first the parent will be
- added-with-history (copied) (which means this file will
- automatically exist in the copy), and then the local
- modifications will be applied to the copy.</para>
-
- <para>The fifth column will show either whitespace or an
- <computeroutput>S</computeroutput>. This signifies that the
- file or directory has been switched from the path of the
- rest of the working copy (using <command>svn
- switch</command>) to a branch.</para>
-
- <para>The sixth column shows information about locks, which is
- further explained in <xref linkend="svn.advanced.locking"/>.
- (These are not the same locks as the ones indicated by an
- <computeroutput>L</computeroutput> in the third column;
- see <xref linkend="svn.advanced.locking.meanings"/>.)</para>
-
<para>If you pass a specific path to <command>svn
status</command>, you get information about that item
alone:</para>
@@ -1093,6 +805,12 @@
commit, or the repository will reject your commit for being
out-of-date. (More on this subject later.)</para>
+ <para><command>svn status</command> displays much more
+ information about the files and directories in your
+ working copy than we've shown here—for an exhaustive
+ description of svn status and its output, see <xref
+ linkend="svn.ref.svn.c.status"/>.</para>
+
</sect3>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
@@ -1111,10 +829,9 @@
pass any flags you'd like to it using the
<option>--extensions</option> switch. For example, to see
local differences in file <filename>foo.c</filename> in
- context output format while ignoring whitespace changes, you
+ context output format while ignoring case differences, you
might run <command>svn diff --diff-cmd /usr/bin/diff
- --extensions '-bc' foo.c</command>.</para>
- </footnote></para>
+ --extensions '-i' foo.c</command>.</para> </footnote></para>
<screen>
$ svn diff
@@ -1190,11 +907,13 @@
<sect2 id="svn.tour.cycle.revert">
<title>Undoing Working Changes</title>
- <para>Now suppose you see the above diff output, and realize
- that your changes to <filename>README</filename> are a
- mistake; perhaps you accidentally typed that text into the
- wrong file in your editor.</para>
+ <para>Suppose while viewing the output of 'svn diff' 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>
@@ -2009,23 +1728,6 @@
$
</screen>
- <para>You're probably wondering why we don't just use
- <command>svn update --revision</command> to update the file to
- the older revision. There are a few reasons why we might
- prefer to use <command>svn cat</command>.</para>
-
- <para>First, you may want to see the differences between two
- revisions of a file using an external diff program (perhaps a
- graphical one, or perhaps your file is in such a format that
- the output of unified diff is nonsensical). In this case,
- 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>
-
- <para>Secondly, it's sometimes just easier to look at an older
- version of a file in its entirety than to look only at the
- differences between it and another revision.</para>
-
</sect3>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
More information about the svnbook-dev
mailing list