hgbook
view en/ch05-daily.xml @ 823:68e59fe2429e
Minor changes to Ch.1.
| author | Giulio@puck |
|---|---|
| date | Sat Aug 15 22:07:42 2009 +0200 (2009-08-15) |
| parents | 477d6a3e5023 |
| children |
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
112 your repository, use the <command role="hg-cmd">hg
113 remove</command> command. This deletes the file, and tells
114 Mercurial to stop tracking it (which will occur at the next
115 commit). A removed file is represented in the output of
116 <command role="hg-cmd">hg status</command> with a
117 <quote><literal>R</literal></quote>.</para>
119 &interaction.daily.files.remove;
121 <para id="x_1b0">After you <command role="hg-cmd">hg remove</command> a file,
122 Mercurial will no longer track changes to that file, even if you
123 recreate a file with the same name in your working directory.
124 If you do recreate a file with the same name and want Mercurial
125 to track the new file, simply <command role="hg-cmd">hg
126 add</command> it. Mercurial will know that the newly added
127 file is not related to the old file of the same name.</para>
129 <sect2>
130 <title>Removing a file does not affect its history</title>
132 <para id="x_1b1">It is important to understand that removing a file has
133 only two effects.</para>
134 <itemizedlist>
135 <listitem><para id="x_1b2">It removes the current version of the file
136 from the working directory.</para>
137 </listitem>
138 <listitem><para id="x_1b3">It stops Mercurial from tracking changes to
139 the file, from the time of the next commit.</para>
140 </listitem></itemizedlist>
141 <para id="x_1b4">Removing a file <emphasis>does not</emphasis> in any way
142 alter the <emphasis>history</emphasis> of the file.</para>
144 <para id="x_1b5">If you update the working directory to a
145 changeset that was committed when it was still tracking a file
146 that you later removed, the file will reappear in the working
147 directory, with the contents it had when you committed that
148 changeset. If you then update the working directory to a
149 later changeset, in which the file had been removed, Mercurial
150 will once again remove the file from the working
151 directory.</para>
152 </sect2>
154 <sect2>
155 <title>Missing files</title>
157 <para id="x_1b6">Mercurial considers a file that you have deleted, but not
158 used <command role="hg-cmd">hg remove</command> to delete, to
159 be <emphasis>missing</emphasis>. A missing file is
160 represented with <quote><literal>!</literal></quote> in the
161 output of <command role="hg-cmd">hg status</command>.
162 Mercurial commands will not generally do anything with missing
163 files.</para>
165 &interaction.daily.files.missing;
167 <para id="x_1b7">If your repository contains a file that <command
168 role="hg-cmd">hg status</command> reports as missing, and
169 you want the file to stay gone, you can run <command
170 role="hg-cmd">hg remove <option
171 role="hg-opt-remove">--after</option></command> at any
172 time later on, to tell Mercurial that you really did mean to
173 remove the file.</para>
175 &interaction.daily.files.remove-after;
177 <para id="x_1b8">On the other hand, if you deleted the missing file by
178 accident, give <command role="hg-cmd">hg revert</command> the
179 name of the file to recover. It will reappear, in unmodified
180 form.</para>
182 &interaction.daily.files.recover-missing;
183 </sect2>
185 <sect2>
186 <title>Aside: why tell Mercurial explicitly to remove a
187 file?</title>
189 <para id="x_1b9">You might wonder why Mercurial requires you to explicitly
190 tell it that you are deleting a file. Early during the
191 development of Mercurial, it let you delete a file however you
192 pleased; Mercurial would notice the absence of the file
193 automatically when you next ran a <command role="hg-cmd">hg
194 commit</command>, and stop tracking the file. In practice,
195 this made it too easy to accidentally remove a file without
196 noticing.</para>
197 </sect2>
199 <sect2>
200 <title>Useful shorthand&emdash;adding and removing files in one
201 step</title>
203 <para id="x_1ba">Mercurial offers a combination command, <command
204 role="hg-cmd">hg addremove</command>, that adds untracked
205 files and marks missing files as removed.</para>
207 &interaction.daily.files.addremove;
209 <para id="x_1bb">The <command role="hg-cmd">hg commit</command> command
210 also provides a <option role="hg-opt-commit">-A</option>
211 option that performs this same add-and-remove, immediately
212 followed by a commit.</para>
214 &interaction.daily.files.commit-addremove;
215 </sect2>
216 </sect1>
218 <sect1 id="chap:daily.copy">
219 <title>Copying files</title>
221 <para id="x_1bc">Mercurial provides a <command role="hg-cmd">hg
222 copy</command> command that lets you make a new copy of a
223 file. When you copy a file using this command, Mercurial makes
224 a record of the fact that the new file is a copy of the original
225 file. It treats these copied files specially when you merge
226 your work with someone else's.</para>
228 <sect2>
229 <title>The results of copying during a merge</title>
231 <para id="x_1bd">What happens during a merge is that changes
232 <quote>follow</quote> a copy. To best illustrate what this
233 means, let's create an example. We'll start with the usual
234 tiny repository that contains a single file.</para>
236 &interaction.daily.copy.init;
238 <para id="x_1be">We need to do some work in
239 parallel, so that we'll have something to merge. So let's
240 clone our repository.</para>
242 &interaction.daily.copy.clone;
244 <para id="x_1bf">Back in our initial repository, let's use the <command
245 role="hg-cmd">hg copy</command> command to make a copy of
246 the first file we created.</para>
248 &interaction.daily.copy.copy;
250 <para id="x_1c0">If we look at the output of the <command role="hg-cmd">hg
251 status</command> command afterwards, the copied file looks
252 just like a normal added file.</para>
254 &interaction.daily.copy.status;
256 <para id="x_1c1">But if we pass the <option
257 role="hg-opt-status">-C</option> option to <command
258 role="hg-cmd">hg status</command>, it prints another line of
259 output: this is the file that our newly-added file was copied
260 <emphasis>from</emphasis>.</para>
262 &interaction.daily.copy.status-copy;
264 <para id="x_1c2">Now, back in the repository we cloned, let's make a change
265 in parallel. We'll add a line of content to the original file
266 that we created.</para>
268 &interaction.daily.copy.other;
270 <para id="x_1c3">Now we have a modified <filename>file</filename> in this
271 repository. When we pull the changes from the first
272 repository, and merge the two heads, Mercurial will propagate
273 the changes that we made locally to <filename>file</filename>
274 into its copy, <filename>new-file</filename>.</para>
276 &interaction.daily.copy.merge;
277 </sect2>
279 <sect2 id="sec:daily:why-copy">
280 <title>Why should changes follow copies?</title>
282 <para id="x_1c4">This behavior&emdash;of changes to a file
283 propagating out to copies of the file&emdash;might seem
284 esoteric, but in most cases it's highly desirable.</para>
286 <para id="x_1c5">First of all, remember that this propagation
287 <emphasis>only</emphasis> happens when you merge. So if you
288 <command role="hg-cmd">hg copy</command> a file, and
289 subsequently modify the original file during the normal course
290 of your work, nothing will happen.</para>
292 <para id="x_1c6">The second thing to know is that modifications will only
293 propagate across a copy as long as the changeset that you're
294 merging changes from <emphasis>hasn't yet seen</emphasis>
295 the copy.</para>
297 <para id="x_1c7">The reason that Mercurial does this is as follows. Let's
298 say I make an important bug fix in a source file, and commit
299 my changes. Meanwhile, you've decided to <command
300 role="hg-cmd">hg copy</command> the file in your repository,
301 without knowing about the bug or having seen the fix, and you
302 have started hacking on your copy of the file.</para>
304 <para id="x_1c8">If you pulled and merged my changes, and Mercurial
305 <emphasis>didn't</emphasis> propagate changes across copies,
306 your new source file would now contain the bug, and unless you
307 knew to propagate the bug fix by hand, the bug would
308 <emphasis>remain</emphasis> in your copy of the file.</para>
310 <para id="x_1c9">By automatically propagating the change that fixed the bug
311 from the original file to the copy, Mercurial prevents this
312 class of problem. To my knowledge, Mercurial is the
313 <emphasis>only</emphasis> revision control system that
314 propagates changes across copies like this.</para>
316 <para id="x_1ca">Once your change history has a record that the copy and
317 subsequent merge occurred, there's usually no further need to
318 propagate changes from the original file to the copied file,
319 and that's why Mercurial only propagates changes across copies
320 at the first merge, and not afterwards.</para>
321 </sect2>
323 <sect2>
324 <title>How to make changes <emphasis>not</emphasis> follow a
325 copy</title>
327 <para id="x_1cb">If, for some reason, you decide that this business of
328 automatically propagating changes across copies is not for
329 you, simply use your system's normal file copy command (on
330 Unix-like systems, that's <command>cp</command>) to make a
331 copy of a file, then <command role="hg-cmd">hg add</command>
332 the new copy by hand. Before you do so, though, please do
333 reread <xref linkend="sec:daily:why-copy"/>, and make
334 an informed
335 decision that this behavior is not appropriate to your
336 specific case.</para>
338 </sect2>
339 <sect2>
340 <title>Behavior of the <command role="hg-cmd">hg copy</command>
341 command</title>
343 <para id="x_1cc">When you use the <command role="hg-cmd">hg copy</command>
344 command, Mercurial makes a copy of each source file as it
345 currently stands in the working directory. This means that if
346 you make some modifications to a file, then <command
347 role="hg-cmd">hg copy</command> it without first having
348 committed those changes, the new copy will also contain the
349 modifications you have made up until that point. (I find this
350 behavior a little counterintuitive, which is why I mention it
351 here.)</para>
353 <para id="x_1cd">The <command role="hg-cmd">hg copy</command>
354 command acts similarly to the Unix <command>cp</command>
355 command (you can use the <command role="hg-cmd">hg
356 cp</command> alias if you prefer). We must supply two or
357 more arguments, of which the last is treated as the
358 <emphasis>destination</emphasis>, and all others are
359 <emphasis>sources</emphasis>.</para>
361 <para id="x_685">If you pass <command role="hg-cmd">hg copy</command> a
362 single file as the source, and the destination does not exist,
363 it creates a new file with that name.</para>
365 &interaction.daily.copy.simple;
367 <para id="x_1ce">If the destination is a directory, Mercurial copies its
368 sources into that directory.</para>
370 &interaction.daily.copy.dir-dest;
372 <para id="x_1cf">Copying a directory is
373 recursive, and preserves the directory structure of the
374 source.</para>
376 &interaction.daily.copy.dir-src;
378 <para id="x_1d0">If the source and destination are both directories, the
379 source tree is recreated in the destination directory.</para>
381 &interaction.daily.copy.dir-src-dest;
383 <para id="x_1d1">As with the <command role="hg-cmd">hg remove</command>
384 command, if you copy a file manually and then want Mercurial
385 to know that you've copied the file, simply use the <option
386 role="hg-opt-copy">--after</option> option to <command
387 role="hg-cmd">hg copy</command>.</para>
389 &interaction.daily.copy.after;
390 </sect2>
391 </sect1>
393 <sect1>
394 <title>Renaming files</title>
396 <para id="x_1d2">It's rather more common to need to rename a file than to
397 make a copy of it. The reason I discussed the <command
398 role="hg-cmd">hg copy</command> command before talking about
399 renaming files is that Mercurial treats a rename in essentially
400 the same way as a copy. Therefore, knowing what Mercurial does
401 when you copy a file tells you what to expect when you rename a
402 file.</para>
404 <para id="x_1d3">When you use the <command role="hg-cmd">hg rename</command>
405 command, Mercurial makes a copy of each source file, then
406 deletes it and marks the file as removed.</para>
408 &interaction.daily.rename.rename;
410 <para id="x_1d4">The <command role="hg-cmd">hg status</command> command shows
411 the newly copied file as added, and the copied-from file as
412 removed.</para>
414 &interaction.daily.rename.status;
416 <para id="x_1d5">As with the results of a <command role="hg-cmd">hg
417 copy</command>, we must use the <option
418 role="hg-opt-status">-C</option> option to <command
419 role="hg-cmd">hg status</command> to see that the added file
420 is really being tracked by Mercurial as a copy of the original,
421 now removed, file.</para>
423 &interaction.daily.rename.status-copy;
425 <para id="x_1d6">As with <command role="hg-cmd">hg remove</command> and
426 <command role="hg-cmd">hg copy</command>, you can tell Mercurial
427 about a rename after the fact using the <option
428 role="hg-opt-rename">--after</option> option. In most other
429 respects, the behavior of the <command role="hg-cmd">hg
430 rename</command> command, and the options it accepts, are
431 similar to the <command role="hg-cmd">hg copy</command>
432 command.</para>
434 <para id="x_686">If you're familiar with the Unix command line, you'll be
435 glad to know that <command role="hg-cmd">hg rename</command>
436 command can be invoked as <command role="hg-cmd">hg
437 mv</command>.</para>
439 <sect2>
440 <title>Renaming files and merging changes</title>
442 <para id="x_1d7">Since Mercurial's rename is implemented as
443 copy-and-remove, the same propagation of changes happens when
444 you merge after a rename as after a copy.</para>
446 <para id="x_1d8">If I modify a file, and you rename it to a new name, and
447 then we merge our respective changes, my modifications to the
448 file under its original name will be propagated into the file
449 under its new name. (This is something you might expect to
450 <quote>simply work,</quote> but not all revision control
451 systems actually do this.)</para>
453 <para id="x_1d9">Whereas having changes follow a copy is a feature where
454 you can perhaps nod and say <quote>yes, that might be
455 useful,</quote> it should be clear that having them follow a
456 rename is definitely important. Without this facility, it
457 would simply be too easy for changes to become orphaned when
458 files are renamed.</para>
459 </sect2>
461 <sect2>
462 <title>Divergent renames and merging</title>
464 <para id="x_1da">The case of diverging names occurs when two developers
465 start with a file&emdash;let's call it
466 <filename>foo</filename>&emdash;in their respective
467 repositories.</para>
469 &interaction.rename.divergent.clone;
471 <para id="x_1db">Anne renames the file to <filename>bar</filename>.</para>
473 &interaction.rename.divergent.rename.anne;
475 <para id="x_1dc">Meanwhile, Bob renames it to
476 <filename>quux</filename>. (Remember that <command
477 role="hg-cmd">hg mv</command> is an alias for <command
478 role="hg-cmd">hg rename</command>.)</para>
480 &interaction.rename.divergent.rename.bob;
482 <para id="x_1dd">I like to think of this as a conflict because each
483 developer has expressed different intentions about what the
484 file ought to be named.</para>
486 <para id="x_1de">What do you think should happen when they merge their
487 work? Mercurial's actual behavior is that it always preserves
488 <emphasis>both</emphasis> names when it merges changesets that
489 contain divergent renames.</para>
491 &interaction.rename.divergent.merge;
493 <para id="x_1df">Notice that while Mercurial warns about the divergent
494 renames, it leaves it up to you to do something about the
495 divergence after the merge.</para>
496 </sect2>
498 <sect2>
499 <title>Convergent renames and merging</title>
501 <para id="x_1e0">Another kind of rename conflict occurs when two people
502 choose to rename different <emphasis>source</emphasis> files
503 to the same <emphasis>destination</emphasis>. In this case,
504 Mercurial runs its normal merge machinery, and lets you guide
505 it to a suitable resolution.</para>
506 </sect2>
508 <sect2>
509 <title>Other name-related corner cases</title>
511 <para id="x_1e1">Mercurial has a longstanding bug in which it fails to
512 handle a merge where one side has a file with a given name,
513 while another has a directory with the same name. This is
514 documented as <ulink role="hg-bug"
515 url="http://www.selenic.com/mercurial/bts/issue29">issue
516 29</ulink>.</para>
518 &interaction.issue29.go;
520 </sect2>
521 </sect1>
523 <sect1>
524 <title>Recovering from mistakes</title>
526 <para id="x_1e2">Mercurial has some useful commands that will help you to
527 recover from some common mistakes.</para>
529 <para id="x_1e3">The <command role="hg-cmd">hg revert</command> command lets
530 you undo changes that you have made to your working directory.
531 For example, if you <command role="hg-cmd">hg add</command> a
532 file by accident, just run <command role="hg-cmd">hg
533 revert</command> with the name of the file you added, and
534 while the file won't be touched in any way, it won't be tracked
535 for adding by Mercurial any longer, either. You can also use
536 <command role="hg-cmd">hg revert</command> to get rid of
537 erroneous changes to a file.</para>
539 <para id="x_1e4">It is helpful to remember that the <command
540 role="hg-cmd">hg revert</command> command is useful for
541 changes that you have not yet committed. Once you've committed
542 a change, if you decide it was a mistake, you can still do
543 something about it, though your options may be more
544 limited.</para>
546 <para id="x_1e5">For more information about the <command
547 role="hg-cmd">hg revert</command> command, and details about
548 how to deal with changes you have already committed, see <xref
549 linkend="chap:undo"/>.</para>
550 </sect1>
552 <sect1>
553 <title>Dealing with tricky merges</title>
555 <para id="x_687">In a complicated or large project, it's not unusual for a
556 merge of two changesets to result in some headaches. Suppose
557 there's a big source file that's been extensively edited by each
558 side of a merge: this is almost inevitably going to result in
559 conflicts, some of which can take a few tries to sort
560 out.</para>
562 <para id="x_688">Let's develop a simple case of this and see how to deal with
563 it. We'll start off with a repository containing one file, and
564 clone it twice.</para>
566 &interaction.ch04-resolve.init;
568 <para id="x_689">In one clone, we'll modify the file in one way.</para>
570 &interaction.ch04-resolve.left;
572 <para id="x_68a">In another, we'll modify the file differently.</para>
574 &interaction.ch04-resolve.right;
576 <para id="x_68b">Next, we'll pull each set of changes into our original
577 repo.</para>
579 &interaction.ch04-resolve.pull;
581 <para id="x_68c">We expect our repository to now contain two heads.</para>
583 &interaction.ch04-resolve.heads;
585 <para id="x_68d">Normally, if we run <command role="hg-cmd">hg
586 merge</command> at this point, it will drop us into a GUI that
587 will let us manually resolve the conflicting edits to
588 <filename>myfile.txt</filename>. However, to simplify things
589 for presentation here, we'd like the merge to fail immediately
590 instead. Here's one way we can do so.</para>
592 &interaction.ch04-resolve.export;
594 <para id="x_68e">We've told Mercurial's merge machinery to run the command
595 <command>false</command> (which, as we desire, fails
596 immediately) if it detects a merge that it can't sort out
597 automatically.</para>
599 <para id="x_68f">If we now fire up <command role="hg-cmd">hg
600 merge</command>, it should grind to a halt and report a
601 failure.</para>
603 &interaction.ch04-resolve.merge;
605 <para id="x_690">Even if we don't notice that the merge failed, Mercurial
606 will prevent us from accidentally committing the result of a
607 failed merge.</para>
609 &interaction.ch04-resolve.cifail;
611 <para id="x_691">When <command role="hg-cmd">hg commit</command> fails in
612 this case, it suggests that we use the unfamiliar <command
613 role="hg-cmd">hg resolve</command> command. As usual,
614 <command role="hg-cmd">hg help resolve</command> will print a
615 helpful synopsis.</para>
617 <sect2>
618 <title>File resolution states</title>
620 <para id="x_692">When a merge occurs, most files will usually remain
621 unmodified. For each file where Mercurial has to do
622 something, it tracks the state of the file.</para>
624 <itemizedlist>
625 <listitem>
626 <para id="x_693">A <emphasis>resolved</emphasis> file has been
627 successfully merged, either automatically by Mercurial or
628 manually with human intervention.</para>
629 </listitem>
630 <listitem>
631 <para id="x_694">An <emphasis>unresolved</emphasis> file was not merged
632 successfully, and needs more attention.</para>
633 </listitem>
634 </itemizedlist>
636 <para id="x_695">If Mercurial sees <emphasis>any</emphasis> file in the
637 unresolved state after a merge, it considers the merge to have
638 failed. Fortunately, we do not need to restart the entire
639 merge from scratch.</para>
641 <para id="x_696">The <option role="hg-opt-resolve">--list</option> or
642 <option role="hg-opt-resolve">-l</option> option to <command
643 role="hg-cmd">hg resolve</command> prints out the state of
644 each merged file.</para>
646 &interaction.ch04-resolve.list;
648 <para id="x_697">In the output from <command role="hg-cmd">hg
649 resolve</command>, a resolved file is marked with
650 <literal>R</literal>, while an unresolved file is marked with
651 <literal>U</literal>. If any files are listed with
652 <literal>U</literal>, we know that an attempt to commit the
653 results of the merge will fail.</para>
654 </sect2>
656 <sect2>
657 <title>Resolving a file merge</title>
659 <para id="x_698">We have several options to move a file from the unresolved
660 into the resolved state. By far the most common is to rerun
661 <command role="hg-cmd">hg resolve</command>. If we pass the
662 names of individual files or directories, it will retry the
663 merges of any unresolved files present in those locations. We
664 can also pass the <option role="hg-opt-resolve">--all</option>
665 or <option role="hg-opt-resolve">-a</option> option, which
666 will retry the merges of <emphasis>all</emphasis> unresolved
667 files.</para>
669 <para id="x_699">Mercurial also lets us modify the resolution state of a
670 file directly. We can manually mark a file as resolved using
671 the <option role="hg-opt-resolve">--mark</option> option, or
672 as unresolved using the <option
673 role="hg-opt-resolve">--unmark</option> option. This allows
674 us to clean up a particularly messy merge by hand, and to keep
675 track of our progress with each file as we go.</para>
676 </sect2>
677 </sect1>
679 <sect1>
680 <title>More useful diffs</title>
682 <para id="x_6c7">The default output of the <command role="hg-cmd">hg
683 diff</command> command is backwards compatible with the
684 regular <command>diff</command> command, but this has some
685 drawbacks.</para>
687 <para id="x_6c8">Consider the case where we use <command role="hg-cmd">hg
688 rename</command> to rename a file.</para>
690 &interaction.ch04-diff.rename.basic;
692 <para id="x_6c9">The output of <command role="hg-cmd">hg diff</command> above
693 obscures the fact that we simply renamed a file. The <command
694 role="hg-cmd">hg diff</command> command accepts an option,
695 <option>--git</option> or <option>-g</option>, to use a newer
696 diff format that displays such information in a more readable
697 form.</para>
699 &interaction.ch04-diff.rename.git;
701 <para id="x_6ca">This option also helps with a case that can otherwise be
702 confusing: a file that appears to be modified according to
703 <command role="hg-cmd">hg status</command>, but for which
704 <command role="hg-cmd">hg diff</command> prints nothing. This
705 situation can arise if we change the file's execute
706 permissions.</para>
708 &interaction.ch04-diff.chmod;
710 <para id="x_6cb">The normal <command>diff</command> command pays no attention
711 to file permissions, which is why <command role="hg-cmd">hg
712 diff</command> prints nothing by default. If we supply it
713 with the <option>-g</option> option, it tells us what really
714 happened.</para>
716 &interaction.ch04-diff.chmod.git;
717 </sect1>
719 <sect1>
720 <title>Which files to manage, and which to avoid</title>
722 <para id="x_6cc">Revision control systems are generally best at managing text
723 files that are written by humans, such as source code, where the
724 files do not change much from one revision to the next. Some
725 centralized revision control systems can also deal tolerably
726 well with binary files, such as bitmap images.</para>
728 <para id="x_6cd">For instance, a game development team will typically manage
729 both its source code and all of its binary assets (e.g. geometry
730 data, textures, map layouts) in a revision control
731 system.</para>
733 <para id="x_6ce">Because it is usually impossible to merge two conflicting
734 modifications to a binary file, centralized systems often
735 provide a file locking mechanism that allow a user to say
736 <quote>I am the only person who can edit this
737 file</quote>.</para>
739 <para id="x_6cf">Compared to a centralized system, a distributed revision
740 control system changes some of the factors that guide decisions
741 over which files to manage and how.</para>
743 <para id="x_6d0">For instance, a distributed revision control system cannot,
744 by its nature, offer a file locking facility. There is thus no
745 built-in mechanism to prevent two people from making conflicting
746 changes to a binary file. If you have a team where several
747 people may be editing binary files frequently, it may not be a
748 good idea to use Mercurial&emdash;or any other distributed
749 revision control system&emdash;to manage those files.</para>
751 <para id="x_6d1">When storing modifications to a file, Mercurial usually
752 saves only the differences between the previous and current
753 versions of the file. For most text files, this is extremely
754 efficient. However, some files (particularly binary files) are
755 laid out in such a way that even a small change to a file's
756 logical content results in many or most of the bytes inside the
757 file changing. For instance, compressed files are particularly
758 susceptible to this. If the differences between each successive
759 version of a file are always large, Mercurial will not be able
760 to store the file's revision history very efficiently. This can
761 affect both local storage needs and the amount of time it takes
762 to clone a repository.</para>
764 <para id="x_6d2">To get an idea of how this could affect you in practice,
765 suppose you want to use Mercurial to manage an OpenOffice
766 document. OpenOffice stores documents on disk as compressed zip
767 files. Edit even a single letter of your document in OpenOffice,
768 and almost every byte in the entire file will change when you
769 save it. Now suppose that file is 2MB in size. Because most of
770 the file changes every time you save, Mercurial will have to
771 store all 2MB of the file every time you commit, even though
772 from your perspective, perhaps only a few words are changing
773 each time. A single frequently-edited file that is not friendly
774 to Mercurial's storage assumptions can easily have an outsized
775 effect on the size of the repository.</para>
777 <para id="x_6d3">Even worse, if both you and someone else edit the OpenOffice
778 document you're working on, there is no useful way to merge your
779 work. In fact, there isn't even a good way to tell what the
780 differences are between your respective changes.</para>
782 <para id="x_6d4">There are thus a few clear recommendations about specific
783 kinds of files to be very careful with.</para>
785 <itemizedlist>
786 <listitem>
787 <para id="x_6d5">Files that are very large and incompressible, e.g. ISO
788 CD-ROM images, will by virtue of sheer size make clones over
789 a network very slow.</para>
790 </listitem>
791 <listitem>
792 <para id="x_6d6">Files that change a lot from one revision to the next
793 may be expensive to store if you edit them frequently, and
794 conflicts due to concurrent edits may be difficult to
795 resolve.</para>
796 </listitem>
797 </itemizedlist>
798 </sect1>
800 <sect1>
801 <title>Backups and mirroring</title>
803 <para id="x_6d7">Since Mercurial maintains a complete copy of history in each
804 clone, everyone who uses Mercurial to collaborate on a project
805 can potentially act as a source of backups in the event of a
806 catastrophe. If a central repository becomes unavailable, you
807 can construct a replacement simply by cloning a copy of the
808 repository from one contributor, and pulling any changes they
809 may not have seen from others.</para>
811 <para id="x_6d8">It is simple to use Mercurial to perform off-site backups
812 and remote mirrors. Set up a periodic job (e.g. via the
813 <command>cron</command> command) on a remote server to pull
814 changes from your master repositories every hour. This will
815 only be tricky in the unlikely case that the number of master
816 repositories you maintain changes frequently, in which case
817 you'll need to do a little scripting to refresh the list of
818 repositories to back up.</para>
820 <para id="x_6d9">If you perform traditional backups of your master
821 repositories to tape or disk, and you want to back up a
822 repository named <filename>myrepo</filename>, use <command>hg
823 clone -U myrepo myrepo.bak</command> to create a
824 clone of <filename>myrepo</filename> before you start your
825 backups. The <option>-U</option> option doesn't check out a
826 working directory after the clone completes, since that would be
827 superfluous and make the backup take longer.</para>
829 <para id="x_6da">If you then back up <filename>myrepo.bak</filename> instead
830 of <filename>myrepo</filename>, you will be guaranteed to have a
831 consistent snapshot of your repository that won't be pushed to
832 by an insomniac developer in mid-backup.</para>
833 </sect1>
834 </chapter>
836 <!--
837 local variables:
838 sgml-parent-document: ("00book.xml" "book" "chapter")
839 end:
840 -->