What is Mercurial?

Mercurial (hg) is a Source Code Management (SCM), a tool for software developers which supports collaborative development of software within a team, and the tracking of changes to software source code over time.

Mercurial is used by developers, and advanced users who need the very latest changes to the software (before releases occur). Software users generally do not need Mercurial; typically they will download official file releases made available by the project instead.

Developers should familiarize themselves with Mercurial by reading the Mercurial Documentation.

Modern SCM facilities

Here's a nice writeup of why you should consider using a Distributed Version Control System (DVCS), and a comparison of the major DVCSs: http://www.infoq.com/articles/dvcs-guide

Features

SourceForge.net provides the following features in its Mercurial offering:

All features of Mercurial 5.x are supported.

Developer (read/write) access is provided via ssh.

anonymous (read-only) access are provided via hgweb over HTTP ("http://").

Several Mercurial clients are supported, including: The official Mercurial client (MS Windows, Mac OS X, Linux, BSD). The Windows shell extention client, TortoiseHG (MS Windows).

Existing repositories may be imported via a normal Mercurial push (since Mercurial is a distributed SCM).

Repository access may be granted or revoked from a developer using the Project Admin interface.

Repository backups and mirroring may be performed using rsync or Mercurial clone.

Service usage is not restricted by quotas.

Multiple repositories are supported.

Management

To create a new repository:

Click on the "Add New..." link in the project menu bar

Click on Mercurial. Select a name for the label (this will determine the title of the link in the project navigation) Select a Url Path (this will affect the URL for your repository)



The above instructions may be repeated using a different label and path to create multiple repositories.

Once Mercurial has been enabled, you may wish to adjust permission grants for your users, if you need to disable one or more user's ability to make changes in the Mercurial repository.

The standard way to modify the contents of your repository is using a Mercurial client as detailed in Distributed revision control with Mercurial. Refer to the Getting Started section for how to make your first commit to your new repository.

Administrators may also manually manipulate their repository via the site interactive shell service.

Options

The following options are available in 2 places: under the "Admin - REPO_NAME" drop-down in the left sidebar of your repository web page (look for the blue text) or via the gear icon after pressing the lock icon (to unlock your top menu bar): Import Repo This menu entry helps you to import data into an empty repo (only on some SCMs). Viewable Files This menu entry lets you specify a space delimited list of filename extensions that should be viewable in the browser (ie., txt for plain-text files). Refresh Repository This menu entry can be used to force the repository's data to be refreshed in the code browser when there is a problem. This data is typically refreshed automatically. Permissions This menu entry lets you configure specific permissions. Fine-grained permissions controls are not supported (e.g. restrict access by specific paths within a repository), if that sort of access control is required, consider creating multiple repositories with different permissions. Rename This menu entry changes the name of your repo in the menus, but does not have a way to change the mount path that appears in the repository URLs. Delete Everything This menu entry will delete the repository on our servers, note that while this is normally very quick, but there is occasionally a delay in removal.

Developer Access (Read/Write)

We provide read/write access to Mercurial via ssh or https. ssh will provide better performance than https, and should be used whenever possible.

To access a Mercurial repository, configure your Mercurial client as follows (replace PROJECTNAME with the UNIX group name of the project, and the default REPOSITORY is 'code'):

ssh : // USERNAME @hg . code . sf . net / p / PROJECTNAME / REPOSITORY ( read / write )

If ssh does not work for you, you may use https instead, however, access will be slower:

https : // USERNAME @hg . code . sf . net / p / PROJECTNAME / REPOSITORY ( read / write )

Anonymous access (Read-only)

The read/write protocols detailed above can also be used for read-only access (just remove the "USERNAME@" portion). In addition, you may also use the http protocols with the same URLs.

For example:

http : // hg . code . sf . net / p / PROJECTNAME / REPOSITORY /

Authentication

The read-only access does not prompt for a password.

The read/write access uses your ssh password or ssh key to authorize your access. To perform write operations, your project administrator must have granted you write access to the repository.

