comparison en/ch04-daily.xml @ 683:c838b3975bc6

Add IDs to paragraphs.
author Bryan O'Sullivan <bos@serpentine.com>
date Thu, 19 Mar 2009 21:18:52 -0700
parents 28b5a5befb08
children 4ce9d0754af3
comparison
equal deleted inserted replaced
682:28b5a5befb08 683:c838b3975bc6
5 <title>Mercurial in daily use</title> 5 <title>Mercurial in daily use</title>
6 6
7 <sect1> 7 <sect1>
8 <title>Telling Mercurial which files to track</title> 8 <title>Telling Mercurial which files to track</title>
9 9
10 <para>Mercurial does not work with files in your repository unless 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 11 you tell it to manage them. The <command role="hg-cmd">hg
12 status</command> command will tell you which files Mercurial 12 status</command> command will tell you which files Mercurial
13 doesn't know about; it uses a 13 doesn't know about; it uses a
14 <quote><literal>?</literal></quote> to display such 14 <quote><literal>?</literal></quote> to display such
15 files.</para> 15 files.</para>
16 16
17 <para>To tell Mercurial to track a file, use the <command 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 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 19 file, the entry in the output of <command role="hg-cmd">hg
20 status</command> for that file changes from 20 status</command> for that file changes from
21 <quote><literal>?</literal></quote> to 21 <quote><literal>?</literal></quote> to
22 <quote><literal>A</literal></quote>.</para> 22 <quote><literal>A</literal></quote>.</para>
23 23
24 &interaction.daily.files.add; 24 &interaction.daily.files.add;
25 25
26 <para>After you run a <command role="hg-cmd">hg commit</command>, 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 27 the files that you added before the commit will no longer be
28 listed in the output of <command role="hg-cmd">hg 28 listed in the output of <command role="hg-cmd">hg
29 status</command>. The reason for this is that <command 29 status</command>. The reason for this is that <command
30 role="hg-cmd">hg status</command> only tells you about 30 role="hg-cmd">hg status</command> only tells you about
31 <quote>interesting</quote> files&emdash;those that you have 31 <quote>interesting</quote> files&emdash;those that you have
33 default. If you have a repository that contains thousands of 33 default. If you have a repository that contains thousands of
34 files, you will rarely want to know about files that Mercurial 34 files, you will rarely want to know about files that Mercurial
35 is tracking, but that have not changed. (You can still get this 35 is tracking, but that have not changed. (You can still get this
36 information; we'll return to this later.)</para> 36 information; we'll return to this later.)</para>
37 37
38 <para>Once you add a file, Mercurial doesn't do anything with it 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 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 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, 41 to track the changes you make to the file every time you commit,
42 until you remove the file.</para> 42 until you remove the file.</para>
43 43
44 <sect2> 44 <sect2>
45 <title>Explicit versus implicit file naming</title> 45 <title>Explicit versus implicit file naming</title>
46 46
47 <para>A useful behaviour that Mercurial has is that if you pass 47 <para id="x_1a7">A useful behaviour that Mercurial has is that if you pass
48 the name of a directory to a command, every Mercurial command 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 49 will treat this as <quote>I want to operate on every file in
50 this directory and its subdirectories</quote>.</para> 50 this directory and its subdirectories</quote>.</para>
51 51
52 &interaction.daily.files.add-dir; 52 &interaction.daily.files.add-dir;
53 53
54 <para>Notice in this example that Mercurial printed the names of 54 <para id="x_1a8">Notice in this example that Mercurial printed the names of
55 the files it added, whereas it didn't do so when we added the 55 the files it added, whereas it didn't do so when we added the
56 file named <filename>a</filename> in the earlier 56 file named <filename>a</filename> in the earlier
57 example.</para> 57 example.</para>
58 58
59 <para>What's going on is that in the former case, we explicitly 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, so the assumption 60 named the file to add on the command line, so the assumption
61 that Mercurial makes in such cases is that you know what you 61 that Mercurial makes in such cases is that you know what you
62 were doing, and it doesn't print any output.</para> 62 were doing, and it doesn't print any output.</para>
63 63
64 <para>However, when we <emphasis>imply</emphasis> the names of 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 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 66 extra step of printing the name of each file that it does
67 something with. This makes it more clear what is happening, 67 something with. This makes it more clear what is happening,
68 and reduces the likelihood of a silent and nasty surprise. 68 and reduces the likelihood of a silent and nasty surprise.
69 This behaviour is common to most Mercurial commands.</para> 69 This behaviour is common to most Mercurial commands.</para>
70 70
71 </sect2> 71 </sect2>
72 <sect2> 72 <sect2>
73 <title>Aside: Mercurial tracks files, not directories</title> 73 <title>Aside: Mercurial tracks files, not directories</title>
74 74
75 <para>Mercurial does not track directory information. Instead, 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 76 it tracks the path to a file. Before creating a file, it
77 first creates any missing directory components of the path. 77 first creates any missing directory components of the path.
78 After it deletes a file, it then deletes any empty directories 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 79 that were in the deleted file's path. This sounds like a
80 trivial distinction, but it has one minor practical 80 trivial distinction, but it has one minor practical
81 consequence: it is not possible to represent a completely 81 consequence: it is not possible to represent a completely
82 empty directory in Mercurial.</para> 82 empty directory in Mercurial.</para>
83 83
84 <para>Empty directories are rarely useful, and there are 84 <para id="x_1ac">Empty directories are rarely useful, and there are
85 unintrusive workarounds that you can use to achieve an 85 unintrusive workarounds that you can use to achieve an
86 appropriate effect. The developers of Mercurial thus felt 86 appropriate effect. The developers of Mercurial thus felt
87 that the complexity that would be required to manage empty 87 that the complexity that would be required to manage empty
88 directories was not worth the limited benefit this feature 88 directories was not worth the limited benefit this feature
89 would bring.</para> 89 would bring.</para>
90 90
91 <para>If you need an empty directory in your repository, there 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, 92 are a few ways to achieve this. One is to create a directory,
93 then <command role="hg-cmd">hg add</command> a 93 then <command role="hg-cmd">hg add</command> a
94 <quote>hidden</quote> file to that directory. On Unix-like 94 <quote>hidden</quote> file to that directory. On Unix-like
95 systems, any file name that begins with a period 95 systems, any file name that begins with a period
96 (<quote><literal>.</literal></quote>) is treated as hidden by 96 (<quote><literal>.</literal></quote>) is treated as hidden by
97 most commands and GUI tools. This approach is illustrated 97 most commands and GUI tools. This approach is illustrated
98 below.</para> 98 below.</para>
99 99
100 &interaction.daily.files.hidden; 100 &interaction.daily.files.hidden;
101 101
102 <para>Another way to tackle a need for an empty directory is to 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 103 simply create one in your automated build scripts before they
104 will need it.</para> 104 will need it.</para>
105 105
106 </sect2> 106 </sect2>
107 </sect1> 107 </sect1>
108 <sect1> 108 <sect1>
109 <title>How to stop tracking a file</title> 109 <title>How to stop tracking a file</title>
110 110
111 <para>Once you decide that a file no longer belongs in your 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> 112 repository, use the <command role="hg-cmd">hg remove</command>
113 command; this deletes the file, and tells Mercurial to stop 113 command; this deletes the file, and tells Mercurial to stop
114 tracking it. A removed file is represented in the output of 114 tracking it. A removed file is represented in the output of
115 <command role="hg-cmd">hg status</command> with a 115 <command role="hg-cmd">hg status</command> with a
116 <quote><literal>R</literal></quote>.</para> 116 <quote><literal>R</literal></quote>.</para>
117 117
118 &interaction.daily.files.remove; 118 &interaction.daily.files.remove;
119 119
120 <para>After you <command role="hg-cmd">hg remove</command> a file, 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 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. 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 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 124 to track the new file, simply <command role="hg-cmd">hg
125 add</command> it. Mercurial will know that the newly added 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> 126 file is not related to the old file of the same name.</para>
127 127
128 <sect2> 128 <sect2>
129 <title>Removing a file does not affect its history</title> 129 <title>Removing a file does not affect its history</title>
130 130
131 <para>It is important to understand that removing a file has 131 <para id="x_1b1">It is important to understand that removing a file has
132 only two effects.</para> 132 only two effects.</para>
133 <itemizedlist> 133 <itemizedlist>
134 <listitem><para>It removes the current version of the file 134 <listitem><para id="x_1b2">It removes the current version of the file
135 from the working directory.</para> 135 from the working directory.</para>
136 </listitem> 136 </listitem>
137 <listitem><para>It stops Mercurial from tracking changes to 137 <listitem><para id="x_1b3">It stops Mercurial from tracking changes to
138 the file, from the time of the next commit.</para> 138 the file, from the time of the next commit.</para>
139 </listitem></itemizedlist> 139 </listitem></itemizedlist>
140 <para>Removing a file <emphasis>does not</emphasis> in any way 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> 141 alter the <emphasis>history</emphasis> of the file.</para>
142 142
143 <para>If you update the working directory to a changeset in 143 <para id="x_1b5">If you update the working directory to a changeset in
144 which a file that you have removed was still tracked, it will 144 which a file that you have removed was still tracked, it will
145 reappear in the working directory, with the contents it had 145 reappear in the working directory, with the contents it had
146 when you committed that changeset. If you then update the 146 when you committed that changeset. If you then update the
147 working directory to a later changeset, in which the file had 147 working directory to a later changeset, in which the file had
148 been removed, Mercurial will once again remove the file from 148 been removed, Mercurial will once again remove the file from
150 150
151 </sect2> 151 </sect2>
152 <sect2> 152 <sect2>
153 <title>Missing files</title> 153 <title>Missing files</title>
154 154
155 <para>Mercurial considers a file that you have deleted, but not 155 <para id="x_1b6">Mercurial considers a file that you have deleted, but not
156 used <command role="hg-cmd">hg remove</command> to delete, to 156 used <command role="hg-cmd">hg remove</command> to delete, to
157 be <emphasis>missing</emphasis>. A missing file is 157 be <emphasis>missing</emphasis>. A missing file is
158 represented with <quote><literal>!</literal></quote> in the 158 represented with <quote><literal>!</literal></quote> in the
159 output of <command role="hg-cmd">hg status</command>. 159 output of <command role="hg-cmd">hg status</command>.
160 Mercurial commands will not generally do anything with missing 160 Mercurial commands will not generally do anything with missing
161 files.</para> 161 files.</para>
162 162
163 &interaction.daily.files.missing; 163 &interaction.daily.files.missing;
164 164
165 <para>If your repository contains a file that <command 165 <para id="x_1b7">If your repository contains a file that <command
166 role="hg-cmd">hg status</command> reports as missing, and 166 role="hg-cmd">hg status</command> reports as missing, and
167 you want the file to stay gone, you can run <command 167 you want the file to stay gone, you can run <command
168 role="hg-cmd">hg remove <option 168 role="hg-cmd">hg remove <option
169 role="hg-opt-remove">--after</option></command> at any 169 role="hg-opt-remove">--after</option></command> at any
170 time later on, to tell Mercurial that you really did mean to 170 time later on, to tell Mercurial that you really did mean to
171 remove the file.</para> 171 remove the file.</para>
172 172
173 &interaction.daily.files.remove-after; 173 &interaction.daily.files.remove-after;
174 174
175 <para>On the other hand, if you deleted the missing file by 175 <para id="x_1b8">On the other hand, if you deleted the missing file by
176 accident, give <command role="hg-cmd">hg revert</command> the 176 accident, give <command role="hg-cmd">hg revert</command> the
177 name of the file to recover. It will reappear, in unmodified 177 name of the file to recover. It will reappear, in unmodified
178 form.</para> 178 form.</para>
179 179
180 &interaction.daily.files.recover-missing; 180 &interaction.daily.files.recover-missing;
182 </sect2> 182 </sect2>
183 <sect2> 183 <sect2>
184 <title>Aside: why tell Mercurial explicitly to remove a 184 <title>Aside: why tell Mercurial explicitly to remove a
185 file?</title> 185 file?</title>
186 186
187 <para>You might wonder why Mercurial requires you to explicitly 187 <para id="x_1b9">You might wonder why Mercurial requires you to explicitly
188 tell it that you are deleting a file. Early during the 188 tell it that you are deleting a file. Early during the
189 development of Mercurial, it let you delete a file however you 189 development of Mercurial, it let you delete a file however you
190 pleased; Mercurial would notice the absence of the file 190 pleased; Mercurial would notice the absence of the file
191 automatically when you next ran a <command role="hg-cmd">hg 191 automatically when you next ran a <command role="hg-cmd">hg
192 commit</command>, and stop tracking the file. In practice, 192 commit</command>, and stop tracking the file. In practice,
196 </sect2> 196 </sect2>
197 <sect2> 197 <sect2>
198 <title>Useful shorthand&emdash;adding and removing files in one 198 <title>Useful shorthand&emdash;adding and removing files in one
199 step</title> 199 step</title>
200 200
201 <para>Mercurial offers a combination command, <command 201 <para id="x_1ba">Mercurial offers a combination command, <command
202 role="hg-cmd">hg addremove</command>, that adds untracked 202 role="hg-cmd">hg addremove</command>, that adds untracked
203 files and marks missing files as removed.</para> 203 files and marks missing files as removed.</para>
204 204
205 &interaction.daily.files.addremove; 205 &interaction.daily.files.addremove;
206 206
207 <para>The <command role="hg-cmd">hg commit</command> command 207 <para id="x_1bb">The <command role="hg-cmd">hg commit</command> command
208 also provides a <option role="hg-opt-commit">-A</option> 208 also provides a <option role="hg-opt-commit">-A</option>
209 option that performs this same add-and-remove, immediately 209 option that performs this same add-and-remove, immediately
210 followed by a commit.</para> 210 followed by a commit.</para>
211 211
212 &interaction.daily.files.commit-addremove; 212 &interaction.daily.files.commit-addremove;
214 </sect2> 214 </sect2>
215 </sect1> 215 </sect1>
216 <sect1> 216 <sect1>
217 <title>Copying files</title> 217 <title>Copying files</title>
218 218
219 <para>Mercurial provides a <command role="hg-cmd">hg 219 <para id="x_1bc">Mercurial provides a <command role="hg-cmd">hg
220 copy</command> command that lets you make a new copy of a 220 copy</command> command that lets you make a new copy of a
221 file. When you copy a file using this command, Mercurial makes 221 file. When you copy a file using this command, Mercurial makes
222 a record of the fact that the new file is a copy of the original 222 a record of the fact that the new file is a copy of the original
223 file. It treats these copied files specially when you merge 223 file. It treats these copied files specially when you merge
224 your work with someone else's.</para> 224 your work with someone else's.</para>
225 225
226 <sect2> 226 <sect2>
227 <title>The results of copying during a merge</title> 227 <title>The results of copying during a merge</title>
228 228
229 <para>What happens during a merge is that changes 229 <para id="x_1bd">What happens during a merge is that changes
230 <quote>follow</quote> a copy. To best illustrate what this 230 <quote>follow</quote> a copy. To best illustrate what this
231 means, let's create an example. We'll start with the usual 231 means, let's create an example. We'll start with the usual
232 tiny repository that contains a single file.</para> 232 tiny repository that contains a single file.</para>
233 233
234 &interaction.daily.copy.init; 234 &interaction.daily.copy.init;
235 235
236 <para>We need to do some work in 236 <para id="x_1be">We need to do some work in
237 parallel, so that we'll have something to merge. So let's 237 parallel, so that we'll have something to merge. So let's
238 clone our repository.</para> 238 clone our repository.</para>
239 239
240 &interaction.daily.copy.clone; 240 &interaction.daily.copy.clone;
241 241
242 <para>Back in our initial repository, let's use the <command 242 <para id="x_1bf">Back in our initial repository, let's use the <command
243 role="hg-cmd">hg copy</command> command to make a copy of 243 role="hg-cmd">hg copy</command> command to make a copy of
244 the first file we created.</para> 244 the first file we created.</para>
245 245
246 &interaction.daily.copy.copy; 246 &interaction.daily.copy.copy;
247 247
248 <para>If we look at the output of the <command role="hg-cmd">hg 248 <para id="x_1c0">If we look at the output of the <command role="hg-cmd">hg
249 status</command> command afterwards, the copied file looks 249 status</command> command afterwards, the copied file looks
250 just like a normal added file.</para> 250 just like a normal added file.</para>
251 251
252 &interaction.daily.copy.status; 252 &interaction.daily.copy.status;
253 253
254 <para>But if we pass the <option 254 <para id="x_1c1">But if we pass the <option
255 role="hg-opt-status">-C</option> option to <command 255 role="hg-opt-status">-C</option> option to <command
256 role="hg-cmd">hg status</command>, it prints another line of 256 role="hg-cmd">hg status</command>, it prints another line of
257 output: this is the file that our newly-added file was copied 257 output: this is the file that our newly-added file was copied
258 <emphasis>from</emphasis>.</para> 258 <emphasis>from</emphasis>.</para>
259 259
260 &interaction.daily.copy.status-copy; 260 &interaction.daily.copy.status-copy;
261 261
262 <para>Now, back in the repository we cloned, let's make a change 262 <para id="x_1c2">Now, back in the repository we cloned, let's make a change
263 in parallel. We'll add a line of content to the original file 263 in parallel. We'll add a line of content to the original file
264 that we created.</para> 264 that we created.</para>
265 265
266 &interaction.daily.copy.other; 266 &interaction.daily.copy.other;
267 267
268 <para>Now we have a modified <filename>file</filename> in this 268 <para id="x_1c3">Now we have a modified <filename>file</filename> in this
269 repository. When we pull the changes from the first 269 repository. When we pull the changes from the first
270 repository, and merge the two heads, Mercurial will propagate 270 repository, and merge the two heads, Mercurial will propagate
271 the changes that we made locally to <filename>file</filename> 271 the changes that we made locally to <filename>file</filename>
272 into its copy, <filename>new-file</filename>.</para> 272 into its copy, <filename>new-file</filename>.</para>
273 273
275 275
276 </sect2> 276 </sect2>
277 <sect2 id="sec:daily:why-copy"> 277 <sect2 id="sec:daily:why-copy">
278 <title>Why should changes follow copies?</title> 278 <title>Why should changes follow copies?</title>
279 279
280 <para>This behaviour, of changes to a file propagating out to 280 <para id="x_1c4">This behaviour, of changes to a file propagating out to
281 copies of the file, might seem esoteric, but in most cases 281 copies of the file, might seem esoteric, but in most cases
282 it's highly desirable.</para> 282 it's highly desirable.</para>
283 283
284 <para>First of all, remember that this propagation 284 <para id="x_1c5">First of all, remember that this propagation
285 <emphasis>only</emphasis> happens when you merge. So if you 285 <emphasis>only</emphasis> happens when you merge. So if you
286 <command role="hg-cmd">hg copy</command> a file, and 286 <command role="hg-cmd">hg copy</command> a file, and
287 subsequently modify the original file during the normal course 287 subsequently modify the original file during the normal course
288 of your work, nothing will happen.</para> 288 of your work, nothing will happen.</para>
289 289
290 <para>The second thing to know is that modifications will only 290 <para id="x_1c6">The second thing to know is that modifications will only
291 propagate across a copy as long as the repository that you're 291 propagate across a copy as long as the repository that you're
292 pulling changes from <emphasis>doesn't know</emphasis> about 292 pulling changes from <emphasis>doesn't know</emphasis> about
293 the copy.</para> 293 the copy.</para>
294 294
295 <para>The reason that Mercurial does this is as follows. Let's 295 <para id="x_1c7">The reason that Mercurial does this is as follows. Let's
296 say I make an important bug fix in a source file, and commit 296 say I make an important bug fix in a source file, and commit
297 my changes. Meanwhile, you've decided to <command 297 my changes. Meanwhile, you've decided to <command
298 role="hg-cmd">hg copy</command> the file in your repository, 298 role="hg-cmd">hg copy</command> the file in your repository,
299 without knowing about the bug or having seen the fix, and you 299 without knowing about the bug or having seen the fix, and you
300 have started hacking on your copy of the file.</para> 300 have started hacking on your copy of the file.</para>
301 301
302 <para>If you pulled and merged my changes, and Mercurial 302 <para id="x_1c8">If you pulled and merged my changes, and Mercurial
303 <emphasis>didn't</emphasis> propagate changes across copies, 303 <emphasis>didn't</emphasis> propagate changes across copies,
304 your source file would now contain the bug, and unless you 304 your source file would now contain the bug, and unless you
305 remembered to propagate the bug fix by hand, the bug would 305 remembered to propagate the bug fix by hand, the bug would
306 <emphasis>remain</emphasis> in your copy of the file.</para> 306 <emphasis>remain</emphasis> in your copy of the file.</para>
307 307
308 <para>By automatically propagating the change that fixed the bug 308 <para id="x_1c9">By automatically propagating the change that fixed the bug
309 from the original file to the copy, Mercurial prevents this 309 from the original file to the copy, Mercurial prevents this
310 class of problem. To my knowledge, Mercurial is the 310 class of problem. To my knowledge, Mercurial is the
311 <emphasis>only</emphasis> revision control system that 311 <emphasis>only</emphasis> revision control system that
312 propagates changes across copies like this.</para> 312 propagates changes across copies like this.</para>
313 313
314 <para>Once your change history has a record that the copy and 314 <para id="x_1ca">Once your change history has a record that the copy and
315 subsequent merge occurred, there's usually no further need to 315 subsequent merge occurred, there's usually no further need to
316 propagate changes from the original file to the copied file, 316 propagate changes from the original file to the copied file,
317 and that's why Mercurial only propagates changes across copies 317 and that's why Mercurial only propagates changes across copies
318 until this point, and no further.</para> 318 until this point, and no further.</para>
319 319
320 </sect2> 320 </sect2>
321 <sect2> 321 <sect2>
322 <title>How to make changes <emphasis>not</emphasis> follow a 322 <title>How to make changes <emphasis>not</emphasis> follow a
323 copy</title> 323 copy</title>
324 324
325 <para>If, for some reason, you decide that this business of 325 <para id="x_1cb">If, for some reason, you decide that this business of
326 automatically propagating changes across copies is not for 326 automatically propagating changes across copies is not for
327 you, simply use your system's normal file copy command (on 327 you, simply use your system's normal file copy command (on
328 Unix-like systems, that's <command>cp</command>) to make a 328 Unix-like systems, that's <command>cp</command>) to make a
329 copy of a file, then <command role="hg-cmd">hg add</command> 329 copy of a file, then <command role="hg-cmd">hg add</command>
330 the new copy by hand. Before you do so, though, please do 330 the new copy by hand. Before you do so, though, please do
336 </sect2> 336 </sect2>
337 <sect2> 337 <sect2>
338 <title>Behaviour of the <command role="hg-cmd">hg copy</command> 338 <title>Behaviour of the <command role="hg-cmd">hg copy</command>
339 command</title> 339 command</title>
340 340
341 <para>When you use the <command role="hg-cmd">hg copy</command> 341 <para id="x_1cc">When you use the <command role="hg-cmd">hg copy</command>
342 command, Mercurial makes a copy of each source file as it 342 command, Mercurial makes a copy of each source file as it
343 currently stands in the working directory. This means that if 343 currently stands in the working directory. This means that if
344 you make some modifications to a file, then <command 344 you make some modifications to a file, then <command
345 role="hg-cmd">hg copy</command> it without first having 345 role="hg-cmd">hg copy</command> it without first having
346 committed those changes, the new copy will also contain the 346 committed those changes, the new copy will also contain the
347 modifications you have made up until that point. (I find this 347 modifications you have made up until that point. (I find this
348 behaviour a little counterintuitive, which is why I mention it 348 behaviour a little counterintuitive, which is why I mention it
349 here.)</para> 349 here.)</para>
350 350
351 <para>The <command role="hg-cmd">hg copy</command> command acts 351 <para id="x_1cd">The <command role="hg-cmd">hg copy</command> command acts
352 similarly to the Unix <command>cp</command> command (you can 352 similarly to the Unix <command>cp</command> command (you can
353 use the <command role="hg-cmd">hg cp</command> alias if you 353 use the <command role="hg-cmd">hg cp</command> alias if you
354 prefer). The last argument is the 354 prefer). The last argument is the
355 <emphasis>destination</emphasis>, and all prior arguments are 355 <emphasis>destination</emphasis>, and all prior arguments are
356 <emphasis>sources</emphasis>. If you pass it a single file as 356 <emphasis>sources</emphasis>. If you pass it a single file as
357 the source, and the destination does not exist, it creates a 357 the source, and the destination does not exist, it creates a
358 new file with that name.</para> 358 new file with that name.</para>
359 359
360 &interaction.daily.copy.simple; 360 &interaction.daily.copy.simple;
361 361
362 <para>If the destination is a directory, Mercurial copies its 362 <para id="x_1ce">If the destination is a directory, Mercurial copies its
363 sources into that directory.</para> 363 sources into that directory.</para>
364 364
365 &interaction.daily.copy.dir-dest; 365 &interaction.daily.copy.dir-dest;
366 366
367 <para>Copying a directory is 367 <para id="x_1cf">Copying a directory is
368 recursive, and preserves the directory structure of the 368 recursive, and preserves the directory structure of the
369 source.</para> 369 source.</para>
370 370
371 &interaction.daily.copy.dir-src; 371 &interaction.daily.copy.dir-src;
372 372
373 <para>If the source and destination are both directories, the 373 <para id="x_1d0">If the source and destination are both directories, the
374 source tree is recreated in the destination directory.</para> 374 source tree is recreated in the destination directory.</para>
375 375
376 &interaction.daily.copy.dir-src-dest; 376 &interaction.daily.copy.dir-src-dest;
377 377
378 <para>As with the <command role="hg-cmd">hg rename</command> 378 <para id="x_1d1">As with the <command role="hg-cmd">hg rename</command>
379 command, if you copy a file manually and then want Mercurial 379 command, if you copy a file manually and then want Mercurial
380 to know that you've copied the file, simply use the <option 380 to know that you've copied the file, simply use the <option
381 role="hg-opt-copy">--after</option> option to <command 381 role="hg-opt-copy">--after</option> option to <command
382 role="hg-cmd">hg copy</command>.</para> 382 role="hg-cmd">hg copy</command>.</para>
383 383
386 </sect2> 386 </sect2>
387 </sect1> 387 </sect1>
388 <sect1> 388 <sect1>
389 <title>Renaming files</title> 389 <title>Renaming files</title>
390 390
391 <para>It's rather more common to need to rename a file than to 391 <para id="x_1d2">It's rather more common to need to rename a file than to
392 make a copy of it. The reason I discussed the <command 392 make a copy of it. The reason I discussed the <command
393 role="hg-cmd">hg copy</command> command before talking about 393 role="hg-cmd">hg copy</command> command before talking about
394 renaming files is that Mercurial treats a rename in essentially 394 renaming files is that Mercurial treats a rename in essentially
395 the same way as a copy. Therefore, knowing what Mercurial does 395 the same way as a copy. Therefore, knowing what Mercurial does
396 when you copy a file tells you what to expect when you rename a 396 when you copy a file tells you what to expect when you rename a
397 file.</para> 397 file.</para>
398 398
399 <para>When you use the <command role="hg-cmd">hg rename</command> 399 <para id="x_1d3">When you use the <command role="hg-cmd">hg rename</command>
400 command, Mercurial makes a copy of each source file, then 400 command, Mercurial makes a copy of each source file, then
401 deletes it and marks the file as removed.</para> 401 deletes it and marks the file as removed.</para>
402 402
403 &interaction.daily.rename.rename; 403 &interaction.daily.rename.rename;
404 404
405 <para>The <command role="hg-cmd">hg status</command> command shows 405 <para id="x_1d4">The <command role="hg-cmd">hg status</command> command shows
406 the newly copied file as added, and the copied-from file as 406 the newly copied file as added, and the copied-from file as
407 removed.</para> 407 removed.</para>
408 408
409 &interaction.daily.rename.status; 409 &interaction.daily.rename.status;
410 410
411 <para>As with the results of a <command role="hg-cmd">hg 411 <para id="x_1d5">As with the results of a <command role="hg-cmd">hg
412 copy</command>, we must use the <option 412 copy</command>, we must use the <option
413 role="hg-opt-status">-C</option> option to <command 413 role="hg-opt-status">-C</option> option to <command
414 role="hg-cmd">hg status</command> to see that the added file 414 role="hg-cmd">hg status</command> to see that the added file
415 is really being tracked by Mercurial as a copy of the original, 415 is really being tracked by Mercurial as a copy of the original,
416 now removed, file.</para> 416 now removed, file.</para>
417 417
418 &interaction.daily.rename.status-copy; 418 &interaction.daily.rename.status-copy;
419 419
420 <para>As with <command role="hg-cmd">hg remove</command> and 420 <para id="x_1d6">As with <command role="hg-cmd">hg remove</command> and
421 <command role="hg-cmd">hg copy</command>, you can tell Mercurial 421 <command role="hg-cmd">hg copy</command>, you can tell Mercurial
422 about a rename after the fact using the <option 422 about a rename after the fact using the <option
423 role="hg-opt-rename">--after</option> option. In most other 423 role="hg-opt-rename">--after</option> option. In most other
424 respects, the behaviour of the <command role="hg-cmd">hg 424 respects, the behaviour of the <command role="hg-cmd">hg
425 rename</command> command, and the options it accepts, are 425 rename</command> command, and the options it accepts, are
427 command.</para> 427 command.</para>
428 428
429 <sect2> 429 <sect2>
430 <title>Renaming files and merging changes</title> 430 <title>Renaming files and merging changes</title>
431 431
432 <para>Since Mercurial's rename is implemented as 432 <para id="x_1d7">Since Mercurial's rename is implemented as
433 copy-and-remove, the same propagation of changes happens when 433 copy-and-remove, the same propagation of changes happens when
434 you merge after a rename as after a copy.</para> 434 you merge after a rename as after a copy.</para>
435 435
436 <para>If I modify a file, and you rename it to a new name, and 436 <para id="x_1d8">If I modify a file, and you rename it to a new name, and
437 then we merge our respective changes, my modifications to the 437 then we merge our respective changes, my modifications to the
438 file under its original name will be propagated into the file 438 file under its original name will be propagated into the file
439 under its new name. (This is something you might expect to 439 under its new name. (This is something you might expect to
440 <quote>simply work,</quote> but not all revision control 440 <quote>simply work,</quote> but not all revision control
441 systems actually do this.)</para> 441 systems actually do this.)</para>
442 442
443 <para>Whereas having changes follow a copy is a feature where 443 <para id="x_1d9">Whereas having changes follow a copy is a feature where
444 you can perhaps nod and say <quote>yes, that might be 444 you can perhaps nod and say <quote>yes, that might be
445 useful,</quote> it should be clear that having them follow a 445 useful,</quote> it should be clear that having them follow a
446 rename is definitely important. Without this facility, it 446 rename is definitely important. Without this facility, it
447 would simply be too easy for changes to become orphaned when 447 would simply be too easy for changes to become orphaned when
448 files are renamed.</para> 448 files are renamed.</para>
449 449
450 </sect2> 450 </sect2>
451 <sect2> 451 <sect2>
452 <title>Divergent renames and merging</title> 452 <title>Divergent renames and merging</title>
453 453
454 <para>The case of diverging names occurs when two developers 454 <para id="x_1da">The case of diverging names occurs when two developers
455 start with a file&emdash;let's call it 455 start with a file&emdash;let's call it
456 <filename>foo</filename>&emdash;in their respective 456 <filename>foo</filename>&emdash;in their respective
457 repositories.</para> 457 repositories.</para>
458 458
459 &interaction.rename.divergent.clone; 459 &interaction.rename.divergent.clone;
460 460
461 <para>Anne renames the file to <filename>bar</filename>.</para> 461 <para id="x_1db">Anne renames the file to <filename>bar</filename>.</para>
462 462
463 &interaction.rename.divergent.rename.anne; 463 &interaction.rename.divergent.rename.anne;
464 464
465 <para>Meanwhile, Bob renames it to 465 <para id="x_1dc">Meanwhile, Bob renames it to
466 <filename>quux</filename>.</para> 466 <filename>quux</filename>.</para>
467 467
468 &interaction.rename.divergent.rename.bob; 468 &interaction.rename.divergent.rename.bob;
469 469
470 <para>I like to think of this as a conflict because each 470 <para id="x_1dd">I like to think of this as a conflict because each
471 developer has expressed different intentions about what the 471 developer has expressed different intentions about what the
472 file ought to be named.</para> 472 file ought to be named.</para>
473 473
474 <para>What do you think should happen when they merge their 474 <para id="x_1de">What do you think should happen when they merge their
475 work? Mercurial's actual behaviour is that it always preserves 475 work? Mercurial's actual behaviour is that it always preserves
476 <emphasis>both</emphasis> names when it merges changesets that 476 <emphasis>both</emphasis> names when it merges changesets that
477 contain divergent renames.</para> 477 contain divergent renames.</para>
478 478
479 &interaction.rename.divergent.merge; 479 &interaction.rename.divergent.merge;
480 480
481 <para>Notice that Mercurial does warn about the divergent 481 <para id="x_1df">Notice that Mercurial does warn about the divergent
482 renames, but it leaves it up to you to do something about the 482 renames, but it leaves it up to you to do something about the
483 divergence after the merge.</para> 483 divergence after the merge.</para>
484 484
485 </sect2> 485 </sect2>
486 <sect2> 486 <sect2>
487 <title>Convergent renames and merging</title> 487 <title>Convergent renames and merging</title>
488 488
489 <para>Another kind of rename conflict occurs when two people 489 <para id="x_1e0">Another kind of rename conflict occurs when two people
490 choose to rename different <emphasis>source</emphasis> files 490 choose to rename different <emphasis>source</emphasis> files
491 to the same <emphasis>destination</emphasis>. In this case, 491 to the same <emphasis>destination</emphasis>. In this case,
492 Mercurial runs its normal merge machinery, and lets you guide 492 Mercurial runs its normal merge machinery, and lets you guide
493 it to a suitable resolution.</para> 493 it to a suitable resolution.</para>
494 494
495 </sect2> 495 </sect2>
496 <sect2> 496 <sect2>
497 <title>Other name-related corner cases</title> 497 <title>Other name-related corner cases</title>
498 498
499 <para>Mercurial has a longstanding bug in which it fails to 499 <para id="x_1e1">Mercurial has a longstanding bug in which it fails to
500 handle a merge where one side has a file with a given name, 500 handle a merge where one side has a file with a given name,
501 while another has a directory with the same name. This is 501 while another has a directory with the same name. This is
502 documented as <ulink role="hg-bug" 502 documented as <ulink role="hg-bug"
503 url="http://www.selenic.com/mercurial/bts/issue29">issue 503 url="http://www.selenic.com/mercurial/bts/issue29">issue
504 29</ulink>.</para> 504 29</ulink>.</para>
508 </sect2> 508 </sect2>
509 </sect1> 509 </sect1>
510 <sect1> 510 <sect1>
511 <title>Recovering from mistakes</title> 511 <title>Recovering from mistakes</title>
512 512
513 <para>Mercurial has some useful commands that will help you to 513 <para id="x_1e2">Mercurial has some useful commands that will help you to
514 recover from some common mistakes.</para> 514 recover from some common mistakes.</para>
515 515
516 <para>The <command role="hg-cmd">hg revert</command> command lets 516 <para id="x_1e3">The <command role="hg-cmd">hg revert</command> command lets
517 you undo changes that you have made to your working directory. 517 you undo changes that you have made to your working directory.
518 For example, if you <command role="hg-cmd">hg add</command> a 518 For example, if you <command role="hg-cmd">hg add</command> a
519 file by accident, just run <command role="hg-cmd">hg 519 file by accident, just run <command role="hg-cmd">hg
520 revert</command> with the name of the file you added, and 520 revert</command> with the name of the file you added, and
521 while the file won't be touched in any way, it won't be tracked 521 while the file won't be touched in any way, it won't be tracked
522 for adding by Mercurial any longer, either. You can also use 522 for adding by Mercurial any longer, either. You can also use
523 <command role="hg-cmd">hg revert</command> to get rid of 523 <command role="hg-cmd">hg revert</command> to get rid of
524 erroneous changes to a file.</para> 524 erroneous changes to a file.</para>
525 525
526 <para>It's useful to remember that the <command role="hg-cmd">hg 526 <para id="x_1e4">It's useful to remember that the <command role="hg-cmd">hg
527 revert</command> command is useful for changes that you have 527 revert</command> command is useful for changes that you have
528 not yet committed. Once you've committed a change, if you 528 not yet committed. Once you've committed a change, if you
529 decide it was a mistake, you can still do something about it, 529 decide it was a mistake, you can still do something about it,
530 though your options may be more limited.</para> 530 though your options may be more limited.</para>
531 531
532 <para>For more information about the <command role="hg-cmd">hg 532 <para id="x_1e5">For more information about the <command role="hg-cmd">hg
533 revert</command> command, and details about how to deal with 533 revert</command> command, and details about how to deal with
534 changes you have already committed, see chapter <xref 534 changes you have already committed, see chapter <xref
535 linkend="chap:undo"/>.</para> 535 linkend="chap:undo"/>.</para>
536 536
537 </sect1> 537 </sect1>