ns-3 Mercurial repositories

This webpage will give you a very small very short introduction to mercurial (Wikipedia entry) and how to use it. In doubt, please, refer to the mercurial documentation available at these places:

If you are a longtime CVS user, you may find this page helpful.

Install Mercurial

If you have not done so, you need to install the latest version of Mercurial. As of this writing, the latest version is 0.9.1. It can be downloaded from the mercurial website. Binary packages are shipped with most linux distributions but you can also find them from there. Installation instructions on:

Once mercurial is installed, you can check it is indeed there by running the following command:

hg version
Make sure you add a username setting in your ~/.hgrc file:
[mathieu@mathieu ns-3]$ cat ~/.hgrc
[ui]
username = Mathieu Lacage 
[mathieu@mathieu ns-3]$

Getting read-only access to the ns-3 repositories

The list of repositories available publicly is available through our web interface: the first column displayed on this page indicates the name of the repositories. To download a full local copy of one of these repositories, run:

hg clone http://code.nsnam.org/[name]
where [name] should be replaced by the name of the repository you want. For example, the following will checkout a local copy of the ns-3 source tree (developmental tree ns-3-dev):
hg clone http://code.nsnam.org/ns-3-dev
These repositories are copied into a local directory whose name matches the name of the downloaded repository. i.e., the above example, creates an ns-3-dev directory and populates it with a full history of the ns-3-dev source code repository and the content of the tip version of the repository.

If, one week later, you want to update this copy of the source code to match the version stored in the main repository, you can run the pull and update commands:

[mathieu@mathieu ns-3]$ hg pull http://code.nsnam.org/ns-3-dev
pulling from http://code.nsnam.org/ns-3-dev
[...]
[mathieu@mathieu ns-3]$ hg update
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
pull downloads all the changes stored in the main repository which are not present in your local copy. pull does not apply these changes to your local copy. It merely stores information on the changes. update applies all these changes to your local copy. If you have made changes to your local copy, you have to merge rather than update:
[mathieu@mathieu ns-3]$ hg merge
abort: there is nothing to merge, just use 'hg update'
Merge will try to perform an automatic merge but if any changes made on your local copy conflict with those made on the remote repository, it will ask you for input to complete the merge. More information on merging is present on the Merge Tutorial webpage.

Looking at the history

Your local copy of the main repository contains a complete copy of the history of the project:

[mathieu@mathieu ns-3]$ hg log
changeset:   2:5ec44cc50c2c
tag:         tip
user:        Mathieu Lacage 
date:        Mon Aug 21 15:18:40 2006 +0200
summary:     AUTHORS empty file

changeset:   1:2ad5a77a8f05
tag:         tip
user:        Mathieu Lacage 
date:        Mon Aug 21 14:54:14 2006 +0200
summary:     empty README test

changeset:   0:4b56de7ae6e7
user:        Mathieu Lacage 
date:        Mon Aug 21 14:53:50 2006 +0200
summary:     empty README test
You can also request file-specific log history:
[mathieu@mathieu ns-3]$ hg log AUTHORS
changeset:   2:5ec44cc50c2c
tag:         tip
user:        Mathieu Lacage 
date:        Mon Aug 21 15:18:40 2006 +0200
summary:     AUTHORS empty file

Checking in local modifications

If you make changes to your local copy of the source code, you should probably record them in your local database. Before doing so, you should verify what changes you have made with the status and diff commands:

[mathieu@mathieu ns-3]$ hg status
M AUTHORS
M README
[mathieu@mathieu ns-3]$ hg diff AUTHORS
diff -r 5ec44cc50c2c AUTHORS
--- a/AUTHORS   Mon Aug 21 15:18:40 2006 +0200
+++ b/AUTHORS   Mon Aug 21 15:21:10 2006 +0200
@@ -0,0 +1,1 @@
+Bilbo The Hobbit
[mathieu@mathieu ns-3]$
status tells you which files have changed while diff tells you how each file was changed.

Once you are sure about your changes, you can commit them:

[mathieu@mathieu ns-3]$ hg ci -m "This is an important bugfix for Bilbo The Hobbit" AUTHORS README
[mathieu@mathieu ns-3]$ hg log
changeset:   3:bb3d6a584b09
tag:         tip
user:        Mathieu Lacage 
date:        Mon Aug 21 15:22:28 2006 +0200
summary:     This is an important bugfix for Bilbo The Hobbit
[...]

Pushing changes to the main repository

If you have an account to the master ns-3 source code repository, you can also push your local changes to this master repository:

[mathieu@mathieu ns-3]$ hg push ssh://code@code.nsnam.org/repos/ns-3-dev
pushing to ssh://code@code.nsnam.org/repos/ns-3-dev
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 2 changesets with 3 changes to 2 files
[mathieu@mathieu ns-3]$