[svnbook commit] r1213 - in trunk/src/en: . book

[sussman]

Author: sussman
Date: Sat Apr 16 09:51:51 2005
New Revision: 1213

Modified:
   trunk/src/en/TODO
   trunk/src/en/book/ch09.xml
Log:

* src/en/book/ch09.xml 
  (svn switch):  tweak some wording, add a Warning box explaining when
  to use --relocate and when not to.

* src/en/TODO:  add some ideas.



Modified: trunk/src/en/TODO
==============================================================================
--- trunk/src/en/TODO	(original)
+++ trunk/src/en/TODO	Sat Apr 16 09:51:51 2005
@@ -61,8 +61,19 @@
 
 To be fixed by sussman:
 
+
+ch03:
+
+   - "magic rule" of working copy management: you must *always* use
+     'svn' to manipulate files and dirs (cp, mv, add, rm, etc.),
+     *except* for editing.  Editing can be done without telling svn;
+     it notices this later on.
+
 ch04:
 
+  - "magic rule" of the merge command:  "diff and apply".  explain the
+     2 URLs + 1 WC arguments.  compare URLs, apply diff to wc.
+
    - need a giant warning-box about how our lack of 'true renames' can
      be really irritating when doing merges.  The classic case is when
      branchA moves things around, and branch B just changes file text.

Modified: trunk/src/en/book/ch09.xml
==============================================================================
--- trunk/src/en/book/ch09.xml	(original)
+++ trunk/src/en/book/ch09.xml	Sat Apr 16 09:51:51 2005
@@ -3602,21 +3602,21 @@
               copy.</para>
           </tip>
 
-          <para>Sometimes an administrator might change the <quote>base
-            location</quote> of your repository—in other words, the
-            contents of the repository doesn't change, but the main
-            URL used to reach the root of the repository does.  For
-            example, the hostname may change, or the URL schema, or
-            perhaps just the path which leads to the repository.
-            Rather than checkout a new working copy, you can have the
-            <command>svn switch</command> command <quote>rewrite</quote> the
-            beginnings of all the URLs in your working copy.  Use the
-            <option>--relocate</option> command to do the
-            substitution.  No file contents are changed, nor is the
-            repository contacted.  It's similar to running a Perl
-            script over your working copy <filename>.svn/</filename>
-            directories which runs
-            <command>s/OldRoot/NewRoot/</command>.</para>
+          <para>Sometimes an administrator might change the
+            <quote>base location</quote> of your repository—in
+            other words, the contents of the repository doesn't
+            change, but the main URL used to reach the root of the
+            repository does.  For example, the hostname may change,
+            the URL scheme, or any part of the URL which leads to the
+            repository itself.  Rather than checkout a new working
+            copy, you can have the <command>svn switch</command>
+            command <quote>rewrite</quote> the beginnings of all the
+            URLs in your working copy.  Use the
+            <option>--relocate</option> option to do the substitution.
+            No file contents are changed, nor is the repository
+            contacted.  It's similar to running a Perl script over
+            your working copy <filename>.svn/</filename> directories
+            which runs <command>s/OldRoot/NewRoot/</command>.</para>
 
           <screen>
 $ svn checkout file:///tmp/repos test
@@ -3636,6 +3636,29 @@
 At revision 3.
 </screen>
 
+          <warning>
+            <para>Be careful when using the
+            <option>--relocate</option> option.  If you mistype the
+            argument, you might end up creating nonsensical URLs
+            within your working copy that render the whole workspace
+            unusable and tricky to fix.  It's also important to
+            understand exactly when one should or shouldn't use
+            <option>--relocate</option>.  Here's the rule of
+            thumb:</para>
+            
+            <itemizedlist>
+              <listitem><para>If the working copy needs to reflect a
+                  new directory <emphasis>within</emphasis> the
+                  repository, then use just <command>svn
+                  switch</command>.</para></listitem>
+
+              <listitem><para>If the working copy still reflects the
+                  same repository directory, but the location of the
+                  repository itself has changed, then use <command>svn
+                  switch --relocate</command>.</para></listitem>
+            </itemizedlist>
+          </warning>
+
         </refsect1>
       </refentry>