Mercurial > public > mercurial-scm > hg

annotate mercurial/help/merge-tools.txt @ 14175:b452abffcb15

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
tests: add pyflakes checking for assigned to but never used
author timeless <timeless@mozdev.org>
date Sun, 01 May 2011 17:27:41 +0200
parents 6eec9d7c6e0f
children 0c4bec9596d8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
1 To merge files Mercurial uses merge tools.
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
2
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
3 A merge tool combines two different versions of a file into a merged
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
4 file. Merge tools are given the two files and the greatest common
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
5 ancestor of the two file versions, so they can determine the changes
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
6 made on both branches.
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
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
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
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
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
14 interactive merge programs make it easier to manually resolve
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
15 conflicting merges, either in a graphical way, or by inserting some
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
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
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
33
12858
6eec9d7c6e0f help: fix typo in merge-tools topic
Wagner Bruna <wbruna@yahoo.com>
parents: 12838
diff changeset
34 There are some internal merge tools which can be used. The internal
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
35 merge tools are:
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
36
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
37 ``internal:merge``
12838
830be2c57626 help: improve wording of internal:merge and internal:fail
Steve Borho <steve@borho.org>
parents: 12826
diff changeset
38 Uses the internal non-interactive simple merge algorithm for merging
830be2c57626 help: improve wording of internal:merge and internal:fail
Steve Borho <steve@borho.org>
parents: 12826
diff changeset
39 files. It will fail if there are any conflicts and leave markers in
830be2c57626 help: improve wording of internal:merge and internal:fail
Steve Borho <steve@borho.org>
parents: 12826
diff changeset
40 the partially merged file.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
41
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
42 ``internal:fail``
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
43 Rather than attempting to merge files that were modified on both
12838
830be2c57626 help: improve wording of internal:merge and internal:fail
Steve Borho <steve@borho.org>
parents: 12826
diff changeset
44 branches, it marks them as unresolved. The resolve command must be
830be2c57626 help: improve wording of internal:merge and internal:fail
Steve Borho <steve@borho.org>
parents: 12826
diff changeset
45 used to resolve these conflicts.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
46
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
47 ``internal:local``
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
48 Uses the local version of files as the merged version.
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
49
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
50 ``internal:other``
12809
e5922564ab01 help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents: 12804
diff changeset
51 Uses the other version of files as the merged version.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
52
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
53 ``internal:prompt``
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
54 Asks the user which of the local or the other version to keep as
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
55 the merged version.
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
56
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
57 ``internal:dump``
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
58 Creates three versions of the files to merge, containing the
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
59 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
60 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
61 ``a.txt``, these files will accordingly be named ``a.txt.local``,
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
62 ``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
63 same directory as ``a.txt``.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
64
12809
e5922564ab01 help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents: 12804
diff changeset
65 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
66 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
67
e5922564ab01 help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents: 12804
diff changeset
68 Choosing a merge tool
e5922564ab01 help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents: 12804
diff changeset
69 """""""""""""""""""""
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
70
12824
93d6559a9cbc merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents: 12809
diff changeset
71 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
72
12824
93d6559a9cbc merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents: 12809
diff changeset
73 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
74 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
75 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
76 the shell.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
77
12824
93d6559a9cbc merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents: 12809
diff changeset
78 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
79 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
80
12824
93d6559a9cbc merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents: 12809
diff changeset
81 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
82 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
83 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
84 merge tool are not considered.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
85
12824
93d6559a9cbc merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents: 12809
diff changeset
86 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
87 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
88 the shell. Otherwise the named tool is used if it is usable.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
89
12824
93d6559a9cbc merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents: 12809
diff changeset
90 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
91 section, the one with the highest priority is used.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
92
12826
4d622380ab39 merge-tools.txt: 6 comes after 5
Patrick Mezard <pmezard@gmail.com>
parents: 12824
diff changeset
93 6. If a program named ``hgmerge`` can be found on the system, it is used - but
12809
e5922564ab01 help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents: 12804
diff changeset
94 it will by default not be used for symlinks and binary files.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
95
12824
93d6559a9cbc merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents: 12809
diff changeset
96 7. If the file to be merged is not binary and is not a symlink, then
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
97 ``internal:merge`` is used.
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
98
12824
93d6559a9cbc merge-tools.txt: fix typos, simplify, renumber from 1.
Patrick Mezard <pmezard@gmail.com>
parents: 12809
diff changeset
99 8. The merge of the file fails and must be resolved before commit.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
100
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
101 .. note::
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
102 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
103 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
104 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
105 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
106 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
107 default unless the file is binary or a symlink.
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
108
12809
e5922564ab01 help: improve merge-tools topic, describe --tool and clarify details
Mads Kiilerich <mads@kiilerich.com>
parents: 12804
diff changeset
109 See the merge-tools and ui sections of hgrc(5) for details on the
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents:
diff changeset
110 configuration of merge tools.