← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics/en/conflicts.txt

merge up with HEAD and with test-fixes

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics/en/conflicts.txt
1
 
Conflicts Types
2
 
===============
3
 
 
4
 
Some operations, like merge, revert and pull, modify the contents of your
5
 
working tree.  These modifications are programmatically generated, and so they
6
 
may conflict with the current state of your working tree. Many kinds of changes
7
 
can be combined programmatically, but sometimes only a human can determine the
8
 
right thing to do.  When this happens Bazaar will inform you that there is a
9
 
conflict and then ask you to resolve it.  The command to tell Bazaar a conflict
10
 
is resolved is ``resolve``, but you must perform some action before you can do
11
 
this.
12
 
 
13
 
Each type of conflict is explained below, and the action which must be done to
14
 
resolve the conflict is outlined.
15
 
 
16
 
 
17
 
Text conflicts
18
 
--------------
19
 
 
20
 
Typical message::
21
 
 
22
 
  Text conflict in FILE
23
 
 
24
 
These are produced when a text merge cannot completely reconcile two sets of
25
 
text changes.  Bazaar will emit files for each version with the extensions
26
 
THIS, OTHER, and BASE.  THIS is the version of the file from the target tree,
27
 
i.e. the tree that you are merging changes into.  OTHER is the version that you
28
 
are merging into the target.  BASE is an older version that is used as a basis
29
 
for comparison.
30
 
 
31
 
In the main copy of the file, Bazaar will include all the changes that it
32
 
could reconcile, and any un-reconciled conflicts are surrounded by
33
 
"herringbone" markers like ``<<<<<<<``.
34
 
 
35
 
Say the initial text is "The project leader released it.", and THIS modifies it
36
 
to "Martin Pool released it.", while OTHER modifies it to "The project leader
37
 
released Bazaar."  A conflict would look like this::
38
 
 
39
 
  <<<<<<< TREE
40
 
  Martin Pool released it.
41
 
  =======
42
 
  The project leader released Bazaar.
43
 
  >>>>>>> MERGE-SOURCE
44
 
 
45
 
The correct resolution would be "Martin Pool released Bazaar."
46
 
 
47
 
You can handle text conflicts either by editing the main copy of the file, or
48
 
by invoking external tools on the THIS, OTHER and BASE versions.  It's worth
49
 
mentioning that resolving text conflicts rarely involves picking one set of
50
 
changes over the other.  More often, the two sets of changes must be
51
 
intelligently combined.
52
 
 
53
 
If you edit the main copy, be sure to remove the herringbone markers.  When
54
 
you are done editing, the file should look like it never had a conflict, and be
55
 
ready to commit.
56
 
 
57
 
When you have resolved text conflicts, just run "bzr resolve", and Bazaar will
58
 
auto-detect which conflicts you have resolved.
59
 
 
60
 
Content conflicts
61
 
-----------------
62
 
 
63
 
Typical message::
64
 
 
65
 
  Contents conflict in FILE
66
 
 
67
 
This conflict happens when there are conflicting changes in the target tree and
68
 
the merge source, but the conflicted items are not text files.  They may be
69
 
binary files, or symlinks, or directories.  It can even happen with files that
70
 
are deleted on one side, and modified on the other.
71
 
 
72
 
Like text conflicts, Bazaar will emit THIS, OTHER and BASE files.  (They may be
73
 
regular files, symlinks or directories).  But it will not include a "main copy"
74
 
of the file with herringbone conflict markers.  It will appear that the "main
75
 
copy" has been renamed to THIS or OTHER.
76
 
 
77
 
To resolve this, use "bzr mv" to rename the file back to its normal name, and
78
 
combine the changes manually.  When you are satisfied, run "bzr resolve
79
 
FILE".  Bazaar cannot auto-detect when conflicts of this kind have been
80
 
resolved.
81
 
 
82
 
Duplicate paths
83
 
---------------
84
 
 
85
 
Typical message::
86
 
 
87
 
  Conflict adding file FILE.  Moved existing file to FILE.moved.
88
 
 
89
 
Sometimes Bazaar will attempt to create a file using a pathname that has
90
 
already been used.  The existing file will be renamed to "FILE.moved".  If
91
 
you wish, you can rename either one of these files, or combine their contents.
92
 
When you are satisfied, you can run "bzr resolve FILE" to mark the conflict as
93
 
resolved.
94
 
 
95
 
Unversioned parent
96
 
------------------
97
 
 
98
 
