hgbook
view en/ch04-daily.xml @ 679:06458701453c
Fix up some links to example URLs that aren't actually real.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Tue Apr 21 21:07:20 2009 -0700 (2009-04-21) |
| parents | 3b640272a966 |
| children | 1a0a78e197c3 |
line source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <chapter id="chap:daily">
4 <?dbhtml filename="mercurial-in-daily-use.html"?>
5 <title>Mercurial in daily use</title>
7 <sect1>
8 <title>Telling Mercurial which files to track</title>
10 <para id="x_1a3">Mercurial does not work with files in your repository unless
11 you tell it to manage them. The <command role="hg-cmd">hg
12 status</command> command will tell you which files Mercurial
13 doesn't know about; it uses a
14 <quote><literal>?</literal></quote> to display such
15 files.</para>
17 <para id="x_1a4">To tell Mercurial to track a file, use the <command
18 role="hg-cmd">hg add</command> command. Once you have added a
19 file, the entry in the output of <command role="hg-cmd">hg
20 status</command> for that file changes from
21 <quote><literal>?</literal></quote> to
22 <quote><literal>A</literal></quote>.</para>
24 &interaction.daily.files.add;
26 <para id="x_1a5">After you run a <command role="hg-cmd">hg commit</command>,
27 the files that you added before the commit will no longer be
28 listed in the output of <command role="hg-cmd">hg
29 status</command>. The reason for this is that by default, <command
30 role="hg-cmd">hg status</command> only tells you about
31 <quote>interesting</quote> files&emdash;those that you have (for
32 example) modified, removed, or renamed. If you have a repository
33 that contains thousands of files, you will rarely want to know
34 about files that Mercurial is tracking, but that have not
35 changed. (You can still get this information; we'll return to
36 this later.)</para>
38 <para id="x_1a6">Once you add a file, Mercurial doesn't do anything with it
39 immediately. Instead, it will take a snapshot of the file's
40 state the next time you perform a commit. It will then continue
41 to track the changes you make to the file every time you commit,
42 until you remove the file.</para>
44 <sect2>
45 <title>Explicit versus implicit file naming</title>
47 <para id="x_1a7">A useful behavior that Mercurial has is that if you pass
48 the name of a directory to a command, every Mercurial command
49 will treat this as <quote>I want to operate on every file in
50 this directory and its subdirectories</quote>.</para>
52 &interaction.daily.files.add-dir;
54 <para id="x_1a8">Notice in this example that Mercurial printed
55 the names of the files it added, whereas it didn't do so when
56 we added the file named <filename>myfile.txt</filename> in the
57 earlier example.</para>
59 <para id="x_1a9">What's going on is that in the former case, we explicitly
60 named the file to add on the command line. The assumption
61 that Mercurial makes in such cases is that we know what we
62 are doing, and it doesn't print any output.</para>
64 <para id="x_1aa">However, when we <emphasis>imply</emphasis> the names of
65 files by giving the name of a directory, Mercurial takes the
66 extra step of printing the name of each file that it does
67 something with. This makes it more clear what is happening,
68 and reduces the likelihood of a silent and nasty surprise.
69 This behavior is common to most Mercurial commands.</para>
70 </sect2>
72 <sect2>
73 <title>Mercurial tracks files, not directories</title>
75 <para id="x_1ab">Mercurial does not track directory information. Instead,
76 it tracks the path to a file. Before creating a file, it
77 first creates any missing directory components of the path.
78 After it deletes a file, it then deletes any empty directories
79 that were in the deleted file's path. This sounds like a
80 trivial distinction, but it has one minor practical
81 consequence: it is not possible to represent a completely
82 empty directory in Mercurial.</para>
84 <para id="x_1ac">Empty directories are rarely useful, and there are
85 unintrusive workarounds that you can use to achieve an
86 appropriate effect. The developers of Mercurial thus felt
87 that the complexity that would be required to manage empty
88 directories was not worth the limited benefit this feature
89 would bring.</para>
91 <para id="x_1ad">If you need an empty directory in your repository, there
92 are a few ways to achieve this. One is to create a directory,
93 then <command role="hg-cmd">hg add</command> a
94 <quote>hidden</quote> file to that directory. On Unix-like
95 systems, any file name that begins with a period
96 (<quote><literal>.</literal></quote>) is treated as hidden by
97 most commands and GUI tools. This approach is illustrated
98 below.</para>
100 &interaction.daily.files.hidden;
102 <para id="x_1ae">Another way to tackle a need for an empty directory is to
103 simply create one in your automated build scripts before they
104 will need it.</para>
105 </sect2>
106 </sect1>
108 <sect1>
109 <title>How to stop tracking a file</title>
111 <para id="x_1af">Once you decide that a file no longer belongs in your
112 repository, use the <command role="hg-cmd">hg remove</command>
113 command. This deletes the file, and tells Mercurial to stop
114 tracking it. A removed file is represented in the output of
115 <command role="hg-cmd">hg status</command> with a
116 <quote><literal>R</literal></quote>.</para>
118 &interaction.daily.files.remove;
120 <para id="x_1b0">After you <command role="hg-cmd">hg remove</command> a file,
121 Mercurial will no longer track changes to that file, even if you
122 recreate a file with the same name in your working directory.
123 If you do recreate a file with the same name and want Mercurial
124 to track the new file, simply <command role="hg-cmd">hg
125 add</command> it. Mercurial will know that the newly added
126 file is not related to the old file of the same name.</para>
128 <sect2>
129 <title>Removing a file does not affect its history</title>
131 <para id="x_1b1">It is important to understand that removing a file has
132 only two effects.</para>
133 <itemizedlist>
134 <listitem><para id="x_1b2">It removes the current version of the file
135 from the working directory.</para>
136 </listitem>
137 <listitem><para id="x_1b3">It stops Mercurial from tracking changes to
138 the file, from the time of the next commit.</para>
139 </listitem></itemizedlist>
140 <para id="x_1b4">Removing a file <emphasis>does not</emphasis> in any way
141 alter the <emphasis>history</emphasis> of the file.</para>
143 <para id="x_1b5">If you update the working directory to a
144 changeset that was committed when it was still tracking a file
145 that you later removed, the file will reappear in the working
146 directory, with the contents it had when you committed that
147 changeset. If you then update the working directory to a
148 later changeset, in which the file had been removed, Mercurial
149 will once again remove the file from the working
150 directory.</para>
151 </sect2>
153 <sect2>
154 <title>Missing files</title>
156 <para id="x_1b6">Mercurial considers a file that you have deleted, but not
157 used <command role="hg-cmd">hg remove</command> to delete, to
158 be <emphasis>missing</emphasis>. A missing file is
159 represented with <quote><literal>!</literal></quote> in the
160 output of <command role="hg-cmd">hg status</command>.
161 Mercurial commands will not generally do anything with missing
162 files.</para>
164 &interaction.daily.files.missing;
166 <para id="x_1b7">If your repository contains a file that <command
167 role="hg-cmd">hg status</command> reports as missing, and
168 you want the file to stay gone, you can run <command
169 role="hg-cmd">hg remove <option
170 role="hg-opt-remove">--after</option></command> at any
171 time later on, to tell Mercurial that you really did mean to
172 remove the file.</para>
174 &interaction.daily.files.remove-after;
176 <para id="x_1b8">On the other hand, if you deleted the missing file by
177 accident, give <command role="hg-cmd">hg revert</command> the
178 name of the file to recover. It will reappear, in unmodified
179 form.</para>
181 &interaction.daily.files.recover-missing;
182 </sect2>
184 <sect2>
185 <title>Aside: why tell Mercurial explicitly to remove a
186 file?</title>
188 <para id="x_1b9">You might wonder why Mercurial requires you to explicitly
189 tell it that you are deleting a file. Early during the
190 development of Mercurial, it let you delete a file however you
191 pleased; Mercurial would notice the absence of the file
192 automatically when you next ran a <command role="hg-cmd">hg
193 commit</command>, and stop tracking the file. In practice,
194 this made it too easy to accidentally remove a file without
195 noticing.</para>
196 </sect2>
198 <sect2>
199 <title>Useful shorthand&emdash;adding and removing files in one
200 step</title>
202 <para id="x_1ba">Mercurial offers a combination command, <command
203 role="hg-cmd">hg addremove</command>, that adds untracked
204 files and marks missing files as removed.</para>
206 &interaction.daily.files.addremove;
208 <para id="x_1bb">The <command role="hg-cmd">hg commit</command> command
209 also provides a <option role="hg-opt-commit">-A</option>
210 option that performs this same add-and-remove, immediately
211 followed by a commit.</para>
213 &interaction.daily.files.commit-addremove;
214 </sect2>
215 </sect1>
217 <sect1>
218 <title>Copying files</title>
220 <para id="x_1bc">Mercurial provides a <command role="hg-cmd">hg
221 copy</command> command that lets you make a new copy of a
222 file. When you copy a file using this command, Mercurial makes
223 a record of the fact that the new file is a copy of the original
224 file. It treats these copied files specially when you merge
225 your work with someone else's.</para>
227 <sect2>
228 <title>The results of copying during a merge</title>
230 <para id="x_1bd">What happens during a merge is that changes
231 <quote>follow</quote> a copy. To best illustrate what this
232 means, let's create an example. We'll start with the usual
233 tiny repository that contains a single file.</para>
235 &interaction.daily.copy.init;
237 <para id="x_1be">We need to do some work in
238 parallel, so that we'll have something to merge. So let's
239 clone our repository.</para>
241 &interaction.daily.copy.clone;
243 <para id="x_1bf">Back in our initial repository, let's use the <command
244 role="hg-cmd">hg copy</command> command to make a copy of
245 the first file we created.</para>
247 &interaction.daily.copy.copy;
249 <para id="x_1c0">If we look at the output of the <command role="hg-cmd">hg
250 status</command> command afterwards, the copied file looks
251 just like a normal added file.</para>
253 &interaction.daily.copy.status;
255 <para id="x_1c1">But if we pass the <option
256 role="hg-opt-status">-C</option> option to <command
257 role="hg-cmd">hg status</command>, it prints another line of
258 output: this is the file that our newly-added file was copied
259 <emphasis>from</emphasis>.</para>
261 &interaction.daily.copy.status-copy;
263 <para id="x_1c2">Now, back in the repository we cloned, let's make a change
264 in parallel. We'll add a line of content to the original file
265 that we created.</para>
267 &interaction.daily.copy.other;
269 <para id="x_1c3">Now we have a modified <filename>file</filename> in this
270 repository. When we pull the changes from the first
271 repository, and merge the two heads, Mercurial will propagate
272 the changes that we made locally to <filename>file</filename>
273 into its copy, <filename>new-file</filename>.</para>
275 &interaction.daily.copy.merge;
276 </sect2>
278 <sect2 id="sec:daily:why-copy">
279 <title>Why should changes follow copies?</title>
281 <para id="x_1c4">This behavior&emdash;of changes to a file
282 propagating out to copies of the file&emdash;might seem
283 esoteric, but in most cases it's highly desirable.</para>
285 <para id="x_1c5">First of all, remember that this propagation
286 <emphasis>only</emphasis> happens when you merge. So if you
287 <command role="hg-cmd">hg copy</command> a file, and
288 subsequently modify the original file during the normal course
289 of your work, nothing will happen.</para>
291 <para id="x_1c6">The second thing to know is that modifications will only
292 propagate across a copy as long as the changeset that you're
293 merging changes from <emphasis>hasn't yet seen</emphasis>
294 the copy.</para>
296 <para id="x_1c7">The reason that Mercurial does this is as follows. Let's
297 say I make an important bug fix in a source file, and commit
298 my changes. Meanwhile, you've decided to <command
299 role="hg-cmd">hg copy</command> the file in your repository,
300 without knowing about the bug or having seen the fix, and you
301 have started hacking on your copy of the file.</para>
303 <para id="x_1c8">If you pulled and merged my changes, and Mercurial
304 <emphasis>didn't</emphasis> propagate changes across copies,
305 your new source file would now contain the bug, and unless you
306 knew to propagate the bug fix by hand, the bug would
307 <emphasis>remain</emphasis> in your copy of the file.</para>
309 <para id="x_1c9">By automatically propagating the change that fixed the bug
310 from the original file to the copy, Mercurial prevents this
311 class of problem. To my knowledge, Mercurial is the
312 <emphasis>only</emphasis> revision control system that
313 propagates changes across copies like this.</para>
315 <para id="x_1ca">Once your change history has a record that the copy and
316 subsequent merge occurred, there's usually no further need to
317 propagate changes from the original file to the copied file,
318 and that's why Mercurial only propagates changes across copies
319 at the first merge, and not afterwards.</para>
320 </sect2>
322 <sect2>
323 <title>How to make changes <emphasis>not</emphasis> follow a
324 copy</title>
326 <para id="x_1cb">If, for some reason, you decide that this business of
327 automatically propagating changes across copies is not for
328 you, simply use your system's normal file copy command (on
329 Unix-like systems, that's <command>cp</command>) to make a
330 copy of a file, then <command role="hg-cmd">hg add</command>
331 the new copy by hand. Before you do so, though, please do
332 reread <xref linkend="sec:daily:why-copy"/>, and make
333 an informed
334 decision that this behavior is not appropriate to your
335 specific case.</para>
337 </sect2>
338 <sect2>
339 <title>Behavior of the <command role="hg-cmd">hg copy</command>
340 command</title>
342 <para id="x_1cc">When you use the <command role="hg-cmd">hg copy</command>
343 command, Mercurial makes a copy of each source file as it
344 currently stands in the working directory. This means that if
345 you make some modifications to a file, then <command
346 role="hg-cmd">hg copy</command> it without first having
347 committed those changes, the new copy will also contain the
348 modifications you have made up until that point. (I find this
349 behavior a little counterintuitive, which is why I mention it
350 here.)</para>
352 <para id="x_1cd">The <command role="hg-cmd">hg copy</command>
353 command acts similarly to the Unix <command>cp</command>
354 command (you can use the <command role="hg-cmd">hg
355 cp</command> alias if you prefer). We must supply two or
356 more arguments, of which the last is treated as the
357 <emphasis>destination</emphasis>, and all others are
358 <emphasis>sources</emphasis>.</para>
360 <para id="x_685">If you pass <command role="hg-cmd">hg copy</command> a
361 single file as the source, and the destination does not exist,
362 it creates a new file with that name.</para>
364 &interaction.daily.copy.simple;
366 <para id="x_1ce">If the destination is a directory, Mercurial copies its
367 sources into that directory.</para>
369 &interaction.daily.copy.dir-dest;
371 <para id="x_1cf">Copying a directory is
372 recursive, and preserves the directory structure of the
373 source.</para>
375 &interaction.daily.copy.dir-src;
377 <para id="x_1d0">If the source and destination are both directories, the
378 source tree is recreated in the destination directory.</para>
380 &interaction.daily.copy.dir-src-dest;
382 <para id="x_1d1">As with the <command role="hg-cmd">hg remove</command>
383 command, if you copy a file manually and then want Mercurial
384 to know that you've copied the file, simply use the <option
385 role="hg-opt-copy">--after</option> option to <command
386 role="hg-cmd">hg copy</command>.</para>
388 &interaction.daily.copy.after;
389 </sect2>
390 </sect1>
392 <sect1>
393 <title>Renaming files</title>
395 <para id="x_1d2">It's rather more common to need to rename a file than to
396 make a copy of it. The reason I discussed the <command
397 role="hg-cmd">hg copy</command> command before talking about
398 renaming files is that Mercurial treats a rename in essentially
399 the same way as a copy. Therefore, knowing what Mercurial does
400 when you copy a file tells you what to expect when you rename a
401 file.</para>
403 <para id="x_1d3">When you use the <command role="hg-cmd">hg rename</command>
404 command, Mercurial makes a copy of each source file, then
405 deletes it and marks the file as removed.</para>
407 &interaction.daily.rename.rename;
409 <para id="x_1d4">The <command role="hg-cmd">hg status</command> command shows
410 the newly copied file as added, and the copied-from file as
411 removed.</para>
413 &interaction.daily.rename.status;
415 <para id="x_1d5">As with the results of a <command role="hg-cmd">hg
416 copy</command>, we must use the <option
417 role="hg-opt-status">-C</option> option to <command
418 role="hg-cmd">hg status</command> to see that the added file
419 is really being tracked by Mercurial as a copy of the original,
420 now removed, file.</para>
422 &interaction.daily.rename.status-copy;
424 <para id="x_1d6">As with <command role="hg-cmd">hg remove</command> and
425 <command role="hg-cmd">hg copy</command>, you can tell Mercurial
426 about a rename after the fact using the <option
427 role="hg-opt-rename">--after</option> option. In most other
428 respects, the behavior of the <command role="hg-cmd">hg
429 rename</command> command, and the options it accepts, are
430 similar to the <command role="hg-cmd">hg copy</command>
431 command.</para>
433 <para id="x_686">If you're familiar with the Unix command line, you'll be
434 glad to know that <command role="hg-cmd">hg rename</command>
435 command can be invoked as <command role="hg-cmd">hg
436 mv</command>.</para>
438 <sect2>
439 <title>Renaming files and merging changes</title>
441 <para id="x_1d7">Since Mercurial's rename is implemented as
442 copy-and-remove, the same propagation of changes happens when
443 you merge after a rename as after a copy.</para>
445 <para id="x_1d8">If I modify a file, and you rename it to a new name, and
446 then we merge our respective changes, my modifications to the
447 file under its original name will be propagated into the file
448 under its new name. (This is something you might expect to
449 <quote>simply work,</quote> but not all revision control
450 systems actually do this.)</para>
452 <para id="x_1d9">Whereas having changes follow a copy is a feature where
453 you can perhaps nod and say <quote>yes, that might be
454 useful,</quote> it should be clear that having them follow a
455 rename is definitely important. Without this facility, it
456 would simply be too easy for changes to become orphaned when
457 files are renamed.</para>
458 </sect2>
460 <sect2>
461 <title>Divergent renames and merging</title>
463 <para id="x_1da">The case of diverging names occurs when two developers
464 start with a file&emdash;let's call it
465 <filename>foo</filename>&emdash;in their respective
466 repositories.</para>
468 &interaction.rename.divergent.clone;
470 <para id="x_1db">Anne renames the file to <filename>bar</filename>.</para>
472 &interaction.rename.divergent.rename.anne;
474 <para id="x_1dc">Meanwhile, Bob renames it to
475 <filename>quux</filename>. (Remember that <command
476 role="hg-cmd">hg mv</command> is an alias for <command
477 role="hg-cmd">hg rename</command>.)</para>
479 &interaction.rename.divergent.rename.bob;
481 <para id="x_1dd">I like to think of this as a conflict because each
482 developer has expressed different intentions about what the
483 file ought to be named.</para>
485 <para id="x_1de">What do you think should happen when they merge their
486 work? Mercurial's actual behavior is that it always preserves
487 <emphasis>both</emphasis> names when it merges changesets that
488 contain divergent renames.</para>
490 &interaction.rename.divergent.merge;
492 <para id="x_1df">Notice that while Mercurial warns about the divergent
493 renames, it leaves it up to you to do something about the
494 divergence after the merge.</para>
495 </sect2>
497 <sect2>
498 <title>Convergent renames and merging</title>
500 <para id="x_1e0">Another kind of rename conflict occurs when two people
501 choose to rename different <emphasis>source</emphasis> files
502 to the same <emphasis>destination</emphasis>. In this case,
503 Mercurial runs its normal merge machinery, and lets you guide
504 it to a suitable resolution.</para>
505 </sect2>
507 <sect2>
508 <title>Other name-related corner cases</title>
510 <para id="x_1e1">Mercurial has a longstanding bug in which it fails to
511 handle a merge where one side has a file with a given name,
512 while another has a directory with the same name. This is
513 documented as <ulink role="hg-bug"
514 url="http://www.selenic.com/mercurial/bts/issue29">issue
515 29</ulink>.</para>
517 &interaction.issue29.go;
519 </sect2>
520 </sect1>
522 <sect1>
523 <title>Recovering from mistakes</title>
525 <para id="x_1e2">Mercurial has some useful commands that will help you to
526 recover from some common mistakes.</para>
528 <para id="x_1e3">The <command role="hg-cmd">hg revert</command> command lets
529 you undo changes that you have made to your working directory.
530 For example, if you <command role="hg-cmd">hg add</command> a
531 file by accident, just run <command role="hg-cmd">hg
532 revert</command> with the name of the file you added, and
533 while the file won't be touched in any way, it won't be tracked
534 for adding by Mercurial any longer, either. You can also use
535 <command role="hg-cmd">hg revert</command> to get rid of
536 erroneous changes to a file.</para>
538 <para id="x_1e4">It's good to remember that the <command role="hg-cmd">hg
539 revert</command> command is useful for changes that you have
540 not yet committed. Once you've committed a change, if you
541 decide it was a mistake, you can still do something about it,
542 though your options may be more limited.</para>
544 <para id="x_1e5">For more information about the <command
545 role="hg-cmd">hg revert</command> command, and details about
546 how to deal with changes you have already committed, see <xref
547 linkend="chap:undo"/>.</para>
548 </sect1>
550 <sect1>
551 <title>Dealing with tricky merges</title>
553 <para id="x_687">In a complicated or large project, it's not unusual for a
554 merge of two changesets to result in some headaches. Suppose
555 there's a big source file that's been extensively edited by each
556 side of a merge: this is almost inevitably going to result in
557 conflicts, some of which can take a few tries to sort
558 out.</para>
560 <para id="x_688">Let's develop a simple case of this and see how to deal with
561 it. We'll start off with a repository containing one file, and
562 clone it twice.</para>
564 &interaction.ch04-resolve.init;
566 <para id="x_689">In one clone, we'll modify the file in one way.</para>
568 &interaction.ch04-resolve.left;
570 <para id="x_68a">In another, we'll modify the file differently.</para>
572 &interaction.ch04-resolve.right;
574 <para id="x_68b">Next, we'll pull each set of changes into our original
575 repo.</para>
577 &interaction.ch04-resolve.pull;
579 <para id="x_68c">We expect our repository to now contain two heads.</para>
581 &interaction.ch04-resolve.heads;
583 <para id="x_68d">Normally, if we run <command role="hg-cmd">hg
584 merge</command> at this point, it will drop us into a GUI that
585 will let us manually resolve the conflicting edits to
586 <filename>myfile.txt</filename>. However, to simplify things
587 for presentation here, we'd like the merge to fail immediately
588 instead. Here's one way we can do so.</para>
590 &interaction.ch04-resolve.export;
592 <para id="x_68e">We've told Mercurial's merge machinery to run the command
593 <command>false</command> (which, as we desire, fails
594 immediately) if it detects a merge that it can't sort out
595 automatically.</para>
597 <para id="x_68f">If we now fire up <command role="hg-cmd">hg
598 merge</command>, it should grind to a halt and report a
599 failure.</para>
601 &interaction.ch04-resolve.merge;
603 <para id="x_690">Even if we don't notice that the merge failed, Mercurial
604 will prevent us from accidentally committing the result of a
605 failed merge.</para>
607 &interaction.ch04-resolve.cifail;
609 <para id="x_691">When <command role="hg-cmd">hg commit</command> fails in
610 this case, it suggests that we use the unfamiliar <command
611 role="hg-cmd">hg resolve</command> command. As usual,
612 <command role="hg-cmd">hg help resolve</command> will print a
613 helpful synopsis.</para>
615 <sect2>
616 <title>File resolution states</title>
618 <para id="x_692">When a merge occurs, most files will usually remain
619 unmodified. For each file where Mercurial has to do
620 something, it tracks the state of the file.</para>
622 <itemizedlist>
623 <listitem>
624 <para id="x_693">A <emphasis>resolved</emphasis> file has been
625 successfully merged, either automatically by Mercurial or
626 manually with human intervention.</para>
627 </listitem>
628 <listitem>
629 <para id="x_694">An <emphasis>unresolved</emphasis> file was not merged
630 successfully, and needs more attention.</para>
631 </listitem>
632 </itemizedlist>
634 <para id="x_695">If Mercurial sees <emphasis>any</emphasis> file in the
635 unresolved state after a merge, it considers the merge to have
636 failed. Fortunately, we do not need to restart the entire
637 merge from scratch.</para>
639 <para id="x_696">The <option role="hg-opt-resolve">--list</option> or
640 <option role="hg-opt-resolve">-l</option> option to <command
641 role="hg-cmd">hg resolve</command> prints out the state of
642 each merged file.</para>
644 &interaction.ch04-resolve.list;
646 <para id="x_697">In the output from <command role="hg-cmd">hg
647 resolve</command>, a resolved file is marked with
648 <literal>R</literal>, while an unresolved file is marked with
649 <literal>U</literal>. If any files are listed with
650 <literal>U</literal>, we know that an attempt to commit the
651 results of the merge will fail.</para>
652 </sect2>
654 <sect2>
655 <title>Resolving a file merge</title>
657 <para id="x_698">We have several options to move a file from the unresolved
658 into the resolved state. By far the most common is to rerun
659 <command role="hg-cmd">hg resolve</command>. If we pass the
660 names of individual files or directories, it will retry the
661 merges of any unresolved files present in those locations. We
662 can also pass the <option role="hg-opt-resolve">--all</option>
663 or <option role="hg-opt-resolve">-a</option> option, which
664 will retry the merges of <emphasis>all</emphasis> unresolved
665 files.</para>
667 <para id="x_699">Mercurial also lets us modify the resolution state of a
668 file directly. We can manually mark a file as resolved using
669 the <option role="hg-opt-resolve">--mark</option> option, or
670 as unresolved using the <option
671 role="hg-opt-resolve">--unmark</option> option. This allows
672 us to clean up a particularly messy merge by hand, and to keep
673 track of our progress with each file as we go.</para>
674 </sect2>
675 </sect1>
676 </chapter>
678 <!--
679 local variables:
680 sgml-parent-document: ("00book.xml" "book" "chapter")
681 end:
682 -->