Getting Started

Note: - For all examples below, "PROJECTNAME" represents a SourceForge.net project UNIX name and "USERNAME" represents your SourceForge.net user account.

Your project's Mercurial repository will be completely empty at the start, but since Mercurial allows you to clone a repository with no content, you can do a clone to get started:

$ hg clone ssh://USERNAME@hg.code.SF.net/p/PROJECTNAME/REPOSITORY PROJECTNAME-REPOSITORY

The first time you try connecting to the hg.code.sf.net host, you should see a message similar to the following:

The authenticity of host ' hg.code.sf.net (216.34.181.156) ' can ' t be established. RSA key fingerprint is 86 : 7 b : 1 b : 12 : 85 : 35 : 8 a : b7 : 98 : b6 : d2 : 97 : 5 e : 96 : 58 : 1 d . Are you sure you want to continue connecting ( yes / no ) ?

Before typing 'yes' to accept the host fingerprint, ensure the fingerprint is correct for the host. You can find a listing of SSH host keys in the SSH Key Fingerprints list. If you receive a host key warning, please contact the SourceForge.net team.

The clone command will create a PROJECTNAME-REPOSITORY directory with the hgrepository inside the .hg subdirectory. If you're starting fresh, use whatever combination of "hg add" and "hg commit" commands you want to create one or more commits in your local repository. When you are ready, run "hg push" to push your commits to our server.

Users should commit to their project repository using their SourceForge.net username or email address (USERNAME@users.sourceforge.net). Several methods are supported for configuring this, please refer to the Mercurial Documentation for the supported methods.

Publishing an Existing Repository

If you already have a repository that you want to publish on SourceForge.net, you can publish it by first creating a new repository on SourceForge.net as described above (using the Mercurial tool in the administrative interface). This new repository will be completely empty and just be used as a container for your existing repository.

To replicate your existing repository, first clone the new repository as described above. This will create a local clone of the new repository in your own filesystem. Then, enter this clone and pull changes from your existing repository:

$ cd PROJECTNAME-REPOSITORY # the new, empty repository from SourceForge $ hg pull ../path/to/existing/repository $ hg update

Since the new repository is empty, Mercurial will happily perform the operation. (Had the new repository not been empty, Mercurial will have complained about you pulling changes into an unrelated repository.)

Now push the contents of the new repository back to SourceForge.net:

$ hg push

You're all set! What you have effectively done at this point is to clone your existing repository to the SourceForge.net server. In other environments, this would have been done using the following command:

$ hg clone path-to-existing-repository ssh://USERNAME@hg.code.SF.net/p/PROJECTNAME/REPOSITORY

However, due to various restrictions on the ssh login specific to SourceForge.net, the above command will not work. Thus, the create, clone, pull, push workflow is required to achieve the same thing.

Accessing the repository via the shell

Direct access to the bare repository is also available via [SSH], when logged into the shell, it will be available at:

/home/hg/p/PROJECTNAME/REPOSITORY/

Note that the directory is mounted during the shell creation, if you create a new repository while an existing shell session is still active, use the shutdown command on the shell and start a new session.

Hooks

Direct access to the repository can be used to install custom hg hooks server-side.

Note however, that a changegroup hook is used for site-integration, if this hook is changed, the code browser view may not longer automatically update.

If you need to re-create the default changegroup hook, the entry in the server-side .hg/hgrc file is as follows:

[hooks] ; = [the next line is required for site integration, do not remove/modify] = changegroup.sourceforge = curl -s http://sourceforge.net/auth/refresh_repo/p/PROJECTNAME/REPOSITORY/

Backups

SourceForge.net performs routine backups for all of our servers and will restore from these backups in the event of catastrophic server failure. We encourage projects to make their own backups of Mercurial data as that data restore can be performed by the project in the event of accidental data destruction by a member of the project team.

Backups of a Mercurial repository may be made using rsync.

Example (replace PROJECTNAME with the UNIX group name of your project):