Command reference

# HG changeset patch # User Bryan O'Sullivan # Date 1240813016 25200 # Node ID e9154b3daa94b048225db9bcf5cab55138acc1aa # Parent 6b7818eb3d8e9051da382d8c24a14496c26fb4fd Repurpose appendix A. diff -r 6b7818eb3d8e -r e9154b3daa94 en/00book.xml --- 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 @@ - + @@ -96,6 +96,8 @@ &ch12; &ch13; + + &appA; &appB; diff -r 6b7818eb3d8e -r e9154b3daa94 en/appA-cmdref.xml --- 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 @@ - - - - -Command reference - -\cmdref{add}{add files at the next commit} -\optref{add}{I}{include} -\optref{add}{X}{exclude} -\optref{add}{n}{dry-run} - -\cmdref{diff}{print changes in history or working directory} - -Show differences between revisions for the specified files or -directories, using the unified diff format. For a description of the -unified diff format, see . - -By default, this command does not print diffs for files that Mercurial -considers to contain binary data. To control this behavior, see the - and options. - - -Options -x -\loptref{diff}{nodates} - -Omit date and time information when printing diff headers. - -\optref{diff}{B}{ignore-blank-lines} - -Do not print changes that only insert or delete blank lines. A line -that contains only whitespace is not considered blank. - - -\optref{diff}{I}{include} - - -Include files and directories whose names match the given patterns. - - -\optref{diff}{X}{exclude} - - -Exclude files and directories whose names match the given patterns. - - -\optref{diff}{a}{text} - - -If this option is not specified, hg diff will refuse to print -diffs for files that it detects as binary. Specifying -forces hg diff to treat all files as text, and generate diffs for -all of them. - - -This option is useful for files that are mostly text 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. - - -\optref{diff}{b}{ignore-space-change} - - -Do not print a line if the only change to that line is in the amount -of white space it contains. - - -\optref{diff}{g}{git} - - -Print git-compatible diffs. XXX reference a format -description. - - -\optref{diff}{p}{show-function} - - -Display the name of the enclosing function in a hunk header, using a -simple heuristic. This functionality is enabled by default, so the - option has no effect unless you change the value of -the showfunc config item, as in the following example. - - - -\optref{diff}{r}{rev} - - -Specify one or more revisions to compare. The hg diff command -accepts up to two options to specify the revisions to -compare. - - - -Display the differences between the parent revision of the - working directory and the working directory. - - -Display the differences between the specified changeset and the - working directory. - - -Display the differences between the two specified changesets. - - - -You can specify two revisions using either two -options or revision range notation. For example, the two revision -specifications below are equivalent. - -hg diff -r 10 -r 20 -hg diff -r10:20 - -When you provide two revisions, Mercurial treats the order of those -revisions as significant. Thus, hg diff -r10:20 will -produce a diff that will transform files from their contents as of -revision 10 to their contents as of revision 20, while -hg diff -r20:10 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. - - -\optref{diff}{w}{ignore-all-space} - - -\cmdref{version}{print version and copyright information} - - -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. - - -The string unknown. This version of Mercurial was - not built in a Mercurial repository, and cannot determine its own - version. - - -A short numeric string, such as 1.1. 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.) - - -A hexadecimal string, such as 875489e31abe. This - is a build of the given revision of Mercurial. - - -A hexadecimal string followed by a date, such as - 875489e31abe+20070205. This is a build of the given - revision of Mercurial, where the build repository contained some - local changes that had not been committed. - - - - - -Tips and tricks - - -Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ? - -When you run the hg status 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 hg diff command, you may notice that it -prints diffs for only a subset of the files that hg status -listed. There are two possible reasons for this. - - -The first is that hg status prints some kinds of modifications -that hg diff doesn't normally display. The hg diff 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. - - -If you use the option to hg diff, it will -display git-compatible diffs that can display this -extra information. - - -The second possible reason that hg diff might be printing diffs -for a subset of the files displayed by hg status is that if you -invoke it without any arguments, hg diff prints diffs against the -first parent of the working directory. If you have run hg merge -to merge two changesets, but you haven't yet committed the results of -the merge, your working directory has two parents (use hg parents -to see them). While hg status prints modifications relative to -both parents after an uncommitted merge, hg diff 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. There is no way to print diffs relative to -both parents. - - - - -Generating safe binary diffs - -If you use the option to force Mercurial to print -diffs of files that are either mostly text or contain lots of -binary data, those diffs cannot subsequently be applied by either -Mercurial's hg import command or the system's patch -command. - - -If you want to generate a diff of a binary file that is safe to use as -input for hg import, use the hg diff{--git} option when you -generate the patch. The system patch command cannot handle -binary patches at all. - - - - - - - diff -r 6b7818eb3d8e -r e9154b3daa94 en/appA-svn.xml --- /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 @@ + + + + +Migrating to Mercurial + + 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. + + 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. + + + Importing history from another system + + Mercurial ships with an extension named + convert, 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: + + + Subversion + + + CVS + + + git + + + Darcs + + + Bazaar + + + Monotone + + + GNU Arch + + + Mercurial + + + + (To see why Mercurial itself is supported as a source, see + .) + + You can enable the extension in the usual way, by editing + your ~/.hgrc file. + + [extensions] +convert = + + This will make a hg convert 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. + + $ hg convert http://python-nose.googlecode.com/svn/trunk + + The convert extension operates + incrementally. In other words, after you have run hg + convert once, running it again will import any new + revisions committed after the first run began. Incremental + conversion will only work if you run hg + convert in the same Mercurial repository that you + originally used, because the convert + extension saves some private metadata in a + non-revision-controlled file named + .hg/shamap inside the target + repository. + + + Mapping user names + + 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. + + 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 to hg convert. This option accepts + a file name that should contain entries of the following + form. + + arist = Aristotle <aristotle@phil.example.gr> +soc = Socrates <socrates@phil.example.gr> + + Whenever convert encounters a commit + with the username arist in the source + repository, it will use the name Aristotle + <aristotle@phil.example.gr> in the converted + Mercurial revision. If no match is found for a name, it is + used verbatim. + + + + Tidying up the tree + + 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. + + The convert extension supports the idea + of a file map 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. + + To specify a file map, use the + option and supply a file name. A file map contains lines of the + following forms. + + # This is a comment. +# Empty lines are ignored. + +include path/to/file + +exclude path/to/file + +rename from/some/path to/some/other/place + + + The include 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 exclude + directive causes files or directories to be omitted, and + others not explicitly mentioned to be included. + + To move a file or directory from one location to another, + use the rename directive. If you need to + move a file or directory from a subdirectory into the root of + the repository, use . as the second + argument to the rename directive. + + + + + Migrating from Subversion + + 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. + + + Philosophical differences + + 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. + + 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. + + + Scope of commands + + 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 svn + log, you'll get the history of whatever part of + the tree you're looking at, not the tree as a whole. + + Mercurial's commands behave differently, by defaulting + to operating over an entire repository. Run hg + log 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. hg log src. + + 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. + + + + Multi-user operation and safety + + 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. + + 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. + + 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. + + + + Published vs local changes + + A Subversion svn commit command + immediately publishes changes to a server, where they can be + seen by everyone who has read access. + + With Mercurial, commits are always local, and must be + published via a hg push command + afterwards. + + 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. + + 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. + + + + + Quick reference + + + Subversion commands and Mercurial equivalents + + + + Subversion + Mercurial + Notes + + + + + svn add + hg add + + + + svn blame + hg annotate + + + + svn cat + hg cat + + + + svn checkout + hg clone + + + + svn cleanup + n/a + No cleanup needed + + + svn commit + hg commit; hg + push + hg push publishes after + commit + + + svn copy + hg clone + To create a new branch + + + svn copy + hg copy + To copy files or directories + + + svn delete (svn + remove) + hg remove + + + + svn diff + hg diff + + + + svn export + hg archive + + + + svn help + hg help + + + + svn import + hg addremove; hg + commit + + + + svn info + hg parents + Shows what revision is checked out + + + svn info + hg showconfig + paths.parent + Shows what URL is checked out + + + svn list + hg manifest + + + + svn log + hg log + + + + svn merge + hg merge + + + + svn mkdir + n/a + Mercurial does not track directories + + + svn move (svn + rename) + hg rename + + + + svn resolved + hg resolve -m + + + + svn revert + hg revert + + + + svn status + hg status + + + + svn update + hg pull -u + + + + +

+ + + + + Useful tips for newcomers + + 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 svn diff -r104653:104654. Mercurial + eliminates the need to type the revision ID twice in this common + case. For a plain diff, hg export 104654. For + a log message followed by a diff, hg log -r104654 + -p. + + When you run hg status 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 hg status + into the command line. If you supply a file or directory name + to hg status, it will print paths relative to + your current location instead. So to get tree-wide status from + hg status, with paths that are relative to + your current directory and not the root of the repository, feed + the output of hg root into hg + status. You can easily do this as follows on a + Unix-like system: + + $ hg status `hg root` + + + +