[MERGE] Conflict handling docs (was: [RFC] Conflicts handling in status command)

[James Westby]

On (23/07/07 18:43), Aaron Bentley wrote:
> Guillermo Gonzalez wrote:
> > 2007/7/23, Aaron Bentley <aaron.bentley at utoronto.ca>:
> >> Actually, there are eight kinds of conflicts.
> 
> > I wasn't aware of all this kinds.
> 
> Well, that's not really surprising, since it's not documented anywhere.
> 
> Here is a patch to add some documentation about conflict handling.

Thanks Aaron, this looks really good. I have a few comments, but I like
where it is already.

> === added file 'doc/conflicts.txt'
> --- doc/conflicts.txt	1970-01-01 00:00:00 +0000
> +++ doc/conflicts.txt	2007-07-23 22:41:15 +0000
> @@ -0,0 +1,144 @@
> +=================
> +Conflict handling
> +=================
> +
> +Some operations, like merge, revert and pull, modify the contents of your
> +working tree.  But because the changes are programmatically generated, they
> +can come into conflict with the actual state of your working tree.  Many
> +kinds of changes can be combined programmatically, but sometimes only a
> +human can determine the right thing to do.

I don't like starting that sentence with "But". Also it isn't clear to
me what "the changes" refers to. Can I suggest

  Some operations, like merge, revert and pull, modify the contents of your
  working tree.  These modifications are programmatically generated, and
  so they may conflict with the current state of your working tree. Many
  kinds of changes can be combined programmatically, but sometimes only
  a human can determine the right thing to do.  When this happens Bazaar
  will inform you that there is a conflict and then ask you to resolve
  it.  The command to tell Bazaar a conflict is resolved is ``resolve``,
  but you must perform some action before you can do this.

  Each type of conflict is explained below, and the action which must be
  done to resolve the conflict is outlined.

> +
> +Text conflicts
> +==============
> +Typical message::
> +
> +  Text conflict in foo

Here and in the other sections you use "foo" in the message, but refer
to "FILE" in the description, it would be good if they were the same.

> +
> +These are produced when a text merge cannot completely reconcile two sets of
> +text changes.  Bazaar will emit files for each version with the extensions
> +THIS, OTHER, and BASE.  THIS is the version of the file from the target tree.
> +OTHER is the version that you are merging into the target.  BASE is an older
> +version that is used as a basis for comparison.

"THIS" etc. are sometimes quoted, sometimes not, perhaps it should be
consistent where that makes sense.

Also I'm not sure which is the target tree. Perhaps it is not easy to
explain for all cases, but an example might be useful. I guess it is the
file from the tree that you are trying to get to (e.g. the parent in a
pull, but labelling it THIS makes it seem like it was the one that was
in my tree before the command).

> +
> +In the main copy of the file, Bazaar will include all the changes that it
> +could reconcile, and any un-reconciled conflicts are surrounded by
> +"herringbone" markers like ``<<<<<<<``.
> +
> +You can handle text conflicts either by editing the main copy of the file, or
> +by invoking external tools on the THIS, OTHER and BASE versions.  It's worth
> +mentioning that resolving text conflicts rarely involves picking one set of
> +changes over the other.  More often, the two sets of changes must be
> +intelligently combined.
> +
> +When you have resolved text conflicts, just run "bzr resolve", and Bazaar will
> +auto-detect which conflicts you have resolved.

Would it be helpful to have an example conflict, and perhaps show what a
resolved version might look like. Also I think it might be worthwhile to
explain that the conflict markers must be removed, that is that the file
should be left exactly as the user would like it to be committed. This
is probably redundant for anyone that has ever used another system, but
a new user probably wont understand.

> +
> +Content conflicts
> +=================
> +Typical message::
> +
> +  Contents conflict in foo
> +
> +This conflict happens when there are conflicting changes in the target tree and
> +the merge source, but the conflicted items are not text files.  They may be
> +binary files, or symlinks, or directories.  It can even happen with files that
> +are deleted on one side, and modified on the other.
> +
> +Like text conflicts, Bazaar will emit "THIS", "OTHER" and "BASE" files.  But
> +it will not include a "main copy" of the file with herringbone conflict
> +markers.  It will appear that the "main copy" has been renamed to "THIS" or
> +"OTHER".

