codebeamer»Wiki»User's Guide»codebeamer ALM: Application Lifecycle Management»Version Control: Subversion (SVN), Git, Mercurial»Using Managed Subversion,~ & Mercurial RepositoriesUsing Mercurial with CodeBeamer #25684/HEAD / v810
Using Mercurial with CodeBeamer
Table of Contents
Mercurial is a fast, lightweight Source Control Management system designed for efficient handling of very large distributed projects. It is also called hg for short.
CodeBeamer has out-of-the-box support for mercurial repository access, for both 'external' or 'managed' repository configurations.
Installing codeBeamer with Mercurial
In the codeBeamer Windows versions, codeBeamer is shipped with Mercurial and no installation is necessary unless access via Apache is required.
At this point codeBeamer and Mercurial should be working together and you should be able to create codeBeamer projects with a managed Mercurial repository. The whole process takes about 10-15 minutes.There is no managed ACL (Access Control List) support for directories in codeBeamer for Mercurial, so authenticated users can access any content under a repository. If necessary, one can maintain ACL by the built-in ACL extension of Mercurial.
The Mercurial server component in codeBeamer is called hgserve (supports only cloning) and it is started and stopped automatically by codeBeamer.
Mercurial Client on Windows
On a Windows platform additional setup is necessary to use Mercurial over SSH.
First generate an SSH keypair as described in Setting Up SSH Authentication for Git and Mercurial
Modify the Mercurial setup to use your ssh client command in global configuration (mercurial.ini under your home):
[ui] ... ssh = "C:\Program Files\TortoiseHg\TortoisePlink.exe" -ssh -2 -i "C:\Documents and Settings\adam.berkes\key.ppk" ...There are certain versions of putty which fail to communicate this way, so we advise using the plink program from TortoiseHg. If you do this don't forget to modify Mercurial.ini in the installation directory of TortoiseHg (by default C:\Program Files\TortoiseHg\Mercurial.ini) as well.
Using Mercurial in the Eclipse IDE with the MercurialEclipse plugin
MercurialEclipse is the most commonly used IDE integration plugin. Using it for development with codeBeamer Managed Mercurial Repositories is easy. For download information visit MercurialEclipse download.
URLs of Managed Mercurial RepositoriesMercurial can be configured three ways in connection with codeBeamer:
If hg serve is turned off in codeBeamer's configuration (i.e. general.xml, see Sharing Managed Repositories) the Apache server can be setup according to Configuring Apache for Mercurial. In this case only members with SCM_VIEW permission can read (clone/pull) project repository and only members with SCM_COMMIT permission can write into it (push). CodeBeamer maintains repository access configuration information however additional restrictions can be applied in Apache configuration if necessary. For example:
If Apache is not configured but hg serve is started by the codeBeamer server and OpenSSH is installed on the server then all users have public read access to the repository (default port: 8000) but only users with SCM_COMMIT permission have write access to it (e.g. push). System Administrators can also run remote hg commands. OpenSSH is officially supported only on Linux platforms however it can be set up using Cygwin on Windows. Examples:
Repository read access example: http://localhost:8000/myrepositoryname Repository read-write access example: https://javaforge.com/hg/hgeclipse Repository read-write access example: ssh://firstname.lastname@example.org/hgeclipse
The above scenarios can be mixed if both Apache and OpenSSH are configured. Authors can send their changes through SSH or HTTPS, while HTTP access is restricted to only certain members.
How to Use Mercurial with codeBeamer
Setting Up SSH User Authentication (Step 1)Before you can work in codeBeamer with Managed Mercurial Repository it needs to know who you are and you need an OpenSSH key (keypair). This consists of a private and a public key, and you must provide your public key to codeBeamer to allow security control of mercurial communication over ssh. Keep your private key in a safe place; this will probably be the place where it was created.
To generate the keys please follow the steps described in Setting Up SSH Authentication for Git and Mercurial.
Creating and Joining Projects with Managed Mercurial Repositories (Step 2)Project repositories subtend a base URL which is set up by the codeBeamer System Administrator. This access URL must be properly configured first, before your managed repository is configured. See Administrator's Guide or your codeBeamer System Administrator for more help.
Follow the steps described in Creating Managed Repositories.
Cloning Repositories, Committing and Pushing Changes (Step 3)
We now need to get our copy of the source code so we can work on it.
On your desktop machine open a terminal window and enter the following commands:
In Apache (scenario 1):
cd your.local.repository.dir hg clone http://email@example.com/hg/repository.name
Note: you will be asked for your codeBeamer password for authentication.
In public access/ssh (scenario 2):
cd your.local.repository.dir hg clone http://codebeamer.host:8000/repository.nameor
cd your.local.repository.dir hg clone ssh://firstname.lastname@example.org/repository.name
Edit the files, fix bugs, etc. Now commit your changes to the repository. In the following instructions only the apache (http access) scenario will be used - others will differ only in the url used in the commands (see above).
On your desktop machine open a terminal window and enter the following commands: If you added/removed any local file:
cd your.local.repository.dir hg addremove hg commit -m "Commit message" -u "my.codebeamer.username"otherwise
cd your.local.repository.dir hg commit -m "Commit message" -u "my.codebeamer.username"This will commit changes locally to your repository. Now send your changes to codeBeamer:
hg push http://email@example.com/hg/repository.nameNote: if you are using a 1-to-1 repository clone, simply using hg push without parameters works.
To use shorter commands, the author's identity can be defined by editing the hgrc file of the repository:
cd your.local.repository.dir/.hg nano hgrcAlter the file's [ui] section to be like:
... [[ui] username = my.codebeamer.username <firstname.lastname@example.org> ...This will set your identity and commits can be sent by 'hg commit -m "..."' More than 1 commit can be sent to codeBeamer with a single push operation. Simply make your changes and repeat the steps above without the push. When you want to share your work execute a 'hg pull -u' to get latest revisions and update (or merge) your local clone, and then execute 'hg push'. That will send all your changes at once.
Associating Issues with Commits (Step 4)
To associate an issue with a commit first create an issue within a codeBeamer tracker. Keep in mind the id of the generated issue, and start to work the source code implement or fix in connection with it. When done open a terminal window and enter the following commands (replace "1234" with the ID of the issue you want to associate your commit with):
cd your.local.repository.dir hg commit -m "#1234 Commit message" -u "my.codebeamer.username"Use the issue ID you've created: this will commit changes locally to your repository. Now send your changes to codeBeamer (replace "<codebeamer.host>" with your actual server name or server IP address):
hg push http://cb.username@<codebeamer.host>/hg/repository.nameLogin to codeBeamer and:
You can now see your commit(s) at the top of the history, and the issue #1234 (check the link on the rightmost cell) is associated with your change. You can check the "back" association by clicking on this issue link, and see your change info on SCM Commits tab at the bottom of the issue.
For more information on associating issues with commits, please see Tracing Source Code Changes to Requirements, Task and Bugs
Converting an Existing Mercurial Repository to a Managed One
An unmanaged (external) repository can be converted to a managed one using bundles as described in Creating Managed Repositories.
Useful Mercurial Commands
Creating BundlesYou can create Mercurial bundles using
hg bundle. Navigate to a repository directory and issue the following command:
hg bundle -a dump.bundle
dump.bundleis the name of the dump file created. For more options see the Mercurial help (
hg help bundle).
codebeamer Knowledge Base
Services by Intland Software