Mercurial Workflows and Cheatsheet

Installing Mercurial

Installing Mercurial is relatively straightforward...

Some repositories make use of the HgExternals plugin, which should be installed prior to use. (Installation on Unix-based systems may be done using setup.py in the distribution).

Cloning from an Existing Repository

If you wish to start work on an existing repository (such as one of the ones at http://dig.csail.mit.edu/hg/), simply call hg clone URL, where URL is the URL of the particular repository (e.g. http://dig.csail.mit.edu/hg/aintno). This will automatically create a new directory named after the last element in the path (e.g. aintno) and check out the most recent revision of the remote repository into that directory.

Once you have cloned the repository, the general workflow below should be sufficient for getting and pushing new updates to/from the remote repository.

General Mercurial Workflow

  1. hg pull - Pull the latest Mercurial updates from the server to the local repository
  2. hg update - Update the local repository to include the latest updates. NOTE: You may get messages about unresolved conflicts. In these cases, you will need to manually merge the conflicting files and then run hg resolve -m FILE to mark the file as resolved.
  3. hg externals - For some repositories (specifically the aintno repository), there is a dependency on external repositories. Updating these repositories may be done using the HgExternals plugin and using this command.
  4. Make any necessary changes to the code (preferably addressing one problem/feature at a time
  5. Write and run any necessary tests, and documentation, and make sure that any code or documentation will be correctly created.
  6. hg add FILE - Add any newly created files to the repository
  7. hg commit -m MESSAGE [-u USER] - Commit the changes to your local repository.
  8. hg push - Push all local changes to the remote (DIG) repository. NOTE: You may need to run hg pull and hg merge if remote changes have been pushed by someone else, so as to not create a new branch. Mercurial will warn you if this is the case.

Other Useful Mercurial Commands

Other Mercurial Tips

New Repositories

New Mercurial repositories may be created by any user with dig-admin rights on the CSAIL servers. Those who do may follow the instructions below. Otherwise contact Ian or Oshani and have them create the repository.

Although the CSAIL servers do have Mercurial installed, due to some versioning issues, it is not possible to create a remote repository easily on the CSAIL servers. The repository script will only work with Mercurial repositories made with version 0.92, while the command-line scripts are generally above version 1.0. Due to this, making new repositories is currently a little more involved than it should be, and instructions follow.

  1. cd to the DIG group directory (/afs/csail/group/dig/hg)
  2. mkdir the directory to contain the new Mercurial repository and cd into it.
  3. Run hg init
  4. Fix the ACL permissions to allow the www user write access to the directory by calling fs setacl . www write, fs setacl .hg www write and fs setacl .hg/store www write.
  5. Create a new file .hg/hgrc using the following template (filling in the appropriate blanks after the equals signs. Description, name, and contact are used to populate the columns on http://dig.csail.mit.edu/hg/)
    [web]
    allow_push = *
    push_ssl = false
    style = gitweb
    description =
    name =
    contact =
    
  6. Add a new line to ../hgweb.config under the [paths] section, reading name=/afs/csail/group/dig/hg/new-directory, replacing name and new-directory with the values chosen above when creating the directory and assigning a name in hgrc.
  7. Add a new line to ../.htaccess to add a new RewriteCond directive to ignore the newly created directory.

New Mercurial Committers

New Mercurial committers may be added by any user with dig-admin rights on the CSAIL servers. Those who do may follow the instructions below. Otherwise contact Ian or Oshani and have them create your user account.

  1. cd into /afs/csail/group/dig/hg
  2. Modify the .htpasswd file using htpasswd and the realm name "DIG Mercurial Repositories".