You say that it emits '"THIS", "OTHER" and "BASE" files' but what if the
conflict is a symlink or a directory?

> +Duplicate Paths
> +===============
> +Sometimes Bazaar will attempt to create a file using a pathname that has
> +already been used.  The existing file will be renamed to "FILE.moved".  If
> +you wish, you can rename either one of these files.  When you are satisfied,
                                                     ^, or combine their
                                                     contents.
> +you can run "bzr resolve FILE" to mark the conflict as resolved.
> +
> +Unversioned Parent
> +==================
> +Typical message::
> +
> +    Conflict because foo is not versioned, but has versioned children.
> +
> +Sometimes Bazaar will attempt to create a file whose parent directory is not
> +versioned.  This happens when the directory has been deleted in the target,
> +but has a new child in the source, or vice versa.  In this situation, Bazaar
> +will version the parent directory as well.  You may rename either file, if you

What does "either file" refer to?

> +like.  When you are satisfied, you can run "bzr resolve FILE" to mark the
> +conflict as resolved.
> +
> +Missing Parent
> +==============
> +This happens when a file has been deleted in the target, but has new children
> +in the source.  This is similar to the "unversioned parent" conflict, except
> +that the parent directory does not *exist*, instead of just being unversioned.
> +In this situation, Bazaar will create the missing parent.  You may rename
> +either file, if you like.  When you are satisfied, you can run "bzr resolve
> +FILE" to mark the conflict as resolved.

"either file" again.

> +
> +Deleting Parent
> +===============
> +This is the opposite of "missing parent".  A directory is deleted in the
> +source, but has new children in the target.  Bazaar will retain the directory.
> +You may rename or delete either file, if you like.  When you are satisfied, you
> +can run "bzr resolve FILE" to mark the conflict as resolved.

And again.

> +Parent Loop
> +===========
> +In this situation, Bazaar will cancel the move, and leave "a" in "b".

Does this not require explicit resolution, but resolution may be desired?
It is probably worth saying that if true.

> +
> +MalformedTransform
> +==================
> +It is possible (though very rare) for Bazaar to raise a MalformedTransform
> +exception.  This means that Bazaar encounted a filesystem conflict that it was
> +unable to resolve.  This usually indicates a bug.  Please let us know if you
> +encounter this.

Worth telling them how they can let us know? Perhaps point them at the
Launchpad file a bug page?

> 
> === modified file 'NEWS'
> --- NEWS	2007-07-23 14:27:42 +0000
> +++ NEWS	2007-07-23 19:37:15 +0000
> @@ -29,6 +29,9 @@
>      * ``bzr status`` now honours FILE parameters for conflict lists
>        (Aaron Bentley, #127606)
>  
> +    * ``bzr checkout`` now honours -r when reconstituting a working tree.
> +      It also honours -r 0.  (Aaron Bentley, #127708)
> +

This looks like the wrong NEWS entry, and a bugfix that isn't for this
merge below.

> === modified file 'bzrlib/builtins.py'
> === modified file 'bzrlib/tests/blackbox/test_checkout.py'
> === modified file 'doc/index.txt'
> --- doc/index.txt	2007-05-08 04:14:01 +0000
> +++ doc/index.txt	2007-07-23 22:41:15 +0000
> @@ -27,6 +27,8 @@
>      The various ways that exist to tell Bazaar your email address for
>      commits.
>  
> +* `Conflict handling <conflicts.htm>`_
> +

Is it worth having a single line description like the other entries?

Thanks,

James

-- 
  James Westby   --    GPG Key ID: B577FE13    --     http://jameswestby.net/
  seccure key - (3+)k7|M*edCX/.A:n*N!>|&7U.L#9E)Tu)T0>AM - secp256r1/nistp256