[svnbook commit] r3398 - trunk/src/en/book

[stsp]

Author: stsp
Date: Tue Jan  6 10:00:38 2009
New Revision: 3398

Log:
* src/en/book/ch02-basic-usage.xml
  (svn.tour.treeconflicts): New section that introduces
   the basics of tree conflicts. Still needs to be extended
   with actual examples.

Review and great input by: cmpilato
                           Neels Hofmeyr


Modified:
   trunk/src/en/book/ch02-basic-usage.xml

Modified: trunk/src/en/book/ch02-basic-usage.xml
==============================================================================
--- trunk/src/en/book/ch02-basic-usage.xml	(original)
+++ trunk/src/en/book/ch02-basic-usage.xml	Tue Jan  6 10:00:38 2009
@@ -2284,6 +2284,67 @@
   <!-- ================================================================= -->
   <!-- ================================================================= -->
   <!-- ================================================================= -->
+  <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.</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>
+
+      <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. As with textual
+        conflicts, tree conflicts prevent a commit from being made
+        from the conflicted state, forcing the user 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 -->
+
+  </sect1>
+
+  <!-- ================================================================= -->
+  <!-- ================================================================= -->
+  <!-- ================================================================= -->
   <sect1 id="svn.tour.summary">
     <title>Summary</title>