1.1 --- a/en/Makefile	Mon Mar 12 23:10:32 2007 -0700
     1.2 +++ b/en/Makefile	Mon Mar 12 23:11:26 2007 -0700
     1.3 @@ -62,6 +62,7 @@
     1.4  	hook.msglen \
     1.5  	hook.simple \
     1.6  	hook.ws \
     1.7 +	issue29 \
     1.8  	mq.guards \
     1.9  	mq.qinit-help \
    1.10  	mq.dodiff \
    1.11 @@ -69,6 +70,7 @@
    1.12  	mq.tarball \
    1.13  	mq.tools \
    1.14  	mq.tutorial \
    1.15 +	rename.divergent \
    1.16  	rollback \
    1.17  	template.simple \
    1.18  	template.svnstyle \

     2.1 --- a/en/daily.tex	Mon Mar 12 23:10:32 2007 -0700
     2.2 +++ b/en/daily.tex	Mon Mar 12 23:11:26 2007 -0700
     2.3 @@ -303,11 +303,11 @@
     2.4  propagation of changes happens when you merge after a rename as after
     2.5  a copy.
     2.6  
     2.7 -If I modify a file, and you rename it to a new name, then we merge our
     2.8 -respective changes, my modifications to the file under its original
     2.9 -name will be propagated into the file under its new name.  (This is
    2.10 -something you might expect to ``simply work,'' but not all revision
    2.11 -control systems actually do this.)
    2.12 +If I modify a file, and you rename it to a new name, and then we merge
    2.13 +our respective changes, my modifications to the file under its
    2.14 +original name will be propagated into the file under its new name.
    2.15 +(This is something you might expect to ``simply work,'' but not all
    2.16 +revision control systems actually do this.)
    2.17  
    2.18  Whereas having changes follow a copy is a feature where you can
    2.19  perhaps nod and say ``yes, that might be useful,'' it should be clear
    2.20 @@ -315,6 +315,56 @@
    2.21  this facility, it would simply be too easy for changes to become
    2.22  orphaned when files are renamed.
    2.23  
    2.24 +\subsection{Divergent renames and merging}
    2.25 +
    2.26 +The case of diverging names occurs when two developers start with a
    2.27 +file---let's call it \filename{foo}---in their respective
    2.28 +repositories.
    2.29 +
    2.30 +\interaction{rename.divergent.clone}
    2.31 +Anne renames the file to \filename{bar}.
    2.32 +\interaction{rename.divergent.rename.anne}
    2.33 +Meanwhile, Bob renames it to \filename{quux}.
    2.34 +\interaction{rename.divergent.rename.bob}
    2.35 +
    2.36 +I like to think of this as a conflict because each developer has
    2.37 +expressed different intentions about what the file ought to be named.
    2.38 +
    2.39 +What do you think should happen when they merge their work?
    2.40 +Mercurial's actual behaviour is that it always preserves \emph{both}
    2.41 +names when it merges changesets that contain divergent renames.
    2.42 +\interaction{rename.divergent.merge}
    2.43 +
    2.44 +I personally find this behaviour quite surprising, which is why I
    2.45 +wanted to explicitly mention it here.  I would have expected Mercurial
    2.46 +to prompt me with a three-way choice instead: do I want to keep only
    2.47 +\filename{bar}, only \filename{quux}, or both?
    2.48 +
    2.49 +In practice, when you rename a source file, it is likely that you will
    2.50 +also modify another file (such as a makefile) that knows how to build
    2.51 +the source file.  So what will happen if Anne renames a file and edits
    2.52 +\filename{Makefile} to build it under its new name, while Bob does the
    2.53 +same, but chooses a different name for the file, is that after the
    2.54 +merge, there will be two copies of the source file in the working
    2.55 +directory under different names, \emph{and} a conflict in the section
    2.56 +of the \filename{Makefile} that both Bob and Anne edited.
    2.57 +
    2.58 +This behaviour is considered surprising by other people, too:
    2.59 +see~\bug{455} for details.
    2.60 +
    2.61 +\subsection{Convergent renames and merging}
    2.62 +
    2.63 +Another kind of rename conflict occurs when two people choose to
    2.64 +rename different \emph{source} files to the same \emph{destination}.
    2.65 +In this case, Mercurial runs its normal merge machinery, and lets you
    2.66 +guide it to a suitable resolution.
    2.67 +
    2.68 +\subsection{Other name-related corner cases}
    2.69 +
    2.70 +Mercurial has a longstanding bug in which it fails to handle a merge
    2.71 +where one side has a file with a given name, while another has a
    2.72 +directory with the same name.  This is documented as~\bug{29}.
    2.73 +\interaction{issue29.go}
    2.74  
    2.75  %%% Local Variables: 
    2.76  %%% mode: latex

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/examples/issue29	Mon Mar 12 23:11:26 2007 -0700
     3.3 @@ -0,0 +1,22 @@
     3.4 +#!/bin/bash
     3.5 +
     3.6 +#$ name: go
     3.7 +
     3.8 +hg init issue29
     3.9 +cd issue29
    3.10 +echo a > a
    3.11 +hg ci -Ama
    3.12 +echo b > b
    3.13 +hg ci -Amb
    3.14 +hg up 0
    3.15 +mkdir b
    3.16 +echo b > b/b
    3.17 +hg ci -Amc
    3.18 +
    3.19 +#$ ignore: abort: Is a directory: .*
    3.20 +hg merge
    3.21 +
    3.22 +#$ name:
    3.23 +# This error is expected from the failed merge.
    3.24 +
    3.25 +exit 0

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/examples/issue29.go.out	Mon Mar 12 23:11:26 2007 -0700
     4.3 @@ -0,0 +1,16 @@
     4.4 +$ \textbf{hg init issue29}
     4.5 +$ \textbf{cd issue29}
     4.6 +$ \textbf{echo a > a}
     4.7 +$ \textbf{hg ci -Ama}
     4.8 +adding a
     4.9 +$ \textbf{echo b > b}
    4.10 +$ \textbf{hg ci -Amb}
    4.11 +adding b
    4.12 +$ \textbf{hg up 0}
    4.13 +0 files updated, 0 files merged, 1 files removed, 0 files unresolved
    4.14 +$ \textbf{mkdir b}
    4.15 +$ \textbf{echo b > b/b}
    4.16 +$ \textbf{hg ci -Amc}
    4.17 +adding b/b
    4.18 +$ \textbf{hg merge}
    4.19 +

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/examples/rename.divergent	Mon Mar 12 23:11:26 2007 -0700
     5.3 @@ -0,0 +1,33 @@
     5.4 +#!/bin/bash
     5.5 +
     5.6 +hg init orig
     5.7 +cd orig
     5.8 +echo foo > foo
     5.9 +hg ci -A -m 'First commit'
    5.10 +cd ..
    5.11 +
    5.12 +#$ name: clone
    5.13 +
    5.14 +hg clone orig anne
    5.15 +hg clone orig bob
    5.16 +
    5.17 +#$ name: rename.anne
    5.18 +
    5.19 +cd anne
    5.20 +hg mv foo bar
    5.21 +hg ci -m 'Rename foo to bar'
    5.22 +
    5.23 +#$ name: rename.bob
    5.24 +
    5.25 +cd ../bob
    5.26 +hg mv foo quux
    5.27 +hg ci -m 'Rename foo to quux'
    5.28 +
    5.29 +#$ name: merge
    5.30 +# See http://www.selenic.com/mercurial/bts/issue455
    5.31 +
    5.32 +cd ../orig
    5.33 +hg pull -u ../anne
    5.34 +hg pull ../bob
    5.35 +hg merge
    5.36 +ls

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/examples/rename.divergent.clone.out	Mon Mar 12 23:11:26 2007 -0700
     6.3 @@ -0,0 +1,4 @@
     6.4 +$ \textbf{hg clone orig anne}
     6.5 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved
     6.6 +$ \textbf{hg clone orig bob}
     6.7 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved

     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/en/examples/rename.divergent.merge.out	Mon Mar 12 23:11:26 2007 -0700
     7.3 @@ -0,0 +1,23 @@
     7.4 +# See http://www.selenic.com/mercurial/bts/issue455
     7.5 +$ \textbf{cd ../orig}
     7.6 +$ \textbf{hg pull -u ../anne}
     7.7 +pulling from ../anne
     7.8 +searching for changes
     7.9 +adding changesets
    7.10 +adding manifests
    7.11 +adding file changes
    7.12 +added 1 changesets with 1 changes to 1 files
    7.13 +1 files updated, 0 files merged, 1 files removed, 0 files unresolved
    7.14 +$ \textbf{hg pull ../bob}
    7.15 +pulling from ../bob
    7.16 +searching for changes
    7.17 +adding changesets
    7.18 +adding manifests
    7.19 +adding file changes
    7.20 +added 1 changesets with 1 changes to 1 files (+1 heads)
    7.21 +(run 'hg heads' to see heads, 'hg merge' to merge)
    7.22 +$ \textbf{hg merge}
    7.23 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved
    7.24 +(branch merge, don't forget to commit)
    7.25 +$ \textbf{ls}
    7.26 +bar  quux

     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/en/examples/rename.divergent.rename.anne.out	Mon Mar 12 23:11:26 2007 -0700
     8.3 @@ -0,0 +1,3 @@
     8.4 +$ \textbf{cd anne}
     8.5 +$ \textbf{hg mv foo bar}
     8.6 +$ \textbf{hg ci -m 'Rename foo to bar'}

     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/en/examples/rename.divergent.rename.bob.out	Mon Mar 12 23:11:26 2007 -0700
     9.3 @@ -0,0 +1,3 @@
     9.4 +$ \textbf{cd ../bob}
     9.5 +$ \textbf{hg mv foo quux}
     9.6 +$ \textbf{hg ci -m 'Rename foo to quux'}