Debian Codegraph @

doc/html/topic-merge-tools.html

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6 <meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" />
7 <title>Merge Tools</title>
8 <link rel="stylesheet" href="../style.css" type="text/css" />
9 </head>
10 <body>
11 <div class="document" id="merge-tools">
12 <span id="topic-merge-tools"></span>
13 <h1 class="title">Merge Tools</h1>
14
15 <div class="contents htmlonly topic" id="contents">
16 <p class="topic-title"><a class="reference internal" href="#top">Contents</a></p>
17 <ul class="simple">
18 <li><a class="reference internal" href="#available-merge-tools" id="toc-entry-1">Available merge tools</a></li>
19 <li><a class="reference internal" href="#choosing-a-merge-tool" id="toc-entry-2">Choosing a merge tool</a></li>
20 </ul>
21 </div>
22 <p id="mergetool"><span id="mergetools"></span><span id="merge-tools-1"></span>To merge files Mercurial uses merge tools.</p>
23 <p>A merge tool combines two different versions of a file into a merged
24 file. Merge tools are given the two files and the greatest common
25 ancestor of the two file versions, so they can determine the changes
26 made on both branches.</p>
27 <p>Merge tools are used both for <a class="reference external" href="hg-resolve.html"><tt class="docutils literal">hg resolve</tt></a>, <a class="reference external" href="hg-merge.html"><tt class="docutils literal">hg merge</tt></a>, <a class="reference external" href="hg-update.html"><tt class="docutils literal">hg update</tt></a>,
28 <a class="reference external" href="hg-backout.html"><tt class="docutils literal">hg backout</tt></a> and in several extensions.</p>
29 <p>Usually, the merge tool tries to automatically reconcile the files by
30 combining all non-overlapping changes that occurred separately in
31 the two different evolutions of the same initial base file. Furthermore, some
32 interactive merge programs make it easier to manually resolve
33 conflicting merges, either in a graphical way, or by inserting some
34 conflict markers. Mercurial does not include any interactive merge
35 programs but relies on external tools for that.</p>
36 <div class="section" id="available-merge-tools">
37 <h1><a class="toc-backref" href="#contents">Available merge tools</a></h1>
38 <p>External merge tools and their properties are configured in the
39 merge-tools configuration section - see hgrc(5) - but they can often just
40 be named by their executable.</p>
41 <p>A merge tool is generally usable if its executable can be found on the
42 system and if it can handle the merge. The executable is found if it
43 is an absolute or relative executable path or the name of an
44 application in the executable search path. The tool is assumed to be
45 able to handle the merge if it can handle symlinks if the file is a
46 symlink, if it can handle binary files if the file is binary, and if a
47 GUI is available if the tool requires a GUI.</p>
48 <p>There are some internal merge tools which can be used. The internal
49 merge tools are:</p>
50 <dl class="docutils">
51 <dt><tt class="docutils literal">:dump</tt></dt>
52 <dd><p class="first">Creates three versions of the files to merge, containing the
53 contents of local, other and base. These files can then be used to
54 perform a merge manually. If the file to be merged is named
55 <tt class="docutils literal">a.txt</tt>, these files will accordingly be named <tt class="docutils literal">a.txt.local</tt>,
56 <tt class="docutils literal">a.txt.other</tt> and <tt class="docutils literal">a.txt.base</tt> and they will be placed in the
57 same directory as <tt class="docutils literal">a.txt</tt>.</p>
58 <p>This implies premerge. Therefore, files aren't dumped, if premerge
59 runs successfully. Use :forcedump to forcibly write files out.</p>
60 <p class="last">(actual capabilities: binary, symlink)</p>
61 </dd>
62 <dt><tt class="docutils literal">:fail</tt></dt>
63 <dd><p class="first">Rather than attempting to merge files that were modified on both
64 branches, it marks them as unresolved. The resolve command must be
65 used to resolve these conflicts.</p>
66 <p class="last">(actual capabilities: binary, symlink)</p>
67 </dd>
68 <dt><tt class="docutils literal">:forcedump</tt></dt>
69 <dd><p class="first">Creates three versions of the files as same as :dump, but omits premerge.</p>
70 <p class="last">(actual capabilities: binary, symlink)</p>
71 </dd>
72 <dt><tt class="docutils literal">:local</tt></dt>
73 <dd><p class="first">Uses the local <cite>p1()</cite> version of files as the merged version.</p>
74 <p class="last">(actual capabilities: binary, symlink)</p>
75 </dd>
76 <dt><tt class="docutils literal">:merge</tt></dt>
77 <dd>Uses the internal non-interactive simple merge algorithm for merging
78 files. It will fail if there are any conflicts and leave markers in
79 the partially merged file. Markers will have two sections, one for each side
80 of merge.</dd>
81 <dt><tt class="docutils literal"><span class="pre">:merge-local</span></tt></dt>
82 <dd>Like :merge, but resolve all conflicts non-interactively in favor
83 of the local <cite>p1()</cite> changes.</dd>
84 <dt><tt class="docutils literal"><span class="pre">:merge-other</span></tt></dt>
85 <dd>Like :merge, but resolve all conflicts non-interactively in favor
86 of the other <cite>p2()</cite> changes.</dd>
87 <dt><tt class="docutils literal">:merge3</tt></dt>
88 <dd>Uses the internal non-interactive simple merge algorithm for merging
89 files. It will fail if there are any conflicts and leave markers in
90 the partially merged file. Marker will have three sections, one from each
91 side of the merge and one for the base content.</dd>
92 <dt><tt class="docutils literal">:mergediff</tt></dt>
93 <dd>Uses the internal non-interactive simple merge algorithm for merging
94 files. It will fail if there are any conflicts and leave markers in
95 the partially merged file. The marker will have two sections, one with the
96 content from one side of the merge, and one with a diff from the base
97 content to the content on the other side. (experimental)</dd>
98 <dt><tt class="docutils literal">:other</tt></dt>
99 <dd><p class="first">Uses the other <cite>p2()</cite> version of files as the merged version.</p>
100 <p class="last">(actual capabilities: binary, symlink)</p>
101 </dd>
102 <dt><tt class="docutils literal">:prompt</tt></dt>
103 <dd><p class="first">Asks the user which of the local <cite>p1()</cite> or the other <cite>p2()</cite> version to
104 keep as the merged version.</p>
105 <p class="last">(actual capabilities: binary, symlink)</p>
106 </dd>
107 <dt><tt class="docutils literal">:tagmerge</tt></dt>
108 <dd>Uses the internal tag merge algorithm (experimental).</dd>
109 <dt><tt class="docutils literal">:union</tt></dt>
110 <dd>Uses the internal non-interactive simple merge algorithm for merging
111 files. It will use both local and other sides for conflict regions by
112 adding local on top of other.
113 No markers are inserted.</dd>
114 <dt><tt class="docutils literal"><span class="pre">:union-other-first</span></tt></dt>
115 <dd>Like :union, but add other on top of local.</dd>
116 </dl>
117 <p>Internal tools are always available and do not require a GUI but will
118 by default not handle symlinks or binary files. See next section for
119 detail about &quot;actual capabilities&quot; described above.</p>
120 </div>
121 <div class="section" id="choosing-a-merge-tool">
122 <h1><a class="toc-backref" href="#contents">Choosing a merge tool</a></h1>
123 <p>Mercurial uses these rules when deciding which merge tool to use:</p>
124 <ol class="arabic simple">
125 <li>If a tool has been specified with the --tool option to merge or resolve, it
126 is used. If it is the name of a tool in the merge-tools configuration, its
127 configuration is used. Otherwise the specified tool must be executable by
128 the shell.</li>
129 <li>If the <tt class="docutils literal">HGMERGE</tt> environment variable is present, its value is used and
130 must be executable by the shell.</li>
131 <li>If the filename of the file to be merged matches any of the patterns in the
132 merge-patterns configuration section, the first usable merge tool
133 corresponding to a matching pattern is used.</li>
134 <li>If ui.merge is set it will be considered next. If the value is not the name
135 of a configured tool, the specified value is used and must be executable by
136 the shell. Otherwise the named tool is used if it is usable.</li>
137 <li>If any usable merge tools are present in the merge-tools configuration
138 section, the one with the highest priority is used.</li>
139 <li>If a program named <tt class="docutils literal">hgmerge</tt> can be found on the system, it is used - but
140 it will by default not be used for symlinks and binary files.</li>
141 <li>If the file to be merged is not binary and is not a symlink, then
142 internal <tt class="docutils literal">:merge</tt> is used.</li>
143 <li>Otherwise, <tt class="docutils literal">:prompt</tt> is used.</li>
144 </ol>
145 <p>For historical reason, Mercurial treats merge tools as below while
146 examining rules above.</p>
147 <table border="1" class="docutils">
148 <colgroup>
149 <col width="13%" />
150 <col width="47%" />
151 <col width="19%" />
152 <col width="22%" />
153 </colgroup>
154 <thead valign="bottom">
155 <tr><th class="head">step</th>
156 <th class="head">specified via</th>
157 <th class="head">binary</th>
158 <th class="head">symlink</th>
159 </tr>
160 </thead>
161 <tbody valign="top">
162 <tr><td><ol class="first last arabic simple">
163 <li></li>
164 </ol>
165 </td>
166 <td>--tool</td>
167 <td>o/o</td>
168 <td>o/o</td>
169 </tr>
170 <tr><td><ol class="first last arabic simple" start="2">
171 <li></li>
172 </ol>
173 </td>
174 <td>HGMERGE</td>
175 <td>o/o</td>
176 <td>o/o</td>
177 </tr>
178 <tr><td><ol class="first last arabic simple" start="3">
179 <li></li>
180 </ol>
181 </td>
182 <td>merge-patterns</td>
183 <td>o/o(*)</td>
184 <td>x/?(*)</td>
185 </tr>
186 <tr><td><ol class="first last arabic simple" start="4">
187 <li></li>
188 </ol>
189 </td>
190 <td>ui.merge</td>
191 <td>x/?(*)</td>
192 <td>x/?(*)</td>
193 </tr>
194 </tbody>
195 </table>
196 <p>Each capability column indicates Mercurial behavior for
197 internal/external merge tools at examining each rule.</p>
198 <ul class="simple">
199 <li>&quot;o&quot;: &quot;assume that a tool has capability&quot;</li>
200 <li>&quot;x&quot;: &quot;assume that a tool does not have capability&quot;</li>
201 <li>&quot;?&quot;: &quot;check actual capability of a tool&quot;</li>
202 </ul>
203 <p>If <tt class="docutils literal"><span class="pre">merge.strict-capability-check</span></tt> configuration is true, Mercurial
204 checks capabilities of merge tools strictly in (*) cases above (= each
205 capability column becomes &quot;?/?&quot;). It is false by default for backward
206 compatibility.</p>
207 <div class="admonition note">
208 <p class="first admonition-title">Note</p>
209 <p class="last">After selecting a merge program, Mercurial will by default attempt
210 to merge the files using a simple merge algorithm first. Only if it doesn't
211 succeed because of conflicting changes will Mercurial actually execute the
212 merge program. Whether to use the simple merge algorithm first can be
213 controlled by the premerge setting of the merge tool. Premerge is enabled by
214 default unless the file is binary or a symlink.</p>
215 </div>
216 <p>See the merge-tools and ui sections of hgrc(5) for details on the
217 configuration of merge tools.</p>
218 </div>
219 </div>
220 </body>
221 </html>