Configuring Mercurial

Before using Mercurial to make Eigen changes/patches, please make sure that you have configured it as described in this section. To do so, edit (or create) your mercurial config file.

On Unix-like systems, the global config file is ~/.hgrc

On Windows systems, the global config file is Mercurial.ini in your home directory

Note that if you need a different mercurial config for another project, you can also use a per-clone config file: .hg/hgrc inside the clone directory. We recommend using the global config file unless you really know what you are doing.

Undoing uncommitted changes

Undoing a local commit

In case you want to undo a local commit, e.g. to deal with typos in the commit log or similar, do:

$ hg rollback # roll back the last transaction

Notice that this will only undo the committing action. See previous section for undoing the changes to your working copy.

Only use this technique for local commits. Otherwise, it doesn't make sense, since it cannot be guaranteed that other users already pulled in public changes.

Generating a patch

Once you have made a local commit, you can generate a patch from it:

$ hg export tip > somefile

Here, 'tip' means the latest revision. Try "hg help export" to see other options. This generates a file that you can then attach to a bug report or to an e-mail to the Eigen mailing list. If you have properly configured your identity as above before committing, then importing your patch will properly credit you.

Pushing the local changes to the central repository

Once you have made a local commit, you can push it to the central repository.

$ hg out # to check what you are actually pushing
$ hg push # push your commits. No need to give the repository if this is the one cloned

You may see this error message:

abort: push creates new remote heads!
(did you forget to merge? use push -f to force)

This means that one of your modified files has been modified meanwhile in the repository. You need to merge before you can push: see next section. Do not use push -f as mentioned in that message, as there may be a conflict to resolve manually.

Merge changes from another repository

$ hg in <repo> # check what's coming in
$ hg pull <repo> # pull changesets from <repo>
$ hg merge # merge the new tip from <repo> into our working directory
$ hg parents # see the revisions that have been merged into the working directory
$ hg commit # commit the result of the merge

But you can also enable a couple of extensions that provide fancier views. Edit (or create) your global .hgrc file (in your home directory) and add these lines:

[extensions]
hgk=
hgext.graphlog =

You can now enjoy a graphical view of the commit history:

$ hgk # or try 'hg view' if that doesn't work

Or if you prefer a plain text output of the graph:

$ hg glog

Finally, if you want something more powerful, have a look at the following external programs: hgtk and hgview. Hgtk allows many things, like viewing only as specific branch, viewing only merges, etc. Do:

Advanced usage

Porting a changeset to another branch

First of all, you should a separate local clone for each of the branches that you're interested in. If you want to transplant a changeset, say, from the default branch to the 2.0 branch, enter your clone of the 2.0 branch, make sure that you have pulled the changeset that you want to transplant, and do:

Mercurial Queues

If you're feeling dangerous today, read about Mercurial Queues. This makes Mercurial about as dangerous as Git.

Pushing many local commits as a single one

If you want to do this, you want Mercurial Queues, see above. Specifically, the qfold command. If you're not very comfortable with Mercurial, don't bother.

Splitting a patch into smaller patches

The best way to do that is using the Crecord extension. It has an interactive interface to let you select line-by-line or hunk-by-hunk how to split your patch.

This extension also provides a 'hg qcrecord' command to interoperation with Mercurial Queues, making it even more powerful. We explain it there.

Rebasing changesets

Warning: rebasing is not something trivial, and can break a repository. Typically, if you push changes, then do some rebasing, this is a very bad thing. The remote repository might get corrupted.

The most obvious way is to use 'hg rebase', or 'hg update --rebase'. See respective documentation.

If you are such a power user that you know how to use Mercurial Queus (MQ, see above), this is another way to do almost automatic rebasing. Once your changeset is a MQ patch, you can pop it, update your hg repository to another changeset, and push it again.

Receiving commit notification

The Bitbucket web interface offers RSS and Atom feeds.

If you prefer email notification, subscribe to the eigen-commits mailing list. Instructions are the same as for the eigen mailing list, just replace "eigen" by "eigen-commits" everywhere.

Search and replace on whole directory

If you do a search-and-replace operation on a whole directory, you probably do not want it to affect Mercurial's own internal files! So you must avoid all .hg directories. You can do:

Make a new release

These days it's very easy, as the docs are automatically generated and uploaded by Thomas' machine, and the tarballs are auto-generated by Bitbucket.

So here's what it takes to make a new release (a new minor version):

Announce a week in advance on the eigen mailing list the upcoming release (give a precise date) so that people can test and/or speak up if they know of an issue. Of course, in case of an emergency, no need to do that :)

Concert with other devs, and/or use CDash, and/or test yourself, to make sure that the test suite passes at the very least for:

latest stable GCC

some older GCC 4.x (ok, it's hard to check them all), try to cover the oldest GCC we're supposed to support (see main page)

latest MSVC

latest Clang

Also do think to check "make install"! Remember how it spoiled the 2.0.7 release!

Supreme refinement would be to check building the test suite against the installed Eigen.

Update the version number (EIGEN_MINOR_VERSION, etc) in the file Eigen/src/Core/util/Macros.h.

In the 2.0 branch, also update the version number in the root CMakeLists.txt. That doesn't apply to the default branch.

commit that:

$ hg commit

Make a tag:

$ hg tag 4.5.6-beta7

recommended: check that everything is in order.

$ hg view

push the release:

$ hg push

For a minor version: make the full changelog. It's not just a dump of the commit messages: it must be readable and interesting for Eigen users. You can use "hg view" again, try to put the grave bug fixes first, try to group together what's related.

Update the Main Page on the wiki, that is the announcement at the top and the Download section. Make sure that the tarball links point to the new release, and that any example of how to get the latest tag also refers to the new tag.