hgbook

annotate en/appA-svn.xml @ 688:75ccc1e89aef

find changesets by author, revision, files, or words in the commit message
Add paragraph IDS
author Bryan O'Sullivan <bos@serpentine.com>
date Sun Apr 26 23:22:28 2009 -0700 (2009-04-26)
parents 0ffae4ee4c47
children fe31dc9ce440
rev   line source
bos@559 1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
bos@559 2
bos@686 3 <appendix id="svn">
bos@687 4 <?dbhtml filename="migrating-to-mercurial.html"?>
bos@686 5 <title>Migrating to Mercurial</title>
bos@686 6
bos@688 7 <para id="x_6e0">A common way to test the waters with a new revision control
bos@686 8 tool is to experiment with switching an existing project, rather
bos@686 9 than starting a new project from scratch.</para>
bos@686 10
bos@688 11 <para id="x_6e1">In this appendix, we discuss how to import a project's history
bos@686 12 into Mercurial, and what to look out for if you are used to a
bos@686 13 different revision control system.</para>
bos@686 14
bos@686 15 <sect1>
bos@686 16 <title>Importing history from another system</title>
bos@686 17
bos@688 18 <para id="x_6e2">Mercurial ships with an extension named
bos@686 19 <literal>convert</literal>, which can import project history
bos@686 20 from most popular revision control systems. At the time this
bos@686 21 book was written, it could import history from the following
bos@686 22 systems:</para>
bos@686 23 <itemizedlist>
bos@686 24 <listitem>
bos@688 25 <para id="x_6e3">Subversion</para>
bos@688 26 </listitem>
bos@688 27 <listitem>
bos@688 28 <para id="x_6e4">CVS</para>
bos@688 29 </listitem>
bos@688 30 <listitem>
bos@688 31 <para id="x_6e5">git</para>
bos@688 32 </listitem>
bos@688 33 <listitem>
bos@688 34 <para id="x_6e6">Darcs</para>
bos@688 35 </listitem>
bos@688 36 <listitem>
bos@688 37 <para id="x_6e7">Bazaar</para>
bos@688 38 </listitem>
bos@688 39 <listitem>
bos@688 40 <para id="x_6e8">Monotone</para>
bos@688 41 </listitem>
bos@688 42 <listitem>
bos@688 43 <para id="x_6e9">GNU Arch</para>
bos@688 44 </listitem>
bos@688 45 <listitem>
bos@688 46 <para id="x_6ea">Mercurial</para>
bos@686 47 </listitem>
bos@686 48 </itemizedlist>
bos@686 49
bos@688 50 <para id="x_6eb">(To see why Mercurial itself is supported as a source, see
bos@686 51 <xref linkend="svn.filemap"/>.)</para>
bos@686 52
bos@688 53 <para id="x_6ec">You can enable the extension in the usual way, by editing
bos@686 54 your <filename>~/.hgrc</filename> file.</para>
bos@686 55
bos@686 56 <programlisting>[extensions]
bos@686 57 convert =</programlisting>
bos@686 58
bos@688 59 <para id="x_6ed">This will make a <command>hg convert</command> command
bos@686 60 available. The command is easy to use. For instance, this
bos@686 61 command will import the Subversion history for the Nose unit
bos@686 62 testing framework into Mercurial.</para>
bos@686 63
bos@686 64 <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
bos@686 65
bos@688 66 <para id="x_6ee">The <literal>convert</literal> extension operates
bos@686 67 incrementally. In other words, after you have run <command>hg
bos@686 68 convert</command> once, running it again will import any new
bos@686 69 revisions committed after the first run began. Incremental
bos@686 70 conversion will only work if you run <command>hg
bos@686 71 convert</command> in the same Mercurial repository that you
bos@686 72 originally used, because the <literal>convert</literal>
bos@686 73 extension saves some private metadata in a
bos@686 74 non-revision-controlled file named
bos@686 75 <filename>.hg/shamap</filename> inside the target
bos@686 76 repository.</para>
bos@686 77
bos@686 78 <sect2>
bos@686 79 <title>Mapping user names</title>
bos@686 80
bos@688 81 <para id="x_6ef">Some revision control tools save only short usernames with
bos@686 82 commits, and these can be difficult to interpret. The norm
bos@686 83 with Mercurial is to save a committer's name and email
bos@686 84 address, which is much more useful for talking to them after
bos@686 85 the fact.</para>
bos@686 86
bos@688 87 <para id="x_6f0">If you are converting a tree from a revision control
bos@686 88 system that uses short names, you can map those names to
bos@686 89 longer equivalents by passing a <option>--authors</option>
bos@686 90 option to <command>hg convert</command>. This option accepts
bos@686 91 a file name that should contain entries of the following
bos@686 92 form.</para>
bos@686 93
bos@686 94 <programlisting>arist = Aristotle &lt;aristotle@phil.example.gr&gt;
bos@686 95 soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
bos@686 96
bos@688 97 <para id="x_6f1">Whenever <literal>convert</literal> encounters a commit
bos@686 98 with the username <literal>arist</literal> in the source
bos@686 99 repository, it will use the name <literal>Aristotle
bos@686 100 &lt;aristotle@phil.example.gr&gt;</literal> in the converted
bos@686 101 Mercurial revision. If no match is found for a name, it is
bos@686 102 used verbatim.</para>
bos@686 103 </sect2>
bos@686 104
bos@686 105 <sect2 id="svn.filemap">
bos@686 106 <title>Tidying up the tree</title>
bos@686 107
bos@688 108 <para id="x_6f2">Not all projects have pristine history. There may be a
bos@686 109 directory that should never have been checked in, a file that
bos@686 110 is too big, or a whole hierarchy that needs to be
bos@686 111 refactored.</para>
bos@686 112
bos@688 113 <para id="x_6f3">The <literal>convert</literal> extension supports the idea
bos@686 114 of a <quote>file map</quote> that can reorganize the files and
bos@686 115 directories in a project as it imports the project's history.
bos@686 116 This is useful not only when importing history from other
bos@686 117 revision control systems, but also to prune or refactor a
bos@686 118 Mercurial tree.</para>
bos@686 119
bos@688 120 <para id="x_6f4">To specify a file map, use the <option>--filemap</option>
bos@686 121 option and supply a file name. A file map contains lines of the
bos@686 122 following forms.</para>
bos@686 123
bos@686 124 <programlisting># This is a comment.
bos@686 125 # Empty lines are ignored.
bos@686 126
bos@686 127 include path/to/file
bos@686 128
bos@686 129 exclude path/to/file
bos@686 130
bos@686 131 rename from/some/path to/some/other/place
bos@686 132 </programlisting>
bos@686 133
bos@688 134 <para id="x_6f5">The <literal>include</literal> directive causes a file, or
bos@686 135 all files under a directory, to be included in the destination
bos@686 136 repository. This also excludes all other files and dirs not
bos@686 137 explicitely included. The <literal>exclude</literal>
bos@686 138 directive causes files or directories to be omitted, and
bos@686 139 others not explicitly mentioned to be included.</para>
bos@686 140
bos@688 141 <para id="x_6f6">To move a file or directory from one location to another,
bos@686 142 use the <literal>rename</literal> directive. If you need to
bos@686 143 move a file or directory from a subdirectory into the root of
bos@686 144 the repository, use <literal>.</literal> as the second
bos@686 145 argument to the <literal>rename</literal> directive.</para>
bos@686 146 </sect2>
bos@686 147 </sect1>
bos@686 148
bos@686 149 <sect1>
bos@686 150 <title>Migrating from Subversion</title>
bos@686 151
bos@688 152 <para id="x_6f7">Subversion is currently the most popular open source
bos@686 153 revision control system. Although there are many differences
bos@686 154 between Mercurial and Subversion, making the transition from
bos@686 155 Subversion to Mercurial is not particularly difficult. The two
bos@686 156 have similar command sets and generally uniform
bos@686 157 interfaces.</para>
bos@686 158
bos@686 159 <sect2>
bos@686 160 <title>Philosophical differences</title>
bos@686 161
bos@688 162 <para id="x_6f8">The fundamental difference between Subversion and
bos@686 163 Mercurial is of course that Subversion is centralized, while
bos@686 164 Mercurial is distributed. Since Mercurial stores all of a
bos@686 165 project's history on your local drive, it only needs to
bos@686 166 perform a network access when you want to explicitly
bos@686 167 communicate with another repository. In contrast, Subversion
bos@686 168 stores very little information locally, and the client must
bos@686 169 thus contact its server for many common operations.</para>
bos@686 170
bos@688 171 <para id="x_6f9">Subversion more or less gets away without a well-defined
bos@686 172 notion of a branch: which portion of a server's namespace
bos@686 173 qualifies as a branch is a matter of convention, with the
bos@686 174 software providing no enforcement. Mercurial treats a
bos@686 175 repository as the unit of branch management.</para>
bos@686 176
bos@686 177 <sect3>
bos@686 178 <title>Scope of commands</title>
bos@686 179
bos@688 180 <para id="x_6fa">Since Subversion doesn't know what parts of its
bos@686 181 namespace are really branches, it treats most commands as
bos@686 182 requests to operate at and below whatever directory you are
bos@686 183 currently visiting. For instance, if you run <command>svn
bos@686 184 log</command>, you'll get the history of whatever part of
bos@686 185 the tree you're looking at, not the tree as a whole.</para>
bos@686 186
bos@688 187 <para id="x_6fb">Mercurial's commands behave differently, by defaulting
bos@686 188 to operating over an entire repository. Run <command>hg
bos@686 189 log</command> and it will tell you the history of the
bos@686 190 entire tree, no matter what part of the working directory
bos@686 191 you're visiting at the time. If you want the history of
bos@686 192 just a particular file or directory, simply supply it by
bos@686 193 name, e.g. <command>hg log src</command>.</para>
bos@686 194
bos@688 195 <para id="x_6fc">From my own experience, this difference in default
bos@686 196 behaviors is probably the most likely to trip you up if you
bos@686 197 have to switch back and forth frequently between the two
bos@686 198 tools.</para>
bos@686 199 </sect3>
bos@686 200
bos@686 201 <sect3>
bos@686 202 <title>Multi-user operation and safety</title>
bos@686 203
bos@688 204 <para id="x_6fd">With Subversion, it is normal (though slightly frowned
bos@686 205 upon) for multiple people to collaborate in a single branch.
bos@686 206 If Alice and Bob are working together, and Alice commits
bos@686 207 some changes to their shared branch, Bob must update his
bos@686 208 client's view of the branch before he can commit. Since at
bos@686 209 this time he has no permanent record of the changes he has
bos@686 210 made, he can corrupt or lose his modifications during and
bos@686 211 after his update.</para>
bos@686 212
bos@688 213 <para id="x_6fe">Mercurial encourages a commit-then-merge model instead.
bos@686 214 Bob commits his changes locally before pulling changes from,
bos@686 215 or pushing them to, the server that he shares with Alice.
bos@686 216 If Alice pushed her changes before Bob tries to push his, he
bos@686 217 will not be able to push his changes until he pulls hers,
bos@686 218 merges with them, and commits the result of the merge. If
bos@686 219 he makes a mistake during the merge, he still has the option
bos@686 220 of reverting to the commit that recorded his changes.</para>
bos@686 221
bos@688 222 <para id="x_6ff">It is worth emphasizing that these are the common ways
bos@686 223 of working with these tools. Subversion supports a safer
bos@686 224 work-in-your-own-branch model, but it is cumbersome enough
bos@686 225 in practice to not be widely used. Mercurial can support
bos@686 226 the less safe mode of allowing changes to be pulled in and
bos@686 227 merged on top of uncommitted edits, but this is considered
bos@686 228 highly unusual.</para>
bos@686 229 </sect3>
bos@686 230
bos@686 231 <sect3>
bos@686 232 <title>Published vs local changes</title>
bos@686 233
bos@688 234 <para id="x_700">A Subversion <command>svn commit</command> command
bos@686 235 immediately publishes changes to a server, where they can be
bos@686 236 seen by everyone who has read access.</para>
bos@686 237
bos@688 238 <para id="x_701">With Mercurial, commits are always local, and must be
bos@686 239 published via a <command>hg push</command> command
bos@686 240 afterwards.</para>
bos@686 241
bos@688 242 <para id="x_702">Each approach has its advantages and disadvantages. The
bos@686 243 Subversion model means that changes are published, and hence
bos@686 244 reviewable and usable, immediately. On the other hand, this
bos@686 245 means that a user must have commit access to a repository in
bos@686 246 order to use the software in a normal way, and commit access
bos@686 247 is not lightly given out by most open source
bos@686 248 projects.</para>
bos@686 249
bos@688 250 <para id="x_703">The Mercurial approach allows anyone who can clone a
bos@686 251 repository to commit changes without the need for someone
bos@686 252 else's permission, and they can then publish their changes
bos@686 253 and continue to participate however they see fit. The
bos@686 254 distinction between committing and pushing does open up the
bos@686 255 possibility of someone committing changes to their laptop
bos@686 256 and walking away for a few days having forgotten to push
bos@686 257 them, which in rare cases might leave collaborators
bos@686 258 temporarily stuck.</para>
bos@686 259 </sect3>
bos@686 260 </sect2>
bos@686 261
bos@686 262 <sect2>
bos@686 263 <title>Quick reference</title>
bos@686 264
bos@686 265 <table>
bos@686 266 <title>Subversion commands and Mercurial equivalents</title>
bos@686 267 <tgroup cols="3">
bos@686 268 <thead>
bos@686 269 <row>
bos@686 270 <entry>Subversion</entry>
bos@686 271 <entry>Mercurial</entry>
bos@686 272 <entry>Notes</entry>
bos@686 273 </row>
bos@686 274 </thead>
bos@686 275 <tbody>
bos@686 276 <row>
bos@686 277 <entry><command>svn add</command></entry>
bos@686 278 <entry><command>hg add</command></entry>
bos@686 279 <entry></entry>
bos@686 280 </row>
bos@686 281 <row>
bos@686 282 <entry><command>svn blame</command></entry>
bos@686 283 <entry><command>hg annotate</command></entry>
bos@686 284 <entry></entry>
bos@686 285 </row>
bos@686 286 <row>
bos@686 287 <entry><command>svn cat</command></entry>
bos@686 288 <entry><command>hg cat</command></entry>
bos@686 289 <entry></entry>
bos@686 290 </row>
bos@686 291 <row>
bos@686 292 <entry><command>svn checkout</command></entry>
bos@686 293 <entry><command>hg clone</command></entry>
bos@686 294 <entry></entry>
bos@686 295 </row>
bos@686 296 <row>
bos@686 297 <entry><command>svn cleanup</command></entry>
bos@686 298 <entry>n/a</entry>
bos@686 299 <entry>No cleanup needed</entry>
bos@686 300 </row>
bos@686 301 <row>
bos@686 302 <entry><command>svn commit</command></entry>
bos@686 303 <entry><command>hg commit</command>; <command>hg
bos@686 304 push</command></entry>
bos@686 305 <entry><command>hg push</command> publishes after
bos@686 306 commit</entry>
bos@686 307 </row>
bos@686 308 <row>
bos@686 309 <entry><command>svn copy</command></entry>
bos@686 310 <entry><command>hg clone</command></entry>
bos@686 311 <entry>To create a new branch</entry>
bos@686 312 </row>
bos@686 313 <row>
bos@686 314 <entry><command>svn copy</command></entry>
bos@686 315 <entry><command>hg copy</command></entry>
bos@686 316 <entry>To copy files or directories</entry>
bos@686 317 </row>
bos@686 318 <row>
bos@686 319 <entry><command>svn delete</command> (<command>svn
bos@686 320 remove</command>)</entry>
bos@686 321 <entry><command>hg remove</command></entry>
bos@686 322 <entry></entry>
bos@686 323 </row>
bos@686 324 <row>
bos@686 325 <entry><command>svn diff</command></entry>
bos@686 326 <entry><command>hg diff</command></entry>
bos@686 327 <entry></entry>
bos@686 328 </row>
bos@686 329 <row>
bos@686 330 <entry><command>svn export</command></entry>
bos@686 331 <entry><command>hg archive</command></entry>
bos@686 332 <entry></entry>
bos@686 333 </row>
bos@686 334 <row>
bos@686 335 <entry><command>svn help</command></entry>
bos@686 336 <entry><command>hg help</command></entry>
bos@686 337 <entry></entry>
bos@686 338 </row>
bos@686 339 <row>
bos@686 340 <entry><command>svn import</command></entry>
bos@686 341 <entry><command>hg addremove</command>; <command>hg
bos@686 342 commit</command></entry>
bos@686 343 <entry></entry>
bos@686 344 </row>
bos@686 345 <row>
bos@686 346 <entry><command>svn info</command></entry>
bos@686 347 <entry><command>hg parents</command></entry>
bos@686 348 <entry>Shows what revision is checked out</entry>
bos@686 349 </row>
bos@686 350 <row>
bos@686 351 <entry><command>svn info</command></entry>
bos@686 352 <entry><command>hg showconfig
bos@686 353 paths.parent</command></entry>
bos@686 354 <entry>Shows what URL is checked out</entry>
bos@686 355 </row>
bos@686 356 <row>
bos@686 357 <entry><command>svn list</command></entry>
bos@686 358 <entry><command>hg manifest</command></entry>
bos@686 359 <entry></entry>
bos@686 360 </row>
bos@686 361 <row>
bos@686 362 <entry><command>svn log</command></entry>
bos@686 363 <entry><command>hg log</command></entry>
bos@686 364 <entry></entry>
bos@686 365 </row>
bos@686 366 <row>
bos@686 367 <entry><command>svn merge</command></entry>
bos@686 368 <entry><command>hg merge</command></entry>
bos@686 369 <entry></entry>
bos@686 370 </row>
bos@686 371 <row>
bos@686 372 <entry><command>svn mkdir</command></entry>
bos@686 373 <entry>n/a</entry>
bos@686 374 <entry>Mercurial does not track directories</entry>
bos@686 375 </row>
bos@686 376 <row>
bos@686 377 <entry><command>svn move</command> (<command>svn
bos@686 378 rename</command>)</entry>
bos@686 379 <entry><command>hg rename</command></entry>
bos@686 380 <entry></entry>
bos@686 381 </row>
bos@686 382 <row>
bos@686 383 <entry><command>svn resolved</command></entry>
bos@686 384 <entry><command>hg resolve -m</command></entry>
bos@686 385 <entry></entry>
bos@686 386 </row>
bos@686 387 <row>
bos@686 388 <entry><command>svn revert</command></entry>
bos@686 389 <entry><command>hg revert</command></entry>
bos@686 390 <entry></entry>
bos@686 391 </row>
bos@686 392 <row>
bos@686 393 <entry><command>svn status</command></entry>
bos@686 394 <entry><command>hg status</command></entry>
bos@686 395 <entry></entry>
bos@686 396 </row>
bos@686 397 <row>
bos@686 398 <entry><command>svn update</command></entry>
bos@686 399 <entry><command>hg pull -u</command></entry>
bos@686 400 <entry></entry>
bos@686 401 </row>
bos@686 402 </tbody>
bos@686 403 </tgroup>
bos@686 404 </table>
bos@686 405 </sect2>
bos@686 406 </sect1>
bos@686 407
bos@686 408 <sect1>
bos@686 409 <title>Useful tips for newcomers</title>
bos@686 410
bos@688 411 <para id="x_704">Under some revision control systems, printing a diff for a
bos@686 412 single committed revision can be painful. For instance, with
bos@686 413 Subversion, to see what changed in revision 104654, you must
bos@686 414 type <command>svn diff -r104653:104654</command>. Mercurial
bos@686 415 eliminates the need to type the revision ID twice in this common
bos@686 416 case. For a plain diff, <command>hg export 104654</command>. For
bos@686 417 a log message followed by a diff, <command>hg log -r104654
bos@686 418 -p</command>.</para>
bos@686 419
bos@688 420 <para id="x_705">When you run <command>hg status</command> without any
bos@686 421 arguments, it prints the status of the entire tree, with paths
bos@686 422 relative to the root of the repository. This makes it tricky to
bos@686 423 copy a file name from the output of <command>hg status</command>
bos@686 424 into the command line. If you supply a file or directory name
bos@686 425 to <command>hg status</command>, it will print paths relative to
bos@686 426 your current location instead. So to get tree-wide status from
bos@686 427 <command>hg status</command>, with paths that are relative to
bos@686 428 your current directory and not the root of the repository, feed
bos@686 429 the output of <command>hg root</command> into <command>hg
bos@686 430 status</command>. You can easily do this as follows on a
bos@686 431 Unix-like system:</para>
bos@686 432
bos@686 433 <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
bos@686 434 </sect1>
bos@559 435 </appendix>
bos@559 436
bos@559 437 <!--
bos@559 438 local variables:
bos@559 439 sgml-parent-document: ("00book.xml" "book" "appendix")
bos@559 440 end:
bos@559 441 -->