The 5-Minute Guide to Contributing With Mercurial

Welcome. This will be fast. This guide describes how you can contribute to software projects here using the Mercurial version-control system.

Darcs is a distributed VCS, so you do not need to be granted commit access in advance. You can hack, commit, and then send in your patches without permission from anyone.

Step 1: Get Mercurial

If you are using Debian, you can simply

apt-get install mercurial

. Otherwise, you can download Mercurial source or binaries for other Linux, Unix, Windows, and Mac operating systems from the Mercurial homepage at http://www.selenic.com/mercurial/. Instructions will vary depending on your operating system, and are posted on the Mercurial site.

Step 2: Configure Mercurial

On Unix, you'll edit the file ~/.hgrc. On Windows, you'll edit a similar file, but it may be located elsewhere. You'll add lines like this to it:

[ui]
username = My Name <myemail@example.com>

[email]
from = myemail@example.com
method = /usr/sbin/sendmail

If you aren't on Unix, or if you're not going to use sendmail to send out mail, set up the email section like this instead of the above example:

[email]
from = myemail@example.com
method = smtp

[smtp]
host = somehost.example.com
port = 25
tls = False
username = myuser
password = mypass

You can omit all settings in the smtp section except the host if they are not relevant to you.

If you are using a recent version of Mercurial, you will also need to add the following, to enable the
email extension:

[extensions]
patchbomb =

(sic)

Step 3: Check Out The Source

You'll run:

hg clone http://hg.complete.org/projectname
cd projectname

Replace "projectname" with the Mercurial name for your project. These names will be given on the project page on this site. One example would be:

hg clone http://hg.complete.org/listlike
cd listlike

The [/ Software.Complete.Org project list] and Hg.Complete.Org project list may be of use to you.

Step 4: Hack

Make your changes. After modifying a file, run:

hg commit

An editor will be opened for you to describe what you changed. By convention, the first line will be a 1-line summary, and the rest of the lines will describe your change in more detail.

If you add a new file, you'll need to tell Mercurial about it before you can use

commit

:

hg add filename

To rename a file, don't just use a command such as

mv

. Instead, use:

hg mv oldfilename newfilename

And finally, if you delete a file, use

hg rm filename

to tell Mercurial about it.

Step 5: Submit

Once you're done with your feature, submit it to the software manager(s) for consideration. Simply run:

hg email -go

All version-control history, including your name, commit messages, individual changes, etc. will be e-mailed. You will be prompted for the address to email to.

This, of course, requires a working email setup on your system. You can use

hg bundle filename

to write a patch bundle to a separate file, which you can then send in manually if

hg email

doesn't work for you.

Step 6: Update

If you follow a project for more than a few hours, you'll want to periodically integrate changes from the upstream repository into your local copy.

hg pull -u

will do this.

If you need to merge changes, Mercurial will tell you and you can use

hg merge

to do so.

Advanced Tips & Tricks

You may also be interested in some of these.

Learning About Commands

hg --help

will show you a list of commands.

hg command --help

will show you information about each individual command.

Looking At Changes

You can, of course, use the project timeline here on the website. But for more detailed information, try a command such as:

hg log -v | less

For More Information

Go to the Mercurial homepage. There is also a very helpful Wiki and online community on IRC.