OpenSolaris

You are not signed in. Sign in or register.

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

NOTE: Mercurial is available in Solaris Express releases, starting with Build 46.

Or you can download the SUNWmercurial package from the SCM downloads page, and follow the instructions to install them.

x86:
# /usr/sfw/bin/wget http://www.opensolaris.org/os/community/tools/scmdownloads/SUNWmercurial-<date>.i386.pkg
# /usr/sbin/pkgadd -d SUNWmercurial-<date>.i386.pkg

SPARC:
# /usr/sfw/bin/wget http://www.opensolaris.org/os/community/tools/scmdownloads/SUNWmercurial-<date>.sparc.pkg
# /usr/sbin/pkgadd -d SUNWmercurial-<date>.sparc.pkg

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. SSH uses "public key encryption". To use SSH with this encryption mechanism, a user needs to have a private SSH "key" and a public key, which can be generated using the ssh-keygen(1) command. It is recommended that the key contain at least 1024 bits, and is protected with a password of at least 8 characters, containing both lower- and uppercase letters, and 2 or more non-letters. A sample invocation of the ssh-keygen(1) command to generate these keys would be:

$ ssh-keygen -b 1024 -t dsa

This command will ask for a password, and will save the keyfiles in the .ssh directory in your home directory. The public key will be in a file called id_dsa.pub in the .ssh directory.

Once created, user public keys are submitted via the user's "Update Profile" page. If the user is logged in, click on the:

"You are signed in as USERID (NAME)."
link in the top right corner of the page. Then click on the
"Update Profile"
link. The fields for entering SSH keys will be on the presented page (along with other profile details).

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

If you are a Sun employee who needs information about available SOCKS proxies, you can check this internal web page.

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 Martin Englund's blog.

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 typically 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 upto 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  ...
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
hg push ssh://anon at hg dot opensolaris dot org/hg/onnv/onnv-gate
hg push http://hg.genunix.org/on.hg
This command is the equivalent of the "workspace parent -p /ws/onnv-gate" and "putback" TeamWare commands.
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 at hg dot opensolaris dot org/hg/onnv/onnv-gate

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 Management".  This item will lead you to the SCM configuration page.  Choose "Add 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 "Add" 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" is the opensolaris.org username of an engineer 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 dash ops at sun dot com.