author | Patrick Mezard <pmezard@gmail.com> |
Sun, 24 Oct 2010 12:55:29 +0200 | |
branch | stable |
changeset 12824 | 93d6559a9cbc |
parent 12809 | e5922564ab01 |
child 12826 | 4d622380ab39 |
permissions | -rw-r--r-- |
12771 | 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 |
||
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
8 |
Merge tools are used both for :hg:`resolve`, :hg:`merge`, :hg:`update`, |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
9 |
:hg:`backout` and in several extensions. |
12771 | 10 |
|
12804
e0e8b123b75e
merge-tools: fixed typos
Martin Geisler <mg@lazybytes.net>
parents:
12771
diff
changeset
|
11 |
Usually, the merge tool tries to automatically reconcile the files by |
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
12 |
combining all non-overlapping changes that occurred separately in |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
13 |
the two different evolutions of the same initial base file. Furthermore, some |
12771 | 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 |
|
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
17 |
programs but relies on external tools for that. |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
18 |
|
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
19 |
Available merge tools |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
20 |
""""""""""""""""""""" |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
21 |
|
12824
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
22 |
External merge tools and their properties are configured in the |
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
23 |
merge-tools configuration section - see hgrc(5) - but they can often just |
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
24 |
be named by their executable. |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
25 |
|
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
26 |
A merge tool is generally usable if its executable can be found on the |
12824
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
27 |
system and if it can handle the merge. The executable is found if it |
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
28 |
is an absolute or relative executable path or the name of an |
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
29 |
application in the executable search path. The tool is assumed to be |
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
30 |
able to handle the merge if it can handle symlinks if the file is a |
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
31 |
symlink, if it can handle binary files if the file is binary, and if a |
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
32 |
GUI is available if the tool requires a GUI. |
12771 | 33 |
|
34 |
There are a some internal merge tools which can be used. The internal |
|
35 |
merge tools are: |
|
36 |
||
37 |
``internal:merge`` |
|
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
38 |
Uses the internal non-interactive simple merge algorithm for merging files. |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
39 |
It will fail if there are any conflicts. |
12771 | 40 |
|
41 |
``internal:fail`` |
|
42 |
Rather than attempting to merge files that were modified on both |
|
43 |
branches, it marks these files as unresolved. Then the resolve |
|
44 |
command must be used to mark files resolved. |
|
45 |
||
46 |
``internal:local`` |
|
47 |
Uses the local version of files as the merged version. |
|
48 |
||
49 |
``internal:other`` |
|
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
50 |
Uses the other version of files as the merged version. |
12771 | 51 |
|
52 |
``internal:prompt`` |
|
53 |
Asks the user which of the local or the other version to keep as |
|
54 |
the merged version. |
|
55 |
||
56 |
``internal:dump`` |
|
57 |
Creates three versions of the files to merge, containing the |
|
58 |
contents of local, other and base. These files can then be used to |
|
12804
e0e8b123b75e
merge-tools: fixed typos
Martin Geisler <mg@lazybytes.net>
parents:
12771
diff
changeset
|
59 |
perform a merge manually. If the file to be merged is named |
e0e8b123b75e
merge-tools: fixed typos
Martin Geisler <mg@lazybytes.net>
parents:
12771
diff
changeset
|
60 |
``a.txt``, these files will accordingly be named ``a.txt.local``, |
12771 | 61 |
``a.txt.other`` and ``a.txt.base`` and they will be placed in the |
12804
e0e8b123b75e
merge-tools: fixed typos
Martin Geisler <mg@lazybytes.net>
parents:
12771
diff
changeset
|
62 |
same directory as ``a.txt``. |
12771 | 63 |
|
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
64 |
Internal tools are always available and do not require a GUI but will by default |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
65 |
not handle symlinks or binary files. |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
66 |
|
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
67 |
Choosing a merge tool |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
68 |
""""""""""""""""""""" |
12771 | 69 |
|
12824
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
70 |
Mercurial uses these rules when deciding which merge tool to use: |
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
71 |
|
12824
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
72 |
1. If a tool has been specified with the --tool option to merge or resolve, it |
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
73 |
is used. If it is the name of a tool in the merge-tools configuration, its |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
74 |
configuration is used. Otherwise the specified tool must be executable by |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
75 |
the shell. |
12771 | 76 |
|
12824
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
77 |
2. If the ``HGMERGE`` environment variable is present, its value is used and |
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
78 |
must be executable by the shell. |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
79 |
|
12824
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
80 |
3. If the filename of the file to be merged matches any of the patterns in the |
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
81 |
merge-patterns configuration section, the first usable merge tool |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
82 |
corresponding to a matching pattern is used. Here, binary capabilities of the |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
83 |
merge tool are not considered. |
12771 | 84 |
|
12824
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
85 |
4. If ui.merge is set it will be considered next. If the value is not the name |
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
86 |
of a configured tool, the specified value is used and must be executable by |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
87 |
the shell. Otherwise the named tool is used if it is usable. |
12771 | 88 |
|
12824
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
89 |
5. If any usable merge tools are present in the merge-tools configuration |
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
90 |
section, the one with the highest priority is used. |
12771 | 91 |
|
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
92 |
5. If a program named ``hgmerge`` can be found on the system, it is used - but |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
93 |
it will by default not be used for symlinks and binary files. |
12771 | 94 |
|
12824
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
95 |
7. If the file to be merged is not binary and is not a symlink, then |
12771 | 96 |
``internal:merge`` is used. |
97 |
||
12824
93d6559a9cbc
merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents:
12809
diff
changeset
|
98 |
8. The merge of the file fails and must be resolved before commit. |
12771 | 99 |
|
100 |
.. note:: |
|
101 |
After selecting a merge program, Mercurial will by default attempt |
|
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
102 |
to merge the files using a simple merge algorithm first. Only if it doesn't |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
103 |
succeed because of conflicting changes Mercurial will actually execute the |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
104 |
merge program. Whether to use the simple merge algorithm first can be |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
105 |
controlled by the premerge setting of the merge tool. Premerge is enabled by |
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
106 |
default unless the file is binary or a symlink. |
12771 | 107 |
|
12809
e5922564ab01
help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents:
12804
diff
changeset
|
108 |
See the merge-tools and ui sections of hgrc(5) for details on the |
12771 | 109 |
configuration of merge tools. |