work-in-progress tree conflicts diff, please comment

Julian Foad julianfoad at btopenworld.com
Tue Jan 6 07:04:38 CST 2009


On Mon, 2009-01-05 at 21:47 +0100, Stefan Sperling wrote:
> 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>

Good.

But next, I think it would be better in the main flow of text to
describe only how tree conflicts work in Subversion 1.6, and not assume
that readers have started with v1.5 and are interested in the
differences. For those readers (and there will be many, of course) I
would put some "comparison with v1.5" notes in a side-bar.

> +      <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>

All of the above is the sort of thing I would put in the side-bar.

> +      <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

Perhaps saying "giving the user the opportunity" instead of "forcing",
since (a) it gives a better impression and (b) the user does indeed have
the option of doing a recursive "accept=X" to avoid examining the
problems.

> +        state of the working copy for potential problems arising
> +        from the tree conflict, and resolving any such problems
> +        before committing.</para>
> +
> +      <!-- TODO: example -->
> +
> +  </sect1>

- Julian






More information about the svnbook-dev mailing list