Using a Mercurial Code Repository
Mercurial is a Distributed Concurrent Versions System, rather similar to the Concurrent Versions System that is used for Radiance. The idea is to have central repository that allows different developers to work on the same code base.
Mercurial is fairly easy to use. All Mercurial commands start with hg, followed by the action and options.
Mercurial is well-documented. Here are a couple of guides that you might find of interest. Their order is from Basic to Complex:
Cloning a Repo
To start contributing, first create a local copy of the repo on your machine. We are assuming that you want the csh2perl directory under ~/software/, but it can reside anywhere you like.
$ cd ~/software $ hg clone https://www.jaloxa.eu/devel/hg/csh2perl warning: www.jaloxa.eu certificate with fingerprint cf:c1:...:6d not verified (check hostfingerprints or web.cacerts config setting) destination directory: csh2perl requesting all changes adding changesets adding manifests adding file changes added 18 changesets with 140 changes to 126 files updating to branch default 124 files updated, 0 files merged, 0 files removed, 0 files unresolved
This has created the directory csh2perl under your ~/software/ directory. We'll talk about the fingerprint warning later. You may safely ignore it for now.
$ cd csh2perl/ total 19836 drwxrwxr-x. 8 axel axel 4096 Jun 26 22:59 . drwxrwxrwt. 84 axel axel 20254720 Jun 26 22:59 .. drwxrwxr-x. 2 axel axel 4096 Jun 26 22:58 bin drwxrwxr-x. 4 axel axel 4096 Jun 26 23:00 .hg -rw-rw-r--. 1 axel axel 83 Jun 26 22:58 .hgignore drwxrwxr-x. 3 axel axel 4096 Jun 26 22:58 man drwxrwxr-x. 2 axel axel 4096 Jun 26 22:58 orig drwxrwxr-x. 2 axel axel 4096 Jun 26 22:58 status drwxrwxr-x. 3 axel axel 4096 Jun 26 22:58 tests
You can now browse the code, try it out and tinker with it.
Status of the Repository
The hg status command lists all files in your local repo that are not synchronised. The following status codes are used:
|!||missing (deleted by non-hg command, but still tracked)|
It's a good idea to run hg status after each edit to your csh2perl repo. The example below starts off with a clean repo, after which a file is edited. The new status then indiates this changed file.
$ hg status $ vim bin/myfile.pl $ hg status M bin/myfile.pl
Committing Your Changes
If you have edited any files, you'll need to tell Mercurial to check them in. This is called 'committing the changes'. During the commit, you will be prompted to give a brief summary of the changes that you've made. A one-liner will do, but try to be concise.
$ hg status M bin/myfile.pl $ hg commit
The editor that Mercurial will fire off for you is defined by the $EDITOR environmental variable. It defaults to vi if $EDITOR is not set. This can be overwritten in your ~/.hgrc file. More to this later.
If you don't want to involve any editor, you can specify the commit message on the command line:
$ hg commit -m "Fixed bug with call to pvalue"
You are encouraged to make relatively small changes, committing frequently as you go along. If you got carried away with your editing, and there is a whole bunch of files waiting to be committed, you may tell Mercurial to only process specific files:
$ hg commit bin/myfile.pl
$ hg commit -I bin/myfile.pl
Adding New Files
The last section explained what you need to do if you have edited existing files. If you add new files, e.g. a new Perl script under bin, or a new man page under man/man1/, you need to tell Mercurial, too.
$ hg status $ touch bin/testscript.pl $ hg status ? bin/testscript.pl $ hg add bin/testscript.pl
Pushing Your Changes
After a commit, your local repo is synced with the files that you have edited locally, but the changes still need to be propagated to the central repo on the server. This is done with hg's push action.
Before we go there, we need to briefly talk about the hg resource file, ~/.hgrc. This is where important setting, such as the Mercurial server and authentication are stored. The csh2perl repo on JALOXA is configured to work securely over https. No authentication is required for pulls. However, if you want to push, you need to authenticate yourself.
Copy and paste the following to a new file '.hgrc' in your home directory:
$ cat ~/.hgrc # This is a Mercurial configuration file. [ui] username = Your Name
#editor = vim [paths] #default = https://username:firstname.lastname@example.org/devel/hg/csh2perl csh2perl = https://username:email@example.com/devel/hg/csh2perl [hostfingerprints] www.jaloxa.eu = cf:c1:0f:0f:a6:ed:8d:28:c8:aa:ca:8c:40:67:54:d7:4b:7f:68:6d
Make sure the username and password are valid. Try to get this right. The server will lock you out after too many failed attempts. You should now be able to run
$ hg commit csh2perl
without any complaints or warnings.
There are other changes that you can make to your .hgrc file:
- Un-comment this line and change the value to your favourite editor
- If you un-comment this line (make sure to change username and password!), you can omit the 'csh2perl' part from hg commit.
- The issuing authority of JALOXA's SSL certificate might not be known to your Mercurial. This setting turns off the warning that we got when we first cloned the repo from the server.
Pulling the Latest Revision
Before you do any editing, it's always a good idea to start off with the very latest revision. This is done by 'pulling' from the server.
$ hg pull
Your local repo is now in sync with the main one, but the actual files are not updated yet. This needs one extra command:
$ hg update
You can now start editing. Remember to frequently commit the changes, and to push them to the server.