1
Status of this file: In progress.
3
Purpose of the file: To record the requirements and principles that guide the design of tree-conflict handling. ("Policy" is not a good name for it.)
6
BACKGROUND AND TERMINOLOGY
7
==========================
12
The merge tracking feature helps the client software to determine which changes
13
(revisions) from the source branch to apply to the specified target tree. After
14
that has been determined, the application of one change to one target is where
15
conflict detection becomes involved.
17
At this level of applying changes to the target, merge tracking is irrelevant.
19
MERGE IS DIFF-AND-APPLY
20
-----------------------
22
Subversion's definition of "merging" is to determine the difference between two
23
source trees SOURCE-LEFT and SOURCE-RIGHT, and try to apply that difference to
24
a TARGET tree. The diff that it tries to apply is an arbitrary low-level
25
representation of the overall difference between SOURCE-LEFT and SOURCE-RIGHT,
26
not the series of logically meaningful transformations by which the user
27
originally transformed SOURCE-LEFT into SOURCE-RIGHT.
29
Typically, SOURCE-LEFT is an ancestor of SOURCE-RIGHT in a source branch, but
30
this need not be so. (One effect of the "--ignore-ancestry" option is to force
31
the merge to perform a detailed diff between the sources even if they are not
32
so related, where it would otherwise present the diff as "delete SOURCE-LEFT;
35
The differences are applied to a working copy of the TARGET tree (which may
36
include some local modifications against its base).
38
The degree of success of a merge depends on the degree to which the TARGET tree
39
is similar enough to SOURCE-LEFT for Subversion to be able to match each file
40
or directory involved in the diff to a corresponding file or directory in
41
TARGET. This matching is done purely by path. Where this matching fails, the
42
merge cannot apply that part of the diff. Some of these failures will be
43
defined as "tree conflicts".
49
The use cases (in "use-cases.txt") illustrate some of the cases that are to be
50
handled, but are not a complete set of requirements.
52
The user-level requirements are presented in terms of user-interface actions.
53
Note that the design is formulated and presented in terms of lower-level
54
operations that do not include a "rename" operation.
60
These requirements specify what a tree conflict means, how a tree conflict
61
behaves, and under exactly what conditions a tree conflict is raised. These
62
requirements are intended to apply in all merge, switch and update commands
63
unless otherwise stated.
65
DEFINITION OF A TREE CONFLICT
66
-----------------------------
68
A conflict is the condition that occurs when Subversion cannot apply a source
69
change correctly and with certainty to a corresponding target object. A tree
70
conflict is a kind of conflict that occurs due to a part of the TARGET tree
71
being in some sense "incompatible" with the SOURCE-LEFT tree in kind, name,
72
location, absence or presence.
74
Every tree conflict shall be signaled both by an indication when the conflict
75
occurs and by being marked in the WC in a way that shows up as a conflict in
76
the "svn status" output.
78
The state of conflict shall persist until the user confirms that it has been
79
resolved. The user shall be able to confirm the resolution of each and every
80
conflict individually, and shall also be able to confirm the resolution of all
81
conflicts in a tree with a single command.
83
Confirming the resolution of each and every tree conflict means being
84
able to confirm the resolution of a tree conflict with a single tree conflict
85
victim, even though there might be more than one tree conflict victim
86
in a directory. A tree conflict victim is a file or directory in the tree
87
which is affected by a tree conflict. For example, it might be a file
88
which is deleted during an update operation while carrying local modifications,
89
or it might be a file being blocked during a merge by an unversioned file of
90
the same name. Each tree conflict has only a single victim.
92
Every condition that results in the source diff not being fully applied to the
93
target shall result in either a conflict or an error exit, with a strong
94
preference for a conflict.
96
CONSEQUENCES OF A TREE CONFLICT
97
-------------------------------
99
A commit shall be disallowed if any item considered as part of the commit is
100
marked with a conflict (a tree conflict or any other conflict).
102
A merge or switch or update shall be disallowed if it affects a part of the WC
103
that is marked with a conflict.
108
It is desirable for a tree conflict to be resolved automatically (and thus not
109
to be signaled as a conflict) when there is a way to do so that is clearly what
110
the user wants. This might require some configurable rules. This is not
111
presently a requirement.
113
FAILURE TO GENERATE THE DIFF
114
----------------------------
116
When the diff cannot be completely determined due to read access restrictions
117
in the source repository, tree conflicts shall be handled as defined herein for
118
those parts of the diff that are determined. Rules for whether and how to
119
proceed with an incomplete diff are out of scope of this tree-conflicts
122
FAILURE TO APPLY THE DIFF
123
-------------------------
125
When a part of the diff should apply to a part of the WC that is switched, the
126
rule for whether to apply the diff to this switched subtree or to the natural
127
(unswitched) subtree or to both or to neither is out of scope of this
128
tree-conflicts document, but tree conflict handling shall apply wherever the
131
When a part of the diff cannot be applied, due to not finding a corresponding
132
object or due to an unversioned item being present in the working copy at this
133
path, a conflict is to be signaled. (Previously, in some cases a conflict was
134
raised, in some cases a warning was issued, and in some cases the change was
137
When a part of the diff should apply to a part of the WC that is absent
138
(perhaps due to authz restrictions or due to an intentionally sparse WC), a
139
conflict shall be signaled. ###? This seems to be use case 4, right?
141
LOCAL WC MODIFICATIONS
142
----------------------
144
Correct behaviour with local WC mods in TARGET is conceptually the same as if
145
that uncommitted revision were just another committed revision. (Any necessary
146
differences are to be detailed on delivery.) Correct behaviour with local mods
147
is required for "update". For "switch" and "merge", correct behaviour with
148
local mods is desired but not required for initial delivery.
150
If there is already a conflict in a part of the WC that is to be affected by
151
the merge, then the application of the merge shall be disallowed and no part of
152
the WC shall be altered.
154
### TODO: How can users use 'svn merge' to resolve a tree conflict?
159
When a file is to be deleted or renamed, there shall be a conflict unless the
160
target file is identical to the SOURCE-LEFT file. Identical shall mean
161
identical text and properties except for "svn:mergeinfo".
163
When a directory is to be deleted or renamed, there shall be a conflict unless
164
the target directory is identical to the SOURCE-LEFT directory. Identical shall
165
mean identical properties except for "svn:mergeinfo", and an identical list of
166
children (including their types), and recursively identical directory children
167
and file children according to these definitions of "identical" for directories
168
and for files respectively.
170
### Is that last test (directory being identical) too expensive/impractical to
173
### This is something I've also been thinking about - determining equality
174
of directories may turn out to be a major problem. Would requiring only
175
the direct children to be equal be an acceptable compromise?
added
removed
notes/tree-conflicts/requirements.txt
