Mercurial > hg
comparison mercurial/help/merge-tools.txt @ 12809:e5922564ab01 stable
help: improve merge-tools topic, describe --tool and clarify details
This doesn't make it simpler, but it makes it more correct.
With help from erikz, mg and abuehl.
author | Mads Kiilerich <mads@kiilerich.com> |
---|---|
date | Fri, 22 Oct 2010 17:08:15 +0200 |
parents | e0e8b123b75e |
children | 93d6559a9cbc |
comparison
equal
deleted
inserted
replaced
12808:74f6531581e8 | 12809:e5922564ab01 |
---|---|
3 A merge tool combines two different versions of a file into a merged | 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 | 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 | 5 ancestor of the two file versions, so they can determine the changes |
6 made on both branches. | 6 made on both branches. |
7 | 7 |
8 The merge tools are used both for :hg:`resolve` and :hg:`merge`. | 8 Merge tools are used both for :hg:`resolve`, :hg:`merge`, :hg:`update`, |
9 :hg:`backout` and in several extensions. | |
9 | 10 |
10 Usually, the merge tool tries to automatically reconcile the files by | 11 Usually, the merge tool tries to automatically reconcile the files by |
11 combining all the non-overlapping changes that occurred separately in | 12 combining all non-overlapping changes that occurred separately in |
12 the two different | 13 the two different evolutions of the same initial base file. Furthermore, some |
13 evolutions of the same initial base file. Furthermore, some | |
14 interactive merge programs make it easier to manually resolve | 14 interactive merge programs make it easier to manually resolve |
15 conflicting merges, either in a graphical way, or by inserting some | 15 conflicting merges, either in a graphical way, or by inserting some |
16 conflict markers. Mercurial does not include any interactive merge | 16 conflict markers. Mercurial does not include any interactive merge |
17 programs but relies on external tools for that. External merge tools | 17 programs but relies on external tools for that. |
18 and their properties and usage is configured in merge-tools section - | 18 |
19 see hgrc(5). | 19 Available merge tools |
20 """"""""""""""""""""" | |
21 | |
22 External merge tools and their properties and usage is configured in the | |
23 merge-tools configuration section - see hgrc(5) - but they can often also 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 can be found on the | |
28 system if it either is an absolute or relative executable path or the name of | |
29 an application in the executable search path. The tool is assumed to be able | |
30 to handle the merge if it can handle symlinks if the file is a symlink, if it | |
31 can handle binary files if the file is binary, and if a GUI is available if the | |
32 tool requires a GUI. | |
20 | 33 |
21 There are a some internal merge tools which can be used. The internal | 34 There are a some internal merge tools which can be used. The internal |
22 merge tools are: | 35 merge tools are: |
23 | 36 |
24 ``internal:merge`` | 37 ``internal:merge`` |
25 Uses the internal non-interactive merge tool for merging files. | 38 Uses the internal non-interactive simple merge algorithm for merging files. |
39 It will fail if there are any conflicts. | |
26 | 40 |
27 ``internal:fail`` | 41 ``internal:fail`` |
28 Rather than attempting to merge files that were modified on both | 42 Rather than attempting to merge files that were modified on both |
29 branches, it marks these files as unresolved. Then the resolve | 43 branches, it marks these files as unresolved. Then the resolve |
30 command must be used to mark files resolved. | 44 command must be used to mark files resolved. |
31 | 45 |
32 ``internal:local`` | 46 ``internal:local`` |
33 Uses the local version of files as the merged version. | 47 Uses the local version of files as the merged version. |
34 | 48 |
35 ``internal:other`` | 49 ``internal:other`` |
36 Uses the remote version of files as the merged version. | 50 Uses the other version of files as the merged version. |
37 | 51 |
38 ``internal:prompt`` | 52 ``internal:prompt`` |
39 Asks the user which of the local or the other version to keep as | 53 Asks the user which of the local or the other version to keep as |
40 the merged version. | 54 the merged version. |
41 | 55 |
45 perform a merge manually. If the file to be merged is named | 59 perform a merge manually. If the file to be merged is named |
46 ``a.txt``, these files will accordingly be named ``a.txt.local``, | 60 ``a.txt``, these files will accordingly be named ``a.txt.local``, |
47 ``a.txt.other`` and ``a.txt.base`` and they will be placed in the | 61 ``a.txt.other`` and ``a.txt.base`` and they will be placed in the |
48 same directory as ``a.txt``. | 62 same directory as ``a.txt``. |
49 | 63 |
50 How Mercurial decides which merge program to use | 64 Internal tools are always available and do not require a GUI but will by default |
65 not handle symlinks or binary files. | |
51 | 66 |
52 1. If the ``HGMERGE`` environment variable is present, it is used. If | 67 Choosing a merge tool |
53 specified it must be either an executable path or the name of an | 68 """"""""""""""""""""" |
54 application in your executable search path. | |
55 | 69 |
56 2. If the filename of the file to be merged matches any of the | 70 Mercurial uses these rules when decing which merge tool to use: |
57 patterns in the merge-patterns configuration section, then the | |
58 corresponding merge tool is used, unless the file to be merged is a | |
59 symlink. Here binary capabilities of the merge tool are not | |
60 considered. | |
61 | 71 |
62 3. If ui.merge is set, it is used. | 72 0. If a tool has been specified with the --tool option to merge or resolve, it |
73 is used. If it is the name of a tool in the merge-tools configuration, its | |
74 configuration is used. Otherwise the specified tool must be executable by | |
75 the shell. | |
63 | 76 |
64 4. If any merge tools are present in the merge-tools configuration | 77 1. If the ``HGMERGE`` environment variable is present, its value is used and |
65 section, and any of the tools can be found on the system, the | 78 must be executable by the shell. |
66 priority settings are used to determine which one to use. Binary, | |
67 symlink and GUI capabilities do also have to match. | |
68 | 79 |
69 5. If a program named ``hgmerge`` exists on the system, it is used. | 80 2. If the filename of the file to be merged matches any of the patterns in the |
81 merge-patterns configuration section, the first usable merge tool | |
82 corresponding to a matching pattern is used. Here, binary capabilities of the | |
83 merge tool are not considered. | |
84 | |
85 3. If ui.merge is set it will be considered next. If the value is not the name | |
86 of a configured tool, the specified value is used and must be executable by | |
87 the shell. Otherwise the named tool is used if it is usable. | |
88 | |
89 4. If any usable merge tools are present in the merge-tools configuration | |
90 section, the one with the higest priority is used. | |
91 | |
92 5. If a program named ``hgmerge`` can be found on the system, it is used - but | |
93 it will by default not be used for symlinks and binary files. | |
70 | 94 |
71 6. If the file to be merged is not binary and is not a symlink, then | 95 6. If the file to be merged is not binary and is not a symlink, then |
72 ``internal:merge`` is used. | 96 ``internal:merge`` is used. |
73 | 97 |
74 7. The merge fails. | 98 7. The merge of the file fails and must be resolved before commit. |
75 | 99 |
76 .. note:: | 100 .. note:: |
77 After selecting a merge program, Mercurial will by default attempt | 101 After selecting a merge program, Mercurial will by default attempt |
78 to merge the files using a simple merge algorithm first, to see if | 102 to merge the files using a simple merge algorithm first. Only if it doesn't |
79 they can be merged without conflicts. Only if there are conflicting | 103 succeed because of conflicting changes Mercurial will actually execute the |
80 changes Mercurial will actually execute the merge program. Whether | 104 merge program. Whether to use the simple merge algorithm first can be |
81 to use the simple merge algorithm first can be controlled by the | 105 controlled by the premerge setting of the merge tool. Premerge is enabled by |
82 premerge setting of the merge tool. Premerge is enabled by default | 106 default unless the file is binary or a symlink. |
83 unless the file is binary or symlink. | |
84 | 107 |
85 See the merge-tools and ui sections of hgrc(5) for details on | 108 See the merge-tools and ui sections of hgrc(5) for details on the |
86 configuration of merge tools. | 109 configuration of merge tools. |