Typical message::
99
 
 
100
 
    Conflict because FILE is not versioned, but has versioned children.
101
 
 
102
 
Sometimes Bazaar will attempt to create a file whose parent directory is not
103
 
versioned.  This happens when the directory has been deleted in the target,
104
 
but has a new child in the source, or vice versa.  In this situation, Bazaar
105
 
will version the parent directory as well.  Resolving this issue depends
106
 
very much on the particular scenario.  You may wish to rename or delete either
107
 
the file or the directory.  When you are satisfied, you can run "bzr resolve
108
 
FILE" to mark the conflict as resolved.
109
 
 
110
 
Missing parent
111
 
--------------
112
 
 
113
 
Typical message::
114
 
 
115
 
  Conflict adding files to FILE.  Created directory.
116
 
 
117
 
This happens when a file has been deleted in the target, but has new children
118
 
in the source.  This is similar to the "unversioned parent" conflict, except
119
 
that the parent directory does not *exist*, instead of just being unversioned.
120
 
In this situation, Bazaar will create the missing parent.  Resolving this issue
121
 
depends very much on the particular scenario.  You may wish to rename or delete
122
 
either the file or the directory.  When you are satisfied, you can run "bzr
123
 
resolve FILE" to mark the conflict as resolved.
124
 
 
125
 
Deleting parent
126
 
---------------
127
 
 
128
 
Typical message::
129
 
 
130
 
  Conflict: can't delete FILE because it is not empty.  Not deleting.
131
 
 
132
 
This is the opposite of "missing parent".  A directory is deleted in the
133
 
source, but has new children in the target.  Bazaar will retain the directory.
134
 
Resolving this issue depends very much on the particular scenario.  You may
135
 
wish to rename or delete either the file or the directory.  When you are
136
 
satisfied, you can run "bzr resolve FILE" to mark the conflict as resolved.
137
 
 
138
 
Path conflict
139
 
-------------
140
 
 
141
 
Typical message::
142
 
 
143
 
  Path conflict: PATH1 / PATH2
144
 
 
145
 
This happens when the source and target have each modified the name or parent
146
 
directory of a file.  Bazaar will use the path elements from the source.  You
147
 
can rename the file, and once you have, run "bzr resolve FILE" to mark the
148
 
conflict as resolved.
149
 
 
150
 
Parent loop
151
 
-----------
152
 
 
153
 
Typical message::
154
 
 
155
 
  Conflict moving FILE into DIRECTORY.  Cancelled move.
156
 
 
157
 
This happens when the source and the target have each moved directories, so
158
 
that, if the change could be applied, a directory would be contained by itself.
159
 
For example::
160
 
 
161
 
  $ bzr init
162
 
  $ bzr mkdir a
163
 
  $ bzr mkdir b
164
 
  $ bzr commit -m "BASE"
165
 
  $ bzr branch . ../other
166
 
  $ bzr mv a b
167
 
  $ bzr commit -m "THIS"
168
 
  $ bzr mv ../other/b ../other/a
169
 
  $ bzr commit ../other -m "OTHER"
170
 
  $ bzr merge ../other
171
 
 
172
 
In this situation, Bazaar will cancel the move, and leave "a" in "b".
173
 
You can rename the directories if you like, and once you have, run "bzr resolve
174
 
FILE" to mark the conflict as resolved.
175
 
 
176
 
Non-directory parent
177
 
--------------------
178
 
 
179
 
Typical message::
180
 
 
181
 
  Conflict: FILE.new is not a directory, but has files in it.
182
 
  Created directory.
183
 
 
184
 
This happens when one side has added files to a directory, and the othe side
185
 
has changed the directory into a file or symlink.  For example::
186
 
 
187
 
  $ bzr init
188
 
  $ bzr mkdir a
189
 
  $ bzr commit -m "BASE"
190
 
  $ bzr branch . ../other
191
 
  $ rmdir a
192
 
  $ touch a
193
 
  $ bzr commit -m "THIS"
194
 
  $ bzr mkdir ../other/a/b
195
 
  $ bzr commit ../other -m "OTHER"
196
 
  $ bzr merge ../other
197
 
 
198
 
 
199
 
MalformedTransform
200
 
------------------
201
 
 
202
 
It is possible (though very rare) for Bazaar to raise a MalformedTransform
203
 
exception.  This means that Bazaar encountered a filesystem conflict that it was
204
 
unable to resolve.  This usually indicates a bug.  Please let us know if you
205
 
encounter this.  Our bug tracker is at https://launchpad.net/bzr/+bugs