{{ :how_to:mercurial_logo.png |Mercurial Logo}}

Mercurial is a cross-platform, distributed source management tool for software developers.[1]  There's lots of very good tutorials available on using mercurial, some of which I've linked at the bottom of this page.  This is written from a linux user's perspective. (sorry!)  I'll update for other OS's soon.



====== Common Tasks ======

===== Setting Your Username =====

Create a file ~/.hgrc and add the following, replacing Billy Bob's details with your own:

<code>
[ui]
username = Billy Bob <billy@bob.com>
</code>

===== Cloning a Repository =====

Have a look at the [[http://www.compsoc.nuigalway.ie/~webdev/cgi-bin/index.cgi/hg | Sample Repository]] .

Change directory into where you want your working repository to live.  For example, I've created a ~/mercurial directory.

<cli>
$mkdir ~/mercurial
$cd ~/mercurial
</cli>

Now specify the location of the repository you wish to clone and the name you want to give it.

<cli>
$hg clone http://www.compsoc.nuigalway.ie/~webdev/cgi-bin/index.cgi/hg test-repository
</cli>

Typical output:
<file>
bin/index.cgi/hg test-repository
requesting all changes
adding changesets
adding manifests
adding file changes
added 3 changesets with 3 changes to 1 files
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
</file>

<cli>$ls ~/mercurial</cli> 

You should see a new directory called **test-repository**.

===== Checking The Status =====

Add your name to the file called **test** .  Create a new file.  Call it your initials.

Now have a look at your project's current status:

<cli>
$cd ~/mercurial/test-repository
$hg status
</cli>

Typical Output:
<file>
M test
? ajr
</file>

===== Adding Files to the Project =====

If you create a new file in the repository and do 
<cli>
$cd ~/mercurial/test-repository
$hg Status
</cli> a question mark will be beside the name of the new file.  To add it:

<cli>
$hg add <filename>
</cli>

===== Commiting Changes =====

<cli>
$cd ~/mercurial/test-repository
$hg commit
</cli>

You'll be prompted to give a short description of the changes.


===== Viewing Previous Changes =====

<cli>
$cd ~/mercurial/test-repository
$hg log
</cli>

Typical Output:
<code>
changeset:   3:fa8621938ff9
tag:         tip
user:        andrewjregan <andrewjregancompsoc.nuigalway.ie>
date:        Tue Jun 17 09:17:48 2008 +0100
summary:     Added ajr

changeset:   2:820b24f246b3
user:        Andrew Regan <andrewjregancompsoc.nuigalway.ie>
date:        Tue Jun 17 01:41:54 2008 +0100
summary:     Cloned hg from the server to my local machine and modified test

changeset:   1:82f20c629df5
user:        Webdev <compsoc-webteamcompsoc.nuigalway.ie>
date:        Thu Jun 12 20:45:38 2008 +0100
summary:     Added my name to test.

changeset:   0:a2ca201ee468
user:        Webdev <compsoc-webteamcompsoc.nuigalway.ie>
date:        Thu Jun 12 20:17:19 2008 +0100
summary:     Created the repository and added the test file.
</code>

===== Push Changes To a Remote Repository =====

**Note:** Unless you have been given a password for this example you wont be able to push changes.

<cli>
$cd ~/mercurial/test-repository
$hg push http://compsoc.nuigalway.ie/~webdev/cgi-bin/index.cgi/hg
</cli>

You can also use other protocols.

====== Links ======

  - [[http://en.wikipedia.org/wiki/Mercurial_software|Mercurial on Wikipedia ]]
  - [[http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart|Quick Start Guide ]]