hgbook
changeset 156:91a936be78b8
Document merge behaviour with file names.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Mar 12 23:11:26 2007 -0700 (2007-03-12) |
parents | 914babdc99c8 |
children | e49f4451d0e3 |
files | en/Makefile en/daily.tex en/examples/issue29 en/examples/issue29.go.out en/examples/rename.divergent en/examples/rename.divergent.clone.out en/examples/rename.divergent.merge.out en/examples/rename.divergent.rename.anne.out en/examples/rename.divergent.rename.bob.out |
line diff
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