|
1 To merge files Mercurial uses merge tools. |
|
2 |
|
3 A merge tool combines two different versions of a file into a merged |
|
4 file. Merge tools are given the two files and the greatest common |
|
5 ancestor of the two file versions, so they can determine the changes |
|
6 made on both branches. |
|
7 |
|
8 Merge tools are used both for :hg:`resolve`, :hg:`merge`, :hg:`update`, |
|
9 :hg:`backout` and in several extensions. |
|
10 |
|
11 Usually, the merge tool tries to automatically reconcile the files by |
|
12 combining all non-overlapping changes that occurred separately in |
|
13 the two different evolutions of the same initial base file. Furthermore, some |
|
14 interactive merge programs make it easier to manually resolve |
|
15 conflicting merges, either in a graphical way, or by inserting some |
|
16 conflict markers. Mercurial does not include any interactive merge |
|
17 programs but relies on external tools for that. |
|
18 |
|
19 Available merge tools |
|
20 """"""""""""""""""""" |
|
21 |
|
22 External merge tools and their properties are configured in the |
|
23 merge-tools configuration section - see hgrc(5) - but they can often just |
|
24 be named by their executable. |
|
25 |
|
26 A merge tool is generally usable if its executable can be found on the |
|
27 system and if it can handle the merge. The executable is found if it |
|
28 is an absolute or relative executable path or the name of an |
|
29 application in the executable search path. The tool is assumed to be |
|
30 able to handle the merge if it can handle symlinks if the file is a |
|
31 symlink, if it can handle binary files if the file is binary, and if a |
|
32 GUI is available if the tool requires a GUI. |
|
33 |
|
34 There are some internal merge tools which can be used. The internal |
|
35 merge tools are: |
|
36 |
|
37 ``internal:merge`` |
|
38 Uses the internal non-interactive simple merge algorithm for merging |
|
39 files. It will fail if there are any conflicts and leave markers in |
|
40 the partially merged file. |
|
41 |
|
42 ``internal:fail`` |
|
43 Rather than attempting to merge files that were modified on both |
|
44 branches, it marks them as unresolved. The resolve command must be |
|
45 used to resolve these conflicts. |
|
46 |
|
47 ``internal:local`` |
|
48 Uses the local version of files as the merged version. |
|
49 |
|
50 ``internal:other`` |
|
51 Uses the other version of files as the merged version. |
|
52 |
|
53 ``internal:prompt`` |
|
54 Asks the user which of the local or the other version to keep as |
|
55 the merged version. |
|
56 |
|
57 ``internal:dump`` |
|
58 Creates three versions of the files to merge, containing the |
|
59 contents of local, other and base. These files can then be used to |
|
60 perform a merge manually. If the file to be merged is named |
|
61 ``a.txt``, these files will accordingly be named ``a.txt.local``, |
|
62 ``a.txt.other`` and ``a.txt.base`` and they will be placed in the |
|
63 same directory as ``a.txt``. |
|
64 |
|
65 Internal tools are always available and do not require a GUI but will by default |
|
66 not handle symlinks or binary files. |
|
67 |
|
68 Choosing a merge tool |
|
69 """"""""""""""""""""" |
|
70 |
|
71 Mercurial uses these rules when deciding which merge tool to use: |
|
72 |
|
73 1. If a tool has been specified with the --tool option to merge or resolve, it |
|
74 is used. If it is the name of a tool in the merge-tools configuration, its |
|
75 configuration is used. Otherwise the specified tool must be executable by |
|
76 the shell. |
|
77 |
|
78 2. If the ``HGMERGE`` environment variable is present, its value is used and |
|
79 must be executable by the shell. |
|
80 |
|
81 3. If the filename of the file to be merged matches any of the patterns in the |
|
82 merge-patterns configuration section, the first usable merge tool |
|
83 corresponding to a matching pattern is used. Here, binary capabilities of the |
|
84 merge tool are not considered. |
|
85 |
|
86 4. If ui.merge is set it will be considered next. If the value is not the name |
|
87 of a configured tool, the specified value is used and must be executable by |
|
88 the shell. Otherwise the named tool is used if it is usable. |
|
89 |
|
90 5. If any usable merge tools are present in the merge-tools configuration |
|
91 section, the one with the highest priority is used. |
|
92 |
|
93 6. If a program named ``hgmerge`` can be found on the system, it is used - but |
|
94 it will by default not be used for symlinks and binary files. |
|
95 |
|
96 7. If the file to be merged is not binary and is not a symlink, then |
|
97 ``internal:merge`` is used. |
|
98 |
|
99 8. The merge of the file fails and must be resolved before commit. |
|
100 |
|
101 .. note:: |
|
102 After selecting a merge program, Mercurial will by default attempt |
|
103 to merge the files using a simple merge algorithm first. Only if it doesn't |
|
104 succeed because of conflicting changes Mercurial will actually execute the |
|
105 merge program. Whether to use the simple merge algorithm first can be |
|
106 controlled by the premerge setting of the merge tool. Premerge is enabled by |
|
107 default unless the file is binary or a symlink. |
|
108 |
|
109 See the merge-tools and ui sections of hgrc(5) for details on the |
|
110 configuration of merge tools. |