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