Mercurial > hgbook
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> |