How to Work with Mercurial Author: Sjoerd Mullender Organization: CWI, MonetDB B.V. Abstract The MonetDB repository has moved from CVS on Sourceforge to Mercurial on dev.monetdb.org. In this document, we give an introduction to the use of Mercurial, specifically for MonetDB. Introduction A nice tutorial about how to use Mercurial, aimed at Subversion (SVN) users (although CVS users will understand the Subversion references fine) can be found at http://hginit.com/. There is also a Mercurial book. You can read it online at http://hgbook.red-bean.com/. The main website for Mercurial is https://www.mercurial-scm.org/. There is also a lot of information there, including information about all sorts of nifty extensions. The Basics Mercurial (and git, for that matter) work around the concept of changesets where both CVS and SVN work around the concept of revisions. A revision is basically what the project (or a particular file in the case of CVS) looks like at any particular point in time. A changeset is basically a set of changes. Both CVS and SVN are centralized systems where there is one "truth", the central repository, and every developer has one particular revision on their disk (usually the latest). When you make a change, you upload the new version to the server (known as commit). If another developer was there first, the commit fails. You first need to update your own copy from the central repository, merging any changes in the process, and, when that was successful, try the commit again. Mercurial works differently. Every developer has a complete copy (a clone) of the repository on their disk. When you make a change, you can commit it to your local copy of the repository, independently of any other developers. Since this work is independent of others, you can commit smaller changes that are not yet finished and that do not yet work. When you are satisfied with the changes, you can share them with others by pushing the changes to the central repository. Before you push changes, you may first have to pull in changes from others that had already been pushed by them. Pushing and pulling are mirror operations. What they do is compare the collections of changes (the changesets) in the originating and destination repositories, and copy over all changes that are in the originating repository but not yet in the destination. After you pull in changes, you need to update your working files. In the process you may have to resolve conflicting changes. Because every developer has their own copy of the repository, and every developer makes changes and gets other developers' changes in a different order, the histories of different copies of the repository are different. You can see that in the log of the repository. In Mercurial, changesets are identified by two numbers. A relatively small number that is easy to use (the local revision number), and a large, hexadecimal number (the global revision id). The local revision number is per clone. It indicates the order in which changesets were added to the repository, but has no other significance. The global revision id identifies the changeset across clones. Different developers will have different local revision numbers for the same change, but they will have the same global revision id. Each changeset depends on other changes that came before. However, a changeset does not depend on all previous changes, since some changes were made independently from each other. A changeset records its parent changeset. In fact, in Mercurial a changeset can have up to two parents. When a changeset has two parents, it is the result of a merge. A changeset that is not the parent of other changesets (i.e. it doesn't have any children) is called a head. Mercurial wants to minimize the number of heads in a clone, so it will warn when an operation creates an extra head and will often refuse to perform the operation altogether. Combining heads is called a merge. As far as Mercurial is concerned, each changeset you add (i.e. each commit) depends on the last changeset. However, this is of course not always really true since often different changes are orthogonal to each other. It is possible to tell Mercurial to change the parent of a changeset to some other changeset. This is called rebasing the changeset. Configuration Before you do anything else, it is a good idea to take care of some necessary configuration. Mercurial reads a number of configuration files. Configuration settings in later ones in the list below override settings in earlier ones. • System configuration file, typically in /etc/mercurial. • User-specific configuration file, typically in $HOME/.hgrc (on Windows also %USERPROFILE%\.hgrc, %USERPROFILE%\Mercurial.ini, and %HOME%\Mercurial.ini). • Repository-specific configuration file in .hg/hgrc within the clone. The configuration files all share the same syntax, the Windows INI file syntax, consisting of sections headed by a header in square brackets, and within each section key=value pairs. See the manual hgrc(5) and hg help config for more information. If you're using Mercurial only for MonetDB, you can add all the configurations that are mentioned below to the file $HOME/.hgrc. Otherwise you need to decide which configuration settings can be used for all your Mercurial clones and which should be specific to a clone. If you choose to use clone-specific configuration settings, you do need to make sure that the settings are added to each clone after they have been created. Important Configuration Your Name The minimal configuration consists of telling Mercurial who you are. This is typically done in the user-specific configuration file. Add the following (with appropriate changes) to your configuration file: [ui] username = My Name <[email protected]> Note that the name is actually used by the system in the From address in mails that are sent to the checkin mailing list to notify people of changes and thus the address is public. Line Endings On Windows, text files use the CRLF (Carriage Return - Line Feed) combination as end-of-line indicators, whereas Unix/Linux (including MacOS) uses only LF (Line Feed). On both sets of systems, many programs can deal with either convention, but some programs get confused, and if a file with one type of line ending is edited on a system using the other type, it may well be that all line endings are converted. This would cause a massive change to the file, affecting all lines. This would be very bad. For this reason, it is important that Mercurial converts line endings for you, if needed. However, binary files, such as images, must not be converted. Mercurial uses the eol extension and a file, .hgeol, in the root directory of the working set. This files contains file name patterns with declarations of the type of file (BIN, CRLF, LF, or native). The MonetDB repository already contains this file. In order to enable the line ending conversion, the following configuration needs to be added in your configuration file (this can usually be added to the user-specific file). This should be done on any system, not just on Windows. [extensions] eol = File Name Restrictions If you are on a Linux system, you are urged to fix your configuration so that file names that are not compatible with Windows won't be added. Add the following to your configuration file: [ui] portablefilenames = abort White Space Checks You are strongly urged to add the following configuration to your .hg/hgrc file in all of your MonetDB clones (or to your $HOME/.hgrc file if you don't use Mercurial for other projects). First get a copy of a non-standard extension: hg clone https://dev.monetdb.org/hg/check_whitespace/ This will create a directory check_whitespace in whatever directory you execute this in (preferably not within a clone of an existing repository). Then add the following to your configuration file: [hooks] pretxncommit.whitespace = python:<path-to-check_whitespace-directory>/check_whitespace.py:hook This is a pre transaction hook which will check whether any of the added or changed lines contains incorrect white space. Incorrect white space is currently only defined for Python source code. In Python source code, it is not allowed to have trailing white space or to have TAB characters. The hook will also check for and refuse left over conflict resolution markers and non-empty files not ending with a newline. Optional Configuration Some other configuration ideas are (use hg help extensions for more information about extensions): [extensions] # temporarily save changes shelve = There used to be an extension called autopager which would only use the pager if the output was more than a screen full. This same effect can be had by using the correct options to the program less. To do so, add a pager section: [pager] pager = less -FXR Merge Conflicts Vim users might want to use the following to resolve conflicts: [merge-tools] vimdiff.args = -X $other $local $base vimdiff.priority = 1 vimdiff.premerge = keep Using this, for each file that has a conflict, vimdiff will be started with three open files. From left to right the files are: the other file (the version that is being merged in), the local file (the one that you should be editing), and the base file (the common ancestor of your version and the incoming version). Because of the premerge setting, Mercurial will attempt to merge and start vimdiff in case there are conflicts. In the middle pane you will see the conflict markers which you must resolve. (X)Emacs users might, instead, want to use this (Replace emacs with xemacs if you're into XEmacs): [merge-tools] emacs.args = --eval "(ediff-merge-files-with-ancestor \""$local"\" \""$other"\" \""$base"\" nil \""$output"\")" emacs.priority = 1 Quoting in this and the following examples is important to get right.