work-in-progress tree conflicts diff, please comment

[Stefan Sperling]

Hi,

the diff below adds an introduction to tree conflicts
to the end of the 'svn.tour' chapter.

It is meant to preceed a step-by-step walkthrough of an
example tree conflict, where an update causes a file which
has local modifications to be moved.

I'd like to get comments on this (wrt content, writing
style, formatting, whatever comes to your mind).

Thanks,
Stefan



Index: book/ch02-basic-usage.xml
===================================================================
--- book/ch02-basic-usage.xml	(revision 3397)
+++ book/ch02-basic-usage.xml	(working copy)
@@ -2284,6 +2284,75 @@
   <!-- ================================================================= -->
   <!-- ================================================================= -->
   <!-- ================================================================= -->
+  <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 one of your collaborators commits changes
+        to a file that you have locally modified, and those changes
+        overlap with your local modifications, Subversion will prevent
+        you from committing that file without first merging the changes
+        made to the file in the repository into your working copy.</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 have decided to do some refactoring of your software
+        project to improve the project's structure, renaming files and
+        moving around directories in the process. If one of the affected
+        files still has local modifications in your working copy, those
+        modifications may need to be applied to the file at its new
+        location.</para>
+
+      <para>Such conflicts manifest themselves at the level of directory
+        tree structure, rather than file content. Conflicts at the level
+        of file content are known as <quote>text conflicts</quote>,
+        whereas conflicts at the level of directory tree structure are
+        known as <quote>tree conflicts</quote>.</para>
+
+      <para>Before 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 tedios) 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>