How to Use Mercurial (hg) Repositories
Introduction
Two kinds of source repositories are hosted at opensolaris.org: centralized and distributed. The centralized source management model uses the Subversion (SVN) source control management program. See the Subversion help page for information.
Repositories managed in a distributed fashion use the Mercurial source control management program. This page describes Mercurial. The first sections are for developers. The section at the end for Project Leads is labeled "For Project Leads".
How to install Mercurial
Mercurial is available via OpenSolaris and Solaris Express (build 88 or later).
Building from source code
The Mercurial Wiki has details on building Mercurial from source. Mercurial is primarily written in Python, but some of the extensions are in C.
How to get commit access to opensolaris.org Mercurial repositories
Developers with commit rights will access repositories through their opensolaris.org accounts. Commit rights are managed by Project Leaders. If you do not have an account, sign up to acquire one. Additionally, you will have to provide a Secure Shell (SSH) public key.
For anonymous access to a repository, use the user name 'anon'.
Proxies
If you are behind a firewall that requires that SSH connections be tunnelled through a SOCKS proxy, then your $HOME/.ssh/config file needs to contain a directive like:
Host *.opensolaris.org
ProxyCommand /usr/lib/ssh/ssh-socks5-proxy-connect -h [socks proxy address] %h %p
Sun employees should note that proxying should no longer be used from Sun's internal network. If you have ssh configured to use a proxy, you will eventually start seeing timeouts or other errors as the proxies are being decommissioned.
How to get started with Mercurial
General information about Mercurial and how to use it is available at the Mercurial website. There you will find a quickstart guide, a tutorial for new users, a FAQ, 'tips and tricks' and more.
Information for engineers transitioning from TeamWare is available on the How To Transition from Teamware to Mercurial page.
A few common operations are illustrated below, using the ON Nevada repository as an example.
Usage
The Mercurial program is named hg (the chemical symbol for Mercury). Every Mercurial command starts with hg, followed by the command name, followed by any relevant options and arguments. Just running hg on the command line displays a list of commands.
$ hg Mercurial Distributed SCM basic commands (use "hg help" for the full list or option "-v" for details): add add the specified files on the next commit annotate show changeset information per file line clone make a copy of an existing repository commit commit the specified files or all outstanding changes ...
The help command can be used to get more information about any command.
$ hg help diff hg diff [-a] [-I] [-X] [-r REV1 [-r REV2]] [FILE]... diff repository (or selected files) ...
Getting an initial copy
Use Mercurial's clone subcommand to get a copy of the project repository.
$ hg clone ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate my-copy requesting all changes adding changesets adding manifests adding file changes added 3196 changesets with 65633 changes to 42834 files 39543 files updated, 0 files merged, 0 files removed, 0 files unresolved
Updating a child repository
Use Mercurial's pull and update subcommands to acquire any changes since your last pull or clone operation. If there are no pending changes, you'll see a result like:
$ cd my-copy $ hg pull pulling from ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate searching for changes no changes found
Otherwise, you'll get output informing you of the number of changesets involved:
$ hg pull pulling from ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate searching for changes adding changesets adding manifests adding file changes added 503 changesets with 5608 changes to 4444 files (run 'hg update' to get a working copy) $ hg update 4433 files updated, 0 files merged, 376 files removed, 0 files unresolved
Using hg bundles of the ON repository
OpenSolaris mercurial repositories are sometimes provided as "bundles" with a .hg extension. There are two types of bundles - Changesets and Incremental. Changeset bundles are complete standalone bundles. To get a working copy of this bundle, download it from the opensolaris.org downloads page and do the following steps.
cd /export/work
hg init
hg unbundle {path}/on-hg-bundle-YYYYMMDD.hg
hg update
Incremental bundles are typically named as "on-hg-bundle_yyyymmdd-YYYYMMDD.hg" and contain only incremental changes. They can only be applied to a working copy which contains all changesets up to yyyymmdd and no more. This is verified before the unbundling process by checking the parent property (hg parent) of the bundle. You can apply an incremental bundle to a working copy using the following commands
cd /export/work hg unbundle on-hg-bundle_yyyymmdd-YYYYMMDD.hg hg update
Once you have a working copy, you can clone it and do other operations described below.
Editing files
There is no equivalent of the sccs edit or wx edit. Mercurial automatically keeps track of modified files.
Adding files
The equivalent of the wx create command to add files to the workspace is the add command.
hg add file1.c ...
These files will be added to the repository on the next commit.
Examining differences
The equivalent of the sccs diffs and the wx diffs commands is the diff command.
hg diff
Without any arguments, hg diff will print out the differences between all modified files in the repository. Differences between files are shown using the unified diff format.
Commiting the changes
The equivalent of the sccs delget and wx delget commands is the commit command.
hg commit
This command drops us into an editor (configured using the EDITOR and HGEDITOR environment variables) where we can add the putback comments. Once we save the changes and quit the editor, the changes are committed to the repository.
Putting back the changes to the parent repository
All changes up to this point have been in the working clone repository. The changes can be put back to the parent repository using the push command.
hg push /ws/onnv-gate
This is the equivalent of the Teamware command "putback -p /ws/onnv-gate". It is not mandatory to provide the path to the repository to push the changes to. If no repository is specified, the changes will be pushed to the repository we cloned from.
The equivalent of the "putback -n" command is Mercurial's "outgoing" command.
hg outgoing hg outgoing ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
More Information
For Project Leads: How to set up a Mercurial repository
The creation of a Mercurial repository on opensolaris.org is done through the webpages. You have to be a project leader to create a new repository.
On the main page for a project, there is an item called "SCM Console". This item will lead you to the SCM configuration page. Choose "Create Repository". You will be asked to provide a name for the repository, a notification email address, the repository type (Subversion or Mercurial), and whether anonymous access is allowed. Click the "Create" button to add the repository. After the repository has been created successfully, a short summary of the repository name and properties will be shown. You can click the name of the repository in this summary to add/remove committers.
The URL for the repository will be of the format
ssh://user@hg.opensolaris.org/hg/projectname/reponame
Where "projectname" is the name of your project and "reponame" the name of the newly created repository. "user" can be "anon" or the opensolaris.org username of someone who has commit rights to the repository.
There is currently no support for deleting repositories via the website. If you own a repository that you want to go away, please send mail to tonic-ops@sun.com.