Mercurial > hgbook
comparison en/appA-svn.xml @ 818:75ccc1e89aef
Add paragraph IDS
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Sun, 26 Apr 2009 23:22:28 -0700 |
parents | 0ffae4ee4c47 |
children | fe31dc9ce440 |
comparison
equal
deleted
inserted
replaced
815:0ffae4ee4c47 | 818:75ccc1e89aef |
---|---|
2 | 2 |
3 <appendix id="svn"> | 3 <appendix id="svn"> |
4 <?dbhtml filename="migrating-to-mercurial.html"?> | 4 <?dbhtml filename="migrating-to-mercurial.html"?> |
5 <title>Migrating to Mercurial</title> | 5 <title>Migrating to Mercurial</title> |
6 | 6 |
7 <para>A common way to test the waters with a new revision control | 7 <para id="x_6e0">A common way to test the waters with a new revision control |
8 tool is to experiment with switching an existing project, rather | 8 tool is to experiment with switching an existing project, rather |
9 than starting a new project from scratch.</para> | 9 than starting a new project from scratch.</para> |
10 | 10 |
11 <para>In this appendix, we discuss how to import a project's history | 11 <para id="x_6e1">In this appendix, we discuss how to import a project's history |
12 into Mercurial, and what to look out for if you are used to a | 12 into Mercurial, and what to look out for if you are used to a |
13 different revision control system.</para> | 13 different revision control system.</para> |
14 | 14 |
15 <sect1> | 15 <sect1> |
16 <title>Importing history from another system</title> | 16 <title>Importing history from another system</title> |
17 | 17 |
18 <para>Mercurial ships with an extension named | 18 <para id="x_6e2">Mercurial ships with an extension named |
19 <literal>convert</literal>, which can import project history | 19 <literal>convert</literal>, which can import project history |
20 from most popular revision control systems. At the time this | 20 from most popular revision control systems. At the time this |
21 book was written, it could import history from the following | 21 book was written, it could import history from the following |
22 systems:</para> | 22 systems:</para> |
23 <itemizedlist> | 23 <itemizedlist> |
24 <listitem> | 24 <listitem> |
25 <para>Subversion</para> | 25 <para id="x_6e3">Subversion</para> |
26 </listitem> | 26 </listitem> |
27 <listitem> | 27 <listitem> |
28 <para>CVS</para> | 28 <para id="x_6e4">CVS</para> |
29 </listitem> | 29 </listitem> |
30 <listitem> | 30 <listitem> |
31 <para>git</para> | 31 <para id="x_6e5">git</para> |
32 </listitem> | 32 </listitem> |
33 <listitem> | 33 <listitem> |
34 <para>Darcs</para> | 34 <para id="x_6e6">Darcs</para> |
35 </listitem> | 35 </listitem> |
36 <listitem> | 36 <listitem> |
37 <para>Bazaar</para> | 37 <para id="x_6e7">Bazaar</para> |
38 </listitem> | 38 </listitem> |
39 <listitem> | 39 <listitem> |
40 <para>Monotone</para> | 40 <para id="x_6e8">Monotone</para> |
41 </listitem> | 41 </listitem> |
42 <listitem> | 42 <listitem> |
43 <para>GNU Arch</para> | 43 <para id="x_6e9">GNU Arch</para> |
44 </listitem> | 44 </listitem> |
45 <listitem> | 45 <listitem> |
46 <para>Mercurial</para> | 46 <para id="x_6ea">Mercurial</para> |
47 </listitem> | 47 </listitem> |
48 </itemizedlist> | 48 </itemizedlist> |
49 | 49 |
50 <para>(To see why Mercurial itself is supported as a source, see | 50 <para id="x_6eb">(To see why Mercurial itself is supported as a source, see |
51 <xref linkend="svn.filemap"/>.)</para> | 51 <xref linkend="svn.filemap"/>.)</para> |
52 | 52 |
53 <para>You can enable the extension in the usual way, by editing | 53 <para id="x_6ec">You can enable the extension in the usual way, by editing |
54 your <filename>~/.hgrc</filename> file.</para> | 54 your <filename>~/.hgrc</filename> file.</para> |
55 | 55 |
56 <programlisting>[extensions] | 56 <programlisting>[extensions] |
57 convert =</programlisting> | 57 convert =</programlisting> |
58 | 58 |
59 <para>This will make a <command>hg convert</command> command | 59 <para id="x_6ed">This will make a <command>hg convert</command> command |
60 available. The command is easy to use. For instance, this | 60 available. The command is easy to use. For instance, this |
61 command will import the Subversion history for the Nose unit | 61 command will import the Subversion history for the Nose unit |
62 testing framework into Mercurial.</para> | 62 testing framework into Mercurial.</para> |
63 | 63 |
64 <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen> | 64 <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen> |
65 | 65 |
66 <para>The <literal>convert</literal> extension operates | 66 <para id="x_6ee">The <literal>convert</literal> extension operates |
67 incrementally. In other words, after you have run <command>hg | 67 incrementally. In other words, after you have run <command>hg |
68 convert</command> once, running it again will import any new | 68 convert</command> once, running it again will import any new |
69 revisions committed after the first run began. Incremental | 69 revisions committed after the first run began. Incremental |
70 conversion will only work if you run <command>hg | 70 conversion will only work if you run <command>hg |
71 convert</command> in the same Mercurial repository that you | 71 convert</command> in the same Mercurial repository that you |
76 repository.</para> | 76 repository.</para> |
77 | 77 |
78 <sect2> | 78 <sect2> |
79 <title>Mapping user names</title> | 79 <title>Mapping user names</title> |
80 | 80 |
81 <para>Some revision control tools save only short usernames with | 81 <para id="x_6ef">Some revision control tools save only short usernames with |
82 commits, and these can be difficult to interpret. The norm | 82 commits, and these can be difficult to interpret. The norm |
83 with Mercurial is to save a committer's name and email | 83 with Mercurial is to save a committer's name and email |
84 address, which is much more useful for talking to them after | 84 address, which is much more useful for talking to them after |
85 the fact.</para> | 85 the fact.</para> |
86 | 86 |
87 <para>If you are converting a tree from a revision control | 87 <para id="x_6f0">If you are converting a tree from a revision control |
88 system that uses short names, you can map those names to | 88 system that uses short names, you can map those names to |
89 longer equivalents by passing a <option>--authors</option> | 89 longer equivalents by passing a <option>--authors</option> |
90 option to <command>hg convert</command>. This option accepts | 90 option to <command>hg convert</command>. This option accepts |
91 a file name that should contain entries of the following | 91 a file name that should contain entries of the following |
92 form.</para> | 92 form.</para> |
93 | 93 |
94 <programlisting>arist = Aristotle <aristotle@phil.example.gr> | 94 <programlisting>arist = Aristotle <aristotle@phil.example.gr> |
95 soc = Socrates <socrates@phil.example.gr></programlisting> | 95 soc = Socrates <socrates@phil.example.gr></programlisting> |
96 | 96 |
97 <para>Whenever <literal>convert</literal> encounters a commit | 97 <para id="x_6f1">Whenever <literal>convert</literal> encounters a commit |
98 with the username <literal>arist</literal> in the source | 98 with the username <literal>arist</literal> in the source |
99 repository, it will use the name <literal>Aristotle | 99 repository, it will use the name <literal>Aristotle |
100 <aristotle@phil.example.gr></literal> in the converted | 100 <aristotle@phil.example.gr></literal> in the converted |
101 Mercurial revision. If no match is found for a name, it is | 101 Mercurial revision. If no match is found for a name, it is |
102 used verbatim.</para> | 102 used verbatim.</para> |
103 </sect2> | 103 </sect2> |
104 | 104 |
105 <sect2 id="svn.filemap"> | 105 <sect2 id="svn.filemap"> |
106 <title>Tidying up the tree</title> | 106 <title>Tidying up the tree</title> |
107 | 107 |
108 <para>Not all projects have pristine history. There may be a | 108 <para id="x_6f2">Not all projects have pristine history. There may be a |
109 directory that should never have been checked in, a file that | 109 directory that should never have been checked in, a file that |
110 is too big, or a whole hierarchy that needs to be | 110 is too big, or a whole hierarchy that needs to be |
111 refactored.</para> | 111 refactored.</para> |
112 | 112 |
113 <para>The <literal>convert</literal> extension supports the idea | 113 <para id="x_6f3">The <literal>convert</literal> extension supports the idea |
114 of a <quote>file map</quote> that can reorganize the files and | 114 of a <quote>file map</quote> that can reorganize the files and |
115 directories in a project as it imports the project's history. | 115 directories in a project as it imports the project's history. |
116 This is useful not only when importing history from other | 116 This is useful not only when importing history from other |
117 revision control systems, but also to prune or refactor a | 117 revision control systems, but also to prune or refactor a |
118 Mercurial tree.</para> | 118 Mercurial tree.</para> |
119 | 119 |
120 <para>To specify a file map, use the <option>--filemap</option> | 120 <para id="x_6f4">To specify a file map, use the <option>--filemap</option> |
121 option and supply a file name. A file map contains lines of the | 121 option and supply a file name. A file map contains lines of the |
122 following forms.</para> | 122 following forms.</para> |
123 | 123 |
124 <programlisting># This is a comment. | 124 <programlisting># This is a comment. |
125 # Empty lines are ignored. | 125 # Empty lines are ignored. |
129 exclude path/to/file | 129 exclude path/to/file |
130 | 130 |
131 rename from/some/path to/some/other/place | 131 rename from/some/path to/some/other/place |
132 </programlisting> | 132 </programlisting> |
133 | 133 |
134 <para>The <literal>include</literal> directive causes a file, or | 134 <para id="x_6f5">The <literal>include</literal> directive causes a file, or |
135 all files under a directory, to be included in the destination | 135 all files under a directory, to be included in the destination |
136 repository. This also excludes all other files and dirs not | 136 repository. This also excludes all other files and dirs not |
137 explicitely included. The <literal>exclude</literal> | 137 explicitely included. The <literal>exclude</literal> |
138 directive causes files or directories to be omitted, and | 138 directive causes files or directories to be omitted, and |
139 others not explicitly mentioned to be included.</para> | 139 others not explicitly mentioned to be included.</para> |
140 | 140 |
141 <para>To move a file or directory from one location to another, | 141 <para id="x_6f6">To move a file or directory from one location to another, |
142 use the <literal>rename</literal> directive. If you need to | 142 use the <literal>rename</literal> directive. If you need to |
143 move a file or directory from a subdirectory into the root of | 143 move a file or directory from a subdirectory into the root of |
144 the repository, use <literal>.</literal> as the second | 144 the repository, use <literal>.</literal> as the second |
145 argument to the <literal>rename</literal> directive.</para> | 145 argument to the <literal>rename</literal> directive.</para> |
146 </sect2> | 146 </sect2> |
147 </sect1> | 147 </sect1> |
148 | 148 |
149 <sect1> | 149 <sect1> |
150 <title>Migrating from Subversion</title> | 150 <title>Migrating from Subversion</title> |
151 | 151 |
152 <para>Subversion is currently the most popular open source | 152 <para id="x_6f7">Subversion is currently the most popular open source |
153 revision control system. Although there are many differences | 153 revision control system. Although there are many differences |
154 between Mercurial and Subversion, making the transition from | 154 between Mercurial and Subversion, making the transition from |
155 Subversion to Mercurial is not particularly difficult. The two | 155 Subversion to Mercurial is not particularly difficult. The two |
156 have similar command sets and generally uniform | 156 have similar command sets and generally uniform |
157 interfaces.</para> | 157 interfaces.</para> |
158 | 158 |
159 <sect2> | 159 <sect2> |
160 <title>Philosophical differences</title> | 160 <title>Philosophical differences</title> |
161 | 161 |
162 <para>The fundamental difference between Subversion and | 162 <para id="x_6f8">The fundamental difference between Subversion and |
163 Mercurial is of course that Subversion is centralized, while | 163 Mercurial is of course that Subversion is centralized, while |
164 Mercurial is distributed. Since Mercurial stores all of a | 164 Mercurial is distributed. Since Mercurial stores all of a |
165 project's history on your local drive, it only needs to | 165 project's history on your local drive, it only needs to |
166 perform a network access when you want to explicitly | 166 perform a network access when you want to explicitly |
167 communicate with another repository. In contrast, Subversion | 167 communicate with another repository. In contrast, Subversion |
168 stores very little information locally, and the client must | 168 stores very little information locally, and the client must |
169 thus contact its server for many common operations.</para> | 169 thus contact its server for many common operations.</para> |
170 | 170 |
171 <para>Subversion more or less gets away without a well-defined | 171 <para id="x_6f9">Subversion more or less gets away without a well-defined |
172 notion of a branch: which portion of a server's namespace | 172 notion of a branch: which portion of a server's namespace |
173 qualifies as a branch is a matter of convention, with the | 173 qualifies as a branch is a matter of convention, with the |
174 software providing no enforcement. Mercurial treats a | 174 software providing no enforcement. Mercurial treats a |
175 repository as the unit of branch management.</para> | 175 repository as the unit of branch management.</para> |
176 | 176 |
177 <sect3> | 177 <sect3> |
178 <title>Scope of commands</title> | 178 <title>Scope of commands</title> |
179 | 179 |
180 <para>Since Subversion doesn't know what parts of its | 180 <para id="x_6fa">Since Subversion doesn't know what parts of its |
181 namespace are really branches, it treats most commands as | 181 namespace are really branches, it treats most commands as |
182 requests to operate at and below whatever directory you are | 182 requests to operate at and below whatever directory you are |
183 currently visiting. For instance, if you run <command>svn | 183 currently visiting. For instance, if you run <command>svn |
184 log</command>, you'll get the history of whatever part of | 184 log</command>, you'll get the history of whatever part of |
185 the tree you're looking at, not the tree as a whole.</para> | 185 the tree you're looking at, not the tree as a whole.</para> |
186 | 186 |
187 <para>Mercurial's commands behave differently, by defaulting | 187 <para id="x_6fb">Mercurial's commands behave differently, by defaulting |
188 to operating over an entire repository. Run <command>hg | 188 to operating over an entire repository. Run <command>hg |
189 log</command> and it will tell you the history of the | 189 log</command> and it will tell you the history of the |
190 entire tree, no matter what part of the working directory | 190 entire tree, no matter what part of the working directory |
191 you're visiting at the time. If you want the history of | 191 you're visiting at the time. If you want the history of |
192 just a particular file or directory, simply supply it by | 192 just a particular file or directory, simply supply it by |
193 name, e.g. <command>hg log src</command>.</para> | 193 name, e.g. <command>hg log src</command>.</para> |
194 | 194 |
195 <para>From my own experience, this difference in default | 195 <para id="x_6fc">From my own experience, this difference in default |
196 behaviors is probably the most likely to trip you up if you | 196 behaviors is probably the most likely to trip you up if you |
197 have to switch back and forth frequently between the two | 197 have to switch back and forth frequently between the two |
198 tools.</para> | 198 tools.</para> |
199 </sect3> | 199 </sect3> |
200 | 200 |
201 <sect3> | 201 <sect3> |
202 <title>Multi-user operation and safety</title> | 202 <title>Multi-user operation and safety</title> |
203 | 203 |
204 <para>With Subversion, it is normal (though slightly frowned | 204 <para id="x_6fd">With Subversion, it is normal (though slightly frowned |
205 upon) for multiple people to collaborate in a single branch. | 205 upon) for multiple people to collaborate in a single branch. |
206 If Alice and Bob are working together, and Alice commits | 206 If Alice and Bob are working together, and Alice commits |
207 some changes to their shared branch, Bob must update his | 207 some changes to their shared branch, Bob must update his |
208 client's view of the branch before he can commit. Since at | 208 client's view of the branch before he can commit. Since at |
209 this time he has no permanent record of the changes he has | 209 this time he has no permanent record of the changes he has |
210 made, he can corrupt or lose his modifications during and | 210 made, he can corrupt or lose his modifications during and |
211 after his update.</para> | 211 after his update.</para> |
212 | 212 |
213 <para>Mercurial encourages a commit-then-merge model instead. | 213 <para id="x_6fe">Mercurial encourages a commit-then-merge model instead. |
214 Bob commits his changes locally before pulling changes from, | 214 Bob commits his changes locally before pulling changes from, |
215 or pushing them to, the server that he shares with Alice. | 215 or pushing them to, the server that he shares with Alice. |
216 If Alice pushed her changes before Bob tries to push his, he | 216 If Alice pushed her changes before Bob tries to push his, he |
217 will not be able to push his changes until he pulls hers, | 217 will not be able to push his changes until he pulls hers, |
218 merges with them, and commits the result of the merge. If | 218 merges with them, and commits the result of the merge. If |
219 he makes a mistake during the merge, he still has the option | 219 he makes a mistake during the merge, he still has the option |
220 of reverting to the commit that recorded his changes.</para> | 220 of reverting to the commit that recorded his changes.</para> |
221 | 221 |
222 <para>It is worth emphasizing that these are the common ways | 222 <para id="x_6ff">It is worth emphasizing that these are the common ways |
223 of working with these tools. Subversion supports a safer | 223 of working with these tools. Subversion supports a safer |
224 work-in-your-own-branch model, but it is cumbersome enough | 224 work-in-your-own-branch model, but it is cumbersome enough |
225 in practice to not be widely used. Mercurial can support | 225 in practice to not be widely used. Mercurial can support |
226 the less safe mode of allowing changes to be pulled in and | 226 the less safe mode of allowing changes to be pulled in and |
227 merged on top of uncommitted edits, but this is considered | 227 merged on top of uncommitted edits, but this is considered |
229 </sect3> | 229 </sect3> |
230 | 230 |
231 <sect3> | 231 <sect3> |
232 <title>Published vs local changes</title> | 232 <title>Published vs local changes</title> |
233 | 233 |
234 <para>A Subversion <command>svn commit</command> command | 234 <para id="x_700">A Subversion <command>svn commit</command> command |
235 immediately publishes changes to a server, where they can be | 235 immediately publishes changes to a server, where they can be |
236 seen by everyone who has read access.</para> | 236 seen by everyone who has read access.</para> |
237 | 237 |
238 <para>With Mercurial, commits are always local, and must be | 238 <para id="x_701">With Mercurial, commits are always local, and must be |
239 published via a <command>hg push</command> command | 239 published via a <command>hg push</command> command |
240 afterwards.</para> | 240 afterwards.</para> |
241 | 241 |
242 <para>Each approach has its advantages and disadvantages. The | 242 <para id="x_702">Each approach has its advantages and disadvantages. The |
243 Subversion model means that changes are published, and hence | 243 Subversion model means that changes are published, and hence |
244 reviewable and usable, immediately. On the other hand, this | 244 reviewable and usable, immediately. On the other hand, this |
245 means that a user must have commit access to a repository in | 245 means that a user must have commit access to a repository in |
246 order to use the software in a normal way, and commit access | 246 order to use the software in a normal way, and commit access |
247 is not lightly given out by most open source | 247 is not lightly given out by most open source |
248 projects.</para> | 248 projects.</para> |
249 | 249 |
250 <para>The Mercurial approach allows anyone who can clone a | 250 <para id="x_703">The Mercurial approach allows anyone who can clone a |
251 repository to commit changes without the need for someone | 251 repository to commit changes without the need for someone |
252 else's permission, and they can then publish their changes | 252 else's permission, and they can then publish their changes |
253 and continue to participate however they see fit. The | 253 and continue to participate however they see fit. The |
254 distinction between committing and pushing does open up the | 254 distinction between committing and pushing does open up the |
255 possibility of someone committing changes to their laptop | 255 possibility of someone committing changes to their laptop |
406 </sect1> | 406 </sect1> |
407 | 407 |
408 <sect1> | 408 <sect1> |
409 <title>Useful tips for newcomers</title> | 409 <title>Useful tips for newcomers</title> |
410 | 410 |
411 <para>Under some revision control systems, printing a diff for a | 411 <para id="x_704">Under some revision control systems, printing a diff for a |
412 single committed revision can be painful. For instance, with | 412 single committed revision can be painful. For instance, with |
413 Subversion, to see what changed in revision 104654, you must | 413 Subversion, to see what changed in revision 104654, you must |
414 type <command>svn diff -r104653:104654</command>. Mercurial | 414 type <command>svn diff -r104653:104654</command>. Mercurial |
415 eliminates the need to type the revision ID twice in this common | 415 eliminates the need to type the revision ID twice in this common |
416 case. For a plain diff, <command>hg export 104654</command>. For | 416 case. For a plain diff, <command>hg export 104654</command>. For |
417 a log message followed by a diff, <command>hg log -r104654 | 417 a log message followed by a diff, <command>hg log -r104654 |
418 -p</command>.</para> | 418 -p</command>.</para> |
419 | 419 |
420 <para>When you run <command>hg status</command> without any | 420 <para id="x_705">When you run <command>hg status</command> without any |
421 arguments, it prints the status of the entire tree, with paths | 421 arguments, it prints the status of the entire tree, with paths |
422 relative to the root of the repository. This makes it tricky to | 422 relative to the root of the repository. This makes it tricky to |
423 copy a file name from the output of <command>hg status</command> | 423 copy a file name from the output of <command>hg status</command> |
424 into the command line. If you supply a file or directory name | 424 into the command line. If you supply a file or directory name |
425 to <command>hg status</command>, it will print paths relative to | 425 to <command>hg status</command>, it will print paths relative to |