Mercurial > hgbook
changeset 814:e9154b3daa94
Repurpose appendix A.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Sun, 26 Apr 2009 23:16:56 -0700 |
| parents | 6b7818eb3d8e |
| children | 0ffae4ee4c47 |
| files | en/00book.xml en/appA-cmdref.xml en/appA-svn.xml |
| diffstat | 3 files changed, 444 insertions(+), 225 deletions(-) [+] |
line wrap: on
line diff
--- a/en/00book.xml Fri Apr 24 00:31:21 2009 -0700 +++ b/en/00book.xml Sun Apr 26 23:16:56 2009 -0700 @@ -21,7 +21,7 @@ <!ENTITY ch11 SYSTEM "ch11-mq.xml"> <!ENTITY ch12 SYSTEM "ch12-mq-collab.xml"> <!ENTITY ch13 SYSTEM "ch13-hgext.xml"> -<!ENTITY appA SYSTEM "appA-cmdref.xml"> +<!ENTITY appA SYSTEM "appA-svn.xml"> <!ENTITY appB SYSTEM "appB-mq-ref.xml"> <!ENTITY appC SYSTEM "appC-srcinstall.xml"> <!ENTITY appD SYSTEM "appD-license.xml"> @@ -96,6 +96,8 @@ &ch12; <!-- BEGIN ch13 --> &ch13; + <!-- BEGIN appA --> + &appA; <!-- BEGIN appB --> &appB; <!-- BEGIN appC -->
--- a/en/appA-cmdref.xml Fri Apr 24 00:31:21 2009 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,224 +0,0 @@ -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> - -<appendix id="cmdref"> - <?dbhtml filename="command-reference.html"?> -<title>Command reference</title> - -<para id="x_653">\cmdref{add}{add files at the next commit} -\optref{add}{I}{include} -\optref{add}{X}{exclude} -\optref{add}{n}{dry-run}</para> - -<para id="x_654">\cmdref{diff}{print changes in history or working directory}</para> - -<para id="x_655">Show differences between revisions for the specified files or -directories, using the unified diff format. For a description of the -unified diff format, see <xref linkend="sec:mq:patch"/>.</para> - -<para id="x_656">By default, this command does not print diffs for files that Mercurial -considers to contain binary data. To control this behavior, see the -<option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para> - -<sect2> -<title>Options</title> -x -<para id="x_657">\loptref{diff}{nodates}</para> - -<para id="x_658">Omit date and time information when printing diff headers.</para> - -<para id="x_659">\optref{diff}{B}{ignore-blank-lines}</para> - -<para id="x_65a">Do not print changes that only insert or delete blank lines. A line -that contains only whitespace is not considered blank. -</para> - -<para id="x_65b">\optref{diff}{I}{include} -</para> - -<para id="x_65c">Include files and directories whose names match the given patterns. -</para> - -<para id="x_65d">\optref{diff}{X}{exclude} -</para> - -<para id="x_65e">Exclude files and directories whose names match the given patterns. -</para> - -<para id="x_65f">\optref{diff}{a}{text} -</para> - -<para id="x_660">If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print -diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option> -forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for -all of them. -</para> - -<para id="x_661">This option is useful for files that are <quote>mostly text</quote> but have a -few embedded NUL characters. If you use it on files that contain a -lot of binary data, its output will be incomprehensible. -</para> - -<para id="x_662">\optref{diff}{b}{ignore-space-change} -</para> - -<para id="x_663">Do not print a line if the only change to that line is in the amount -of white space it contains. -</para> - -<para id="x_664">\optref{diff}{g}{git} -</para> - -<para id="x_665">Print <command>git</command>-compatible diffs. XXX reference a format -description. -</para> - -<para id="x_666">\optref{diff}{p}{show-function} -</para> - -<para id="x_667">Display the name of the enclosing function in a hunk header, using a -simple heuristic. This functionality is enabled by default, so the -<option role="hg-opt-diff">-p</option> option has no effect unless you change the value of -the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para> - -<!-- &interaction.cmdref.diff-p; --> - -<para id="x_668">\optref{diff}{r}{rev} -</para> - -<para id="x_669">Specify one or more revisions to compare. The <command role="hg-cmd">hg diff</command> command -accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to -compare. -</para> - -<orderedlist> -<listitem><para id="x_66a">Display the differences between the parent revision of the - working directory and the working directory. -</para> -</listitem> -<listitem><para id="x_66b">Display the differences between the specified changeset and the - working directory. -</para> -</listitem> -<listitem><para id="x_66c">Display the differences between the two specified changesets. -</para> -</listitem></orderedlist> - -<para id="x_66d">You can specify two revisions using either two <option role="hg-opt-diff">-r</option> -options or revision range notation. For example, the two revision -specifications below are equivalent. -</para> -<programlisting>hg diff -r 10 -r 20 -hg diff -r10:20</programlisting> - -<para id="x_66e">When you provide two revisions, Mercurial treats the order of those -revisions as significant. Thus, <command role="hg-cmd">hg diff -r10:20</command> will -produce a diff that will transform files from their contents as of -revision 10 to their contents as of revision 20, while -<command role="hg-cmd">hg diff -r20:10</command> means the opposite: the diff that will -transform files from their revision 20 contents to their revision 10 -contents. You cannot reverse the ordering in this way if you are -diffing against the working directory. -</para> - -<para id="x_66f">\optref{diff}{w}{ignore-all-space} -</para> - -<para id="x_670">\cmdref{version}{print version and copyright information} -</para> - -<para id="x_671">This command displays the version of Mercurial you are running, and -its copyright license. There are four kinds of version string that -you may see. -</para> -<itemizedlist> -<listitem><para id="x_672">The string <quote><literal>unknown</literal></quote>. This version of Mercurial was - not built in a Mercurial repository, and cannot determine its own - version. -</para> -</listitem> -<listitem><para id="x_673">A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a - build of a revision of Mercurial that was identified by a specific - tag in the repository where it was built. (This doesn't necessarily - mean that you're running an official release; someone else could - have added that tag to any revision in the repository where they - built Mercurial.) -</para> -</listitem> -<listitem><para id="x_674">A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>. This - is a build of the given revision of Mercurial. -</para> -</listitem> -<listitem><para id="x_675">A hexadecimal string followed by a date, such as - <quote><literal>875489e31abe+20070205</literal></quote>. This is a build of the given - revision of Mercurial, where the build repository contained some - local changes that had not been committed. -</para> -</listitem></itemizedlist> - -</sect2> -<sect2> -<title>Tips and tricks</title> - -<sect3 id="cmdref:diff-vs-status"> -<title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title> - -<para id="x_676">When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files -that Mercurial will record changes for the next time you perform a -commit. If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it -prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command> -listed. There are two possible reasons for this. -</para> - -<para id="x_677">The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications -that <command role="hg-cmd">hg diff</command> doesn't normally display. The <command role="hg-cmd">hg diff</command> command -normally outputs unified diffs, which don't have the ability to -represent some changes that Mercurial can track. Most notably, -traditional diffs can't represent a change in whether or not a file is -executable, but Mercurial records this information. -</para> - -<para id="x_678">If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will -display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this -extra information. -</para> - -<para id="x_679">The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs -for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you -invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the -first parent of the working directory. If you have run <command role="hg-cmd">hg merge</command> -to merge two changesets, but you haven't yet committed the results of -the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command> -to see them). While <command role="hg-cmd">hg status</command> prints modifications relative to -<emphasis>both</emphasis> parents after an uncommitted merge, <command role="hg-cmd">hg diff</command> still -operates relative only to the first parent. You can get it to print -diffs relative to the second parent by specifying that parent with the -<option role="hg-opt-diff">-r</option> option. There is no way to print diffs relative to -both parents. -</para> - -</sect3> -<sect3> -<title>Generating safe binary diffs</title> - -<para id="x_67a">If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print -diffs of files that are either <quote>mostly text</quote> or contain lots of -binary data, those diffs cannot subsequently be applied by either -Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command> -command. -</para> - -<para id="x_67b">If you want to generate a diff of a binary file that is safe to use as -input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you -generate the patch. The system <command>patch</command> command cannot handle -binary patches at all. -</para> - -</sect3> -</sect2> -</appendix> - -<!-- -local variables: -sgml-parent-document: ("00book.xml" "book" "appendix") -end: --->
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/en/appA-svn.xml Sun Apr 26 23:16:56 2009 -0700 @@ -0,0 +1,441 @@ +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> + +<appendix id="svn"> + <?dbhtml filename="mercurial-for-subversion-users.html"?> +<title>Migrating to Mercurial</title> + + <para>A common way to test the waters with a new revision control + tool is to experiment with switching an existing project, rather + than starting a new project from scratch.</para> + + <para>In this appendix, we discuss how to import a project's history + into Mercurial, and what to look out for if you are used to a + different revision control system.</para> + + <sect1> + <title>Importing history from another system</title> + + <para>Mercurial ships with an extension named + <literal>convert</literal>, which can import project history + from most popular revision control systems. At the time this + book was written, it could import history from the following + systems:</para> + <itemizedlist> + <listitem> + <para>Subversion</para> + </listitem> + <listitem> + <para>CVS</para> + </listitem> + <listitem> + <para>git</para> + </listitem> + <listitem> + <para>Darcs</para> + </listitem> + <listitem> + <para>Bazaar</para> + </listitem> + <listitem> + <para>Monotone</para> + </listitem> + <listitem> + <para>GNU Arch</para> + </listitem> + <listitem> + <para>Mercurial</para> + </listitem> + </itemizedlist> + + <para>(To see why Mercurial itself is supported as a source, see + <xref linkend="svn.filemap"/>.)</para> + + <para>You can enable the extension in the usual way, by editing + your <filename>~/.hgrc</filename> file.</para> + + <programlisting>[extensions] +convert =</programlisting> + + <para>This will make a <command>hg convert</command> command + available. The command is easy to use. For instance, this + command will import the Subversion history for the Nose unit + testing framework into Mercurial.</para> + + <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen> + + <para>The <literal>convert</literal> extension operates + incrementally. In other words, after you have run <command>hg + convert</command> once, running it again will import any new + revisions committed after the first run began. Incremental + conversion will only work if you run <command>hg + convert</command> in the same Mercurial repository that you + originally used, because the <literal>convert</literal> + extension saves some private metadata in a + non-revision-controlled file named + <filename>.hg/shamap</filename> inside the target + repository.</para> + + <sect2> + <title>Mapping user names</title> + + <para>Some revision control tools save only short usernames with + commits, and these can be difficult to interpret. The norm + with Mercurial is to save a committer's name and email + address, which is much more useful for talking to them after + the fact.</para> + + <para>If you are converting a tree from a revision control + system that uses short names, you can map those names to + longer equivalents by passing a <option>--authors</option> + option to <command>hg convert</command>. This option accepts + a file name that should contain entries of the following + form.</para> + + <programlisting>arist = Aristotle <aristotle@phil.example.gr> +soc = Socrates <socrates@phil.example.gr></programlisting> + + <para>Whenever <literal>convert</literal> encounters a commit + with the username <literal>arist</literal> in the source + repository, it will use the name <literal>Aristotle + <aristotle@phil.example.gr></literal> in the converted + Mercurial revision. If no match is found for a name, it is + used verbatim.</para> + </sect2> + + <sect2 id="svn.filemap"> + <title>Tidying up the tree</title> + + <para>Not all projects have pristine history. There may be a + directory that should never have been checked in, a file that + is too big, or a whole hierarchy that needs to be + refactored.</para> + + <para>The <literal>convert</literal> extension supports the idea + of a <quote>file map</quote> that can reorganize the files and + directories in a project as it imports the project's history. + This is useful not only when importing history from other + revision control systems, but also to prune or refactor a + Mercurial tree.</para> + + <para>To specify a file map, use the <option>--filemap</option> + option and supply a file name. A file map contains lines of the + following forms.</para> + + <programlisting># This is a comment. +# Empty lines are ignored. + +include path/to/file + +exclude path/to/file + +rename from/some/path to/some/other/place +</programlisting> + + <para>The <literal>include</literal> directive causes a file, or + all files under a directory, to be included in the destination + repository. This also excludes all other files and dirs not + explicitely included. The <literal>exclude</literal> + directive causes files or directories to be omitted, and + others not explicitly mentioned to be included.</para> + + <para>To move a file or directory from one location to another, + use the <literal>rename</literal> directive. If you need to + move a file or directory from a subdirectory into the root of + the repository, use <literal>.</literal> as the second + argument to the <literal>rename</literal> directive.</para> + </sect2> + </sect1> + + <sect1> + <title>Migrating from Subversion</title> + + <para>Subversion is currently the most popular open source + revision control system. Although there are many differences + between Mercurial and Subversion, making the transition from + Subversion to Mercurial is not particularly difficult. The two + have similar command sets and generally uniform + interfaces.</para> + + <sect2> + <title>Philosophical differences</title> + + <para>The fundamental difference between Subversion and + Mercurial is of course that Subversion is centralized, while + Mercurial is distributed. Since Mercurial stores all of a + project's history on your local drive, it only needs to + perform a network access when you want to explicitly + communicate with another repository. In contrast, Subversion + stores very little information locally, and the client must + thus contact its server for many common operations.</para> + + <para>Subversion more or less gets away without a well-defined + notion of a branch: which portion of a server's namespace + qualifies as a branch is a matter of convention, with the + software providing no enforcement. Mercurial treats a + repository as the unit of branch management.</para> + + <sect3> + <title>Scope of commands</title> + + <para>Since Subversion doesn't know what parts of its + namespace are really branches, it treats most commands as + requests to operate at and below whatever directory you are + currently visiting. For instance, if you run <command>svn + log</command>, you'll get the history of whatever part of + the tree you're looking at, not the tree as a whole.</para> + + <para>Mercurial's commands behave differently, by defaulting + to operating over an entire repository. Run <command>hg + log</command> and it will tell you the history of the + entire tree, no matter what part of the working directory + you're visiting at the time. If you want the history of + just a particular file or directory, simply supply it by + name, e.g. <command>hg log src</command>.</para> + + <para>From my own experience, this difference in default + behaviors is probably the most likely to trip you up if you + have to switch back and forth frequently between the two + tools.</para> + </sect3> + + <sect3> + <title>Multi-user operation and safety</title> + + <para>With Subversion, it is normal (though slightly frowned + upon) for multiple people to collaborate in a single branch. + If Alice and Bob are working together, and Alice commits + some changes to their shared branch, Bob must update his + client's view of the branch before he can commit. Since at + this time he has no permanent record of the changes he has + made, he can corrupt or lose his modifications during and + after his update.</para> + + <para>Mercurial encourages a commit-then-merge model instead. + Bob commits his changes locally before pulling changes from, + or pushing them to, the server that he shares with Alice. + If Alice pushed her changes before Bob tries to push his, he + will not be able to push his changes until he pulls hers, + merges with them, and commits the result of the merge. If + he makes a mistake during the merge, he still has the option + of reverting to the commit that recorded his changes.</para> + + <para>It is worth emphasizing that these are the common ways + of working with these tools. Subversion supports a safer + work-in-your-own-branch model, but it is cumbersome enough + in practice to not be widely used. Mercurial can support + the less safe mode of allowing changes to be pulled in and + merged on top of uncommitted edits, but this is considered + highly unusual.</para> + </sect3> + + <sect3> + <title>Published vs local changes</title> + + <para>A Subversion <command>svn commit</command> command + immediately publishes changes to a server, where they can be + seen by everyone who has read access.</para> + + <para>With Mercurial, commits are always local, and must be + published via a <command>hg push</command> command + afterwards.</para> + + <para>Each approach has its advantages and disadvantages. The + Subversion model means that changes are published, and hence + reviewable and usable, immediately. On the other hand, this + means that a user must have commit access to a repository in + order to use the software in a normal way, and commit access + is not lightly given out by most open source + projects.</para> + + <para>The Mercurial approach allows anyone who can clone a + repository to commit changes without the need for someone + else's permission, and they can then publish their changes + and continue to participate however they see fit. The + distinction between committing and pushing does open up the + possibility of someone committing changes to their laptop + and walking away for a few days having forgotten to push + them, which in rare cases might leave collaborators + temporarily stuck.</para> + </sect3> + </sect2> + + <sect2> + <title>Quick reference</title> + + <table> + <title>Subversion commands and Mercurial equivalents</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Subversion</entry> + <entry>Mercurial</entry> + <entry>Notes</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>svn add</command></entry> + <entry><command>hg add</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn blame</command></entry> + <entry><command>hg annotate</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn cat</command></entry> + <entry><command>hg cat</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn checkout</command></entry> + <entry><command>hg clone</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn cleanup</command></entry> + <entry>n/a</entry> + <entry>No cleanup needed</entry> + </row> + <row> + <entry><command>svn commit</command></entry> + <entry><command>hg commit</command>; <command>hg + push</command></entry> + <entry><command>hg push</command> publishes after + commit</entry> + </row> + <row> + <entry><command>svn copy</command></entry> + <entry><command>hg clone</command></entry> + <entry>To create a new branch</entry> + </row> + <row> + <entry><command>svn copy</command></entry> + <entry><command>hg copy</command></entry> + <entry>To copy files or directories</entry> + </row> + <row> + <entry><command>svn delete</command> (<command>svn + remove</command>)</entry> + <entry><command>hg remove</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn diff</command></entry> + <entry><command>hg diff</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn export</command></entry> + <entry><command>hg archive</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn help</command></entry> + <entry><command>hg help</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn import</command></entry> + <entry><command>hg addremove</command>; <command>hg + commit</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn info</command></entry> + <entry><command>hg parents</command></entry> + <entry>Shows what revision is checked out</entry> + </row> + <row> + <entry><command>svn info</command></entry> + <entry><command>hg showconfig + paths.parent</command></entry> + <entry>Shows what URL is checked out</entry> + </row> + <row> + <entry><command>svn list</command></entry> + <entry><command>hg manifest</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn log</command></entry> + <entry><command>hg log</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn merge</command></entry> + <entry><command>hg merge</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn mkdir</command></entry> + <entry>n/a</entry> + <entry>Mercurial does not track directories</entry> + </row> + <row> + <entry><command>svn move</command> (<command>svn + rename</command>)</entry> + <entry><command>hg rename</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn resolved</command></entry> + <entry><command>hg resolve -m</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn revert</command></entry> + <entry><command>hg revert</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn status</command></entry> + <entry><command>hg status</command></entry> + <entry></entry> + </row> + <row> + <entry><command>svn update</command></entry> + <entry><command>hg pull -u</command></entry> + <entry></entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + </sect1> + + <sect1> + <title>Useful tips for newcomers</title> + + <para>Under some revision control systems, printing a diff for a + single committed revision can be painful. For instance, with + Subversion, to see what changed in revision 104654, you must + type <command>svn diff -r104653:104654</command>. Mercurial + eliminates the need to type the revision ID twice in this common + case. For a plain diff, <command>hg export 104654</command>. For + a log message followed by a diff, <command>hg log -r104654 + -p</command>.</para> + + <para>When you run <command>hg status</command> without any + arguments, it prints the status of the entire tree, with paths + relative to the root of the repository. This makes it tricky to + copy a file name from the output of <command>hg status</command> + into the command line. If you supply a file or directory name + to <command>hg status</command>, it will print paths relative to + your current location instead. So to get tree-wide status from + <command>hg status</command>, with paths that are relative to + your current directory and not the root of the repository, feed + the output of <command>hg root</command> into <command>hg + status</command>. You can easily do this as follows on a + Unix-like system:</para> + + <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen> + </sect1> +</appendix> + +<!-- +local variables: +sgml-parent-document: ("00book.xml" "book" "appendix") +end: +-->