• Introduction
• Basic tasks
• Clone the JUG Events repository
• Commit your changes in your local repository
• Get updates from the parent repository
• Sharing your code
• Use a "branch-per-feature" strategy

Introduction

Recently the JUG Events project switched its code repository from Subversion to Mercurial. Here you'll find some guidelines and good practices for using Mercurial in developing JUG Events.

This page is not intended as a reference guide for Mercurial, as the Web is already full of documentation:

• A tutorial at Selenic
• Mercurial: The Definitive Guide. The O'Reilly book.
• A quick reference card
• Mercurial Best Practices. This page and my knowledge of Mercurial are largely based on that document. Many thanks to the author, Fabrizio Giudici.

Basic tasks

Clone the JUG Events repository

hg clone https://jugevents.googlecode.com/hg/ jugevents
requesting all changes
adding changesets
adding manifests
adding file changes
added 884 changesets with 5069 changes to 2070 files (+2 heads)
updating working directory
414 files updated, 0 files merged, 0 files removed, 0 files unresolved

Cloning is almost equivalent to checkout, in Subversion terms. But after cloning you'll have a complete repository in you local directory. All your operations (except push) will be applied to your local repository.

You could even clone your local repository, for example for some experiments in total isolation:

hg clone jugevents jugevents-2
updating working directory
414 files updated, 0 files merged, 0 files removed, 0 files unresolved

Note this last operation can be executed even without network availability.

Commit your changes in your local repository

Check the status of your working directory:

$ hg status
M README

You modified the README file. Then commit it to your local repository (of course you already built the project and passed all tests ;) ):

$ hg commit README -m "A small change"

Again, this operation can be executed totally offline.

Get updates from the parent repository

When modifications from other developers appear in the JUG Events repository you would like to acquire them to your local repository:

$ hg pull
pulling from https://jugevents.googlecode.com/hg/
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
(run 'hg update' to get a working copy)

Notice the last line: the pull command updated your local repository, but not your working copy. After the pull you need to use the update command:

$ hg update
1 files updated, 0 files merged, 0 files removed, 0 files unresolved

Now You are ready to work on the new code.

Sharing your code

When you'll be ready to share your code with the other developers, you'll push it to the parent repository:

hg push
pushing to https://jugevents.googlecode.com/hg/
searching for changes
http authorization required
realm: Google Code Mercurial Repository
user: lucio.benfante
password: 
Success.

Use a "branch-per-feature" strategy

For small and fast changes a direct "commit and push" activity is ok. But usually the solution of an issue is longer and complex, often we need to work on different issues at the same time, and we would like to have a more controlled environment, one for each issue.

So, when we'll start working on an issue, we'll create a dedicated branch inside our local repository (we'll use the issue 53 in this example):

$ hg branch fix-issue-53
marked working directory as branch fix-issue-53

You working directory is marked as new branch, but the branch wasn't created. You need to commit it:

$ hg commit -m "Created branch fix-issue-53."

Now you can see it in the list of all open branches:

$ hg branches
fix-issue-53                 885:c4b21d1aa132
ingevents                    868:1790c563a490
jugevents-1.0                741:6dd46101dc15
default                      884:2aa92ab8a185 (inactive)

Or you can ask what is your current branch:

$ hg branch
fix-issue-53

The update command will update your working directory from a branch to another. For example, for start working on the jugevents-1.0 branch:

$ hg update -c jugevents-1.0
132 files updated, 0 files merged, 83 files removed, 0 files unresolved

So, go back to your issue branch:

$ hg update -c fix-issue-53
197 files updated, 0 files merged, 18 files removed, 0 files unresolved

...and fix that issue!

When you'll complete your job (and of course all test passed), you will close the issue branch, and merge it to the default branch:

$ hg commit --close-branch -m "Closing branch. Fixes issue 53."
$ hg branches
ingevents                    868:1790c563a490
jugevents-1.0                741:6dd46101dc15
default                      884:2aa92ab8a185 (inactive)
$ hg branch
fix-issue-53
$ hg update -C default
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ hg merge fix-issue-53
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
$ hg commit -m "Merged fix-issue-53 branch."

Notice the content of comment we used when we closed the branch: "Fixes  issue 53 .". That comment, when it will be pushed to the parent GoogleCode repository, it will automatically close the issue, adding a comment with references to that revision.

Look at the issue after the push: