Using Mercurial

Mercurial is a distributed version control system (DVCS). The differences to a “traditional” centralized VCS (like CVS or Subversion) include:

• Users get a self-contained repository that they can commit changes to, even when being offline.
• Changes can be pushed back to the parent repository or even to other repositories.

Installation instructions are provided for Windows, Mac OS X, and Linux

pyLoads Mercurial repository is available from this URL:

http://bitbucket.org/spoob/pyload/

This repository was converted from the SVN repository right after the release of pyLoad 0.0.2.2 .

To create a copy of that repository, simply do

hg clone http://bitbucket.org/spoob/pyload/ pyload

if you have a bitbucket account you can copy the repository with

hg clone https://USERNAME@bitbucket.org/spoob/pyload/ pyload

Where USERNAME obviously has to be replaced by your bitbucket username. This will be handy if you would like to contribute code to pyLoad.

Where the last “pyload” is just a directory name for the local copy (and can be changed at will). This will give you a fully working local repository that you can commit changes to. If you want to push your local changes to the main repository you have to have an bitbucket account and you should have checked out the repository with the user-name in the URL to make it easier for you.

Note: You can also browse the repository online on the bitbucket project page of pyLoad.

Being able to push changes back to the repository again requires an account on bitbucket. If you cloned the repository with your bitbucket user-name you can simply do

hg push

For starters, the Mercurial Wiki has a page on Working Practices that we may want to adopt.

Pull changes to a local “incoming” repository but don't work on that repository. Cloning that repository locally is a cheap operation and allows you to easily create multiple copies if necessary, e.g. when working on different features in parallel.

Push directly from your working repositories, then sync back by pulling the changes back down via your incoming repository. Merging

If you attempt to push changes to the main repository and receive the error:

pushing to https://USERNAME@bitbucket.org/spoob/pyload/
searching for changes
abort: push creates new remote heads!
(did you forget to merge? use push -f to force)

Simply pull from the main repository with

hg pull -u

Then look at the head revision numbers with

hg heads

Now merge the heads with

hg merge REVNR

Where REVNR is the Revision Number of your head

Then commit the changes, and push back to the main repository

hg commit -m "merged"
hg push

Also very important: Don't try to push newly added files while you still have uncommited changes lying around (or you will end up with the above). In that case, it may make sense to make a fresh clone (fast + cheap if you use an “incoming” repository!), add the new files there, then push from the fresh copy.

When committing a change, the username associated with that change will be your local username (login, etc.) - not the name of your account on bitbucket.

For a consistent username, add your preferred username to your local ~/.hgrc file:

[ui]
username = John Doe <john@example.com>

The email address has to be the same email that you entered to your bitbucket account, if you want wour changeset linked to your bitbucket user account on the web interface.

(More tips and tricks to be added here)

To undo changes you made, use one of the following, depending on circumstances:

• hg revert

  to revert changes made before a commit. This will also undo hg add and hg remove.

• hg rollback

  to revert changes that have been commited to the local repository but not been pushed to another repository yet. You can only rollback the last hg command.

• hg backout

  to revert changes after they have been commited and pushed.

Note that hg backout will actually add a new change to the current branch that reverts your previous change. I.e. your change will not be removed from the repository. Unless you've accidentally committed something super-secret, that's usually fine. Mistakes happen - no need to sweat it.

• The book Distributed revision control with Mercurial aka “the hg book” is probably the best available documentation for Mercurial. It is available for download under the Open Publication License.
• The Mercurial Wiki is a good place to search for more information.
• Inside a distributed version control system by Jim Hague provides a good introduction into the workings of DVCS in general and Mercurial in particular.
• Mercurial lets you choose between a variety of workflows. Learning Mercurial in Workflows discusses the most commonly used ones.
• Those already familiar with a non-distributed VCS may find Mercurial for SVN Users useful.

• Tags and Branches