Information about Mercurial and RhodeCode

Mercurial

If you've never used revision control systems before, you may want to look at the Mercurial Tutorial. There are many other tutorials on the web as well (the last link is part of the Definitive Guide, which is a great reference).

If you're on windows, the recommended mercurial GUI tool is TortoiseHg; If you're comfortable with the command line, you can download clients for most platforms on the Mercurial Website.

If you're already familiar with Subversion, Mercurial should be very easy to learn: the most important difference is that in Mercurial your local copy contains a complete repository (including all its history), and there's a separate command for synchronizing with the remote repository. This means you can commit stuff locally without network access (e.g., while working on a plane), and then "push" multiple commits at once to the main repository (where they will be seen by everyone else). A brief Subverson/Hg comparison for the command line can be found here.

RhodeCode

RhodeCode is the web-based respository management system we use. It should be fairly self-explanatory. Some documentation can be found here. If you have trouble, please ask on the course help forum.

Some Frequently Asked Questions

I committed my changes. Why don't they appear on the repository server?

In brief: you need to push after you commit to send your changes to the server. In more detail: this is one of the major differences between CVS/Subversion/etc. and distributed version control systems such as Mercurial. In Merurial, every copy of the repository (including the one you made when you cloned the repository) is a complete and independent repository in itself, including all the version history. When you "commit" your changes, you are performing a local operation: it only affects your local copy of the repository. This means you can commit multiple changes, view history and roll back to previous revisions all without network access. To propagate changes to a remote repository repository (by default the one you cloned from), you need to perform a push command.

I tried to push changes but Mercurial complained about “multiple heads”

In brief: if you haven't purposefully created a new branch, you need to first pull changes from the remote repository, merge with your latest changes and then push again. In more detail: think of the repository as a DAG (Directed, Acyclic Graph): each node is a version, and a node i is a parent of node j if j was created by making changes to version i (e.g., you updated to version i, edited a file, committed the change and the resulting version is j). A "head" is a leaf in the DAG. Multiple heads occur if two different edits were both based on the same version. This usually happens when two people are working on the same version independently (remember that each repository copy is independent) and commit their changes. The first one to push their changes to the server will not create a new head (since the server's version is the one they started from). The second person to push the changes would create a new head. The recommended workflow in this case is to pull from the server instead of push (in which case your local repository will now have two heads. The next step is to merge in your local repository: a merge combines changes from two parent versions and creates a single child. If there are no conflicts, the merge can be done automatically. Otherwise, you need to go over it manually to resolve conflicting edits. After merging and committing the result, you should be able to push the results without creating new heads.

Why shouldn't compiled code be in the repository?

Since every clone contains the entire repository history, if you committed compiled code it would add up pretty quickly (it would also make pushes and pulls much slower, since the diff for binary files isn't very good).