Mercurial HOWTO

This will is a guide to help you to install mercurial on your system, and get it configured. This will also cover how to connect to Mercurial project to work on the available source.

Installation

On a Debian based system(this includes ubuntu), just type the following command:

 apt-get install mercurial 

On a RedHat based system(fedora, RHEL), use the following command:

 yum install mercurial

After you have done one of the above command, its a good idea to make sure everything went ok. Lets make sure that mercurial was installed by trying to run 'hg'.

 hg help 

If this prints out the help screen about possible commands and options, then you are on the right track. However, if you see the following, you should go back to the top and figure out why the package was unable to be installed.

 bash: hg: command not found 

Making a Clone

Clones are great, Star Wars had a whole episode about a war with them. But unfortunately, this isn't that kind of clone.

So just in case you are new to this whole repository thing, here is an explanation:

A repository is simply a collection of source code and other files that are part of the project you will be working on. This also includes a record or log of the changes and edits of the project.

Now that you know this, lets go over making a clone(or a copy of the remote repository on your system). This is fairly simple and you will only need the address to the remote mercurial repository to do this. Here is an example:

 hg clone Http://hg.globalshellz.org/example/repo 

This will ask you what directory you wish to store the clone in. You can put anything you want, but try to keep it specific to the project you will working on, so that you know what it is later. For this example, I will simply refer to this folder as 'example'. Also, its worth noting that mercurial will remember the address of the repository you are pulling from, and this will make it even more convenient later.

Make sure that the new clone is there by entering the directory and checking the listing:

 cd ./example && ls -al 

If you see any errors at this point, or the directory is empty back up and try again.

Mercurial History

No, I am not gonna explain why and where mercurial came from, if you wanna know that go look it up yourself.

This is talk about the log history of a project that you may be working on.

This command will print the log:

 hg log

This will print out the history of the repository. Each changeset or change to the project will print out four basic sections.

Changeset: This basically an identifier or revision even. This helps to distinguish between each change in the project, much like your age changes each year, and distinguishes you this year, from last year. The format for this is much simpler than it looks. First is a decimal number, then a colon, then a hex number. The first decimal number is an identifier that is only relative to this clone. Another clone of the exact same repository can have the same decimal numbers, but they may actually refer to changesets that vary from one another. The second number(the hex) is unique to the repository as a whole, and will match the same changes on any clone of the same repository

User: This refers to the person who created the changeset, usually an e-mail address, but can be any format.

Date: Duh. This is the date the changeset was created, not the current date always.

Summary: Something the person who created the changeset entered to help describe what this change did.

Still with me so far? Not that bad really.

You can also use '-r' with log, to get revision specific information. This will take either the decimal number, or the hex number. You can use it more than once in a single command to get more than just one changeset or revision. You can also use a colon(like this -r 3:5) to show just those revisions including and between the decimal numbers.

There are many more options you can use with the log command, I suggest reading up on the help section, or the man page.

Creating a User

I think the best way to do this is to simply create ~/.hgrc file. In this file you can set the username entry, and this will be read when you commit a changeset.

[ui]
username = digitalirony

You can also use the -u option followed by a username:

 hg commit -u digitalirony 

The -u option will override your .hgrc entries.

Creating Changesets

A lot of people like to work and make changes in a second clone on their local file system. This is easy to make, and can help you distinguish between particular changesets you may be working on. In case you did get the underlying information here, this means that with each clone, or changeset you are working on, you should try and work on a single specific task, instead of trying to 'fix' the whole project in one go. This helps with organization, and helps other coders to understand whats going on with the project. Remember KISS(Keep it simple stupid).

Example:

 hg clone example change1-example 

Then change directory to the new change1-example, and work away to plug that bug! Once you are done its time to package this all up and submit the new changeset back to the remote repository. This is called a commit. Before we do this, You will want to check the section on how to setup a username so you can get credit(or yelled at) for your changes.

Once you have an understanding of how usernames work you can commit your changeset:

 hg commit 

This will start an editor to allow you to enter a description of your changes. Remember that the log will only print the first line of this description, so make sure to keep it simple and informative. Once you are done save the file before exiting. If you wish to abort your commit, simply exit without saving.

Lets check our commit:

 hg tip -vp 

This should output information nearly identical to the 'log' command, but only information relative to your latest commit.

As of now though, this commit is only stored locally in our change1-example local repository. I suggest checking over this and making sure the change works, and everything is in order before moving ahead.

The 'hg pull' command is the way you will merge your new commit with an existing repository. I like to use the 'hg incoming' command to check the changes and test that this is indeed what I want.

To do this, you will want to make sure you change to the current working directory of your first clone(some people like to make a third clone for this so they can leave a clean copy of the code locally, but I don't, call me lazy).

Once we are in the original working directory of 'example' we will issue the following command:

 hg incoming ../change1-example 

Again this will look similar to your 'log' command, just make sure its what you want then move forward.

To pull the changes in we use the 'pull' command:

 hg pull ../change1-example 

Use 'tip' again to check and make sure that everything is again in order.

 hg tip -vp

Note: this does not actually change any of the files in our working directory, it will simply 'note' the changes to be made in the repository.

Now one last step to actually make the changes to the files in our working directory from the repository:

 hg update tip 

You can combine the pull and update into one command if you with the -u option to the 'pull' command:

 hg pull ../change1-example -u

Ok, so this is all good and fine for working with mercurial locally, but you will eventually want to push your changes to the remote repository. This generally works the same as before with the 'incoming' and 'pull' commands, but slightly different.

 hg outgoing Http://hg.globalshellz.org/example/repo

The above command does the same thing as incoming but from, as you guess the outgoing perspective.

 hg push Http://hg.globalshellz.org/example/repo

Please note that you can not use -u with the push command, as generally it is up to those in control of the remote repository weather or not they would like to update the changeset in their working directory.