Mercurial is an open-source source code management tool that is available on a wide variety of platforms (windows, OSX, Linux, etc.).

A lot of documentation about how to use mercurial can be found elsewhere:

  • If you are new to source code management tools, we suggest that you start with the mercurial book which is both an extensive introduction to source code management, mercurial concepts, as well as a reference on how to use mercurial efficiently.
  • If you are already familiar with tools such as cvs, svn, or git but not mercurial, keeping around the cheat sheet (such as this or this) while reading the following is helpful.
  • If you are knowledgeable about mercurial but have some questions on how to use it, consult its extensive documentation available from the main website and the wiki

The url to ns-3 repositories

The ns-3 server which hosts our mercurial repositories allow read-only access for all repositories through http and read-write access through ssh.

The read-only url for all our repositories is either http://code.nsnam.org/REPO or http://code.nsnam.org/USER/REPO. All of these repositories can be listed by visiting this url.

The read-write access for all our repositories takes two forms: ssh://code@code.nsnam.org/REPO or ssh://USER@code.nsnam.org/repositories/USER/REPO. To obtain read-write access to one of these repositories, one should send an ssh public key on the ns-developers mailing-list.

Undoing local changes before commit

hg revert [FILE/DIR]: revert the state of your local checkout to what it was upon your last update.

Undoing a commit

There are two ways to do this:

  • If you have already published your repository and others have cloned it, you should use hg backout -r REV to commit a new change in the mercurial history which undos the previous commit.
  • If you don’t care about wreaking havoc on your users who cloned your repository or if you have never published it, you could use hg rollback to remove the last commit from the mercurial history. BEWARE that this operation loses history and is undoable. Use with caution.

Renaming a file

hg rename old-file-name new-file-name This is preferable to adding the new file name and removing the old file name, because it preserves revision history. Don’t forget to commit once you are done.

Synchronizing with REMOTE-URL

If you have created a local clone of an ns-3 repository, if you have worked on it, commited changes to that local repository, and if you want to synchronize with a more recent version of the original ns-3 repository, here are the steps to take:

  • cd your-clone
  • hg pull REMOTE-URL: download new history from REMOTE-URL.
  • hg merge: attempt to reconcile your local changes with remote changes
  • Check that it still works: builds, tests pass, etc.
  • hg commit -m “merge with REMOTE-URL”: commit the reconciled version
  • hg push OTHER-URL: finally, push your new history in a published repository.

Setting the username in commit logs

Each mercurial checkin is made by a user. By default, mercurial uses accountname@hostname as a username for each commit. This leads to commit logs like the following:

changeset:   7:e53ac3c458e9
 user:        tomh@powerbook.local

To avoid this, and have it print something nicer, like

changeset:   7:e53ac3c458e9
 user:        Tom Henderson <tomh@tomh.org>
</tomh@tomh.org>

you need to add an .hgrc file to your home directory, such as follows:

[ui]
 username = Tom Henderson <tomh@tomh.org>
</tomh@tomh.org>

Committing a change as another user

If you, as a maintainer, check in a patch authored by someone else, it is good practice to credit them in the commit message using the –user or -u option to hg; e.g.:

hg commit -m "...commit message..." -u "A User <a.user@example.com>"
</a.user@example.com>

Background information on the practice of recording contributors.

Avoid using LONG-URL

If you are getting tired of repeating the same LONG-URL in clone, pull, or push commands, you can define shortcuts in your .hgrc file:

[paths]
  my-repo = A-LONG-URL

And, then, you can do hg clone my-repo

Sending a commit to X

If you want to send to someone the content of a single commit, use hg export -o FILENAME REV and send the resulting file FILENAME by email.

Sending un-commited changes to X

If you want to send to someone your local uncommited changes for review, use hg diff > FILENAME and send the resulting file FILENAME by email.