[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