[wiki]Mercurial hg使用指南

Historically, Solaris consolidations have used different source code management (SCM) solutions. TeamWare has been in use at Sun for over twelve years and supports large-scale, distributed software development. It is used by large, complex consolidations such as ON. Now that Solaris is being open sourced, SCM solutions that support the needs of open development are required.

In order for the OpenSolaris community to make progress, and in order to support new and current projects and consolidations that are not tied to TeamWare, two parallel efforts related to SCM support are being pursued. A Centralized SCM facility and a Distributed SCM (DSCM) solution will be supported. Subversion was chosen for the centralized solution and Mercurial for the distributed one.

This document aims to be an introduction to the Mercurial DSCM with emphasis on migration from TeamWare.

Note: The terms workspace and repository are used interchangeably in this document.

<script type="text/javascript"> if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); } </script>

Installation

The source code and pre-built packages can be downloaded from the Source Code Management Tool Downloads page on OpenSolaris.ORG. You need Python installed on your machine to use Mercurial.

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.

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)
...

Bringing over a repository

The equivalent of the TeamWare bringover command is the clone command which make a clone of a given repository.

hg clone /ws/onnv-clone onnv

Unlike TeamWare, Mercurial supports cloning and syncing repositories over HTTP and SSH.

hg clone ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
hg clone http://hg.genunix.org/on.hg

Like TeamWare, each Mercurial repository is self-contained. When you clone a repository, the new repository becomes an exact copy of the existing one at the time of the clone.

Note: Mercurial does not support partial bringovers right now. [1]

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 <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.

Syncing up with the parent

The pull and update commands are used to sync up the workspace with the parent.

hg pull
hg update

The pull command pulls changes from the parent repository but does not actually make any changes to the files in the repository. The hg update command is used to actually update the files in the repository.

Note: These two commands can be combined into a single hg pull --update command.

A repository location could be passed to the pull command to sync the repository with a different parent.

hg pull --update /ws/onnv-gate
hg pull --update ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
hg pull --update http://hg.genunix.org/on.hg

The equivalent of the bringover -n command (used to check what changes would be carried out without actually modifying the workspace) is the incoming command.

hg incoming
hg incoming ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate

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@hg.opensolaris.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@hg.opensolaris.org/hg/onnv/onnv-gate

Try It Out

The Mercurial ONNV repository mirror is located here:

ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate

This is a clone repository. Only pull operations are allowed. It is a live mirror of the internal TeamWare onnv-gate workspace and is updated as putbacks happen in real-time. Subscribe to the onnv-notify mailing list to receive putback notifications as they happen.

There is another ONNV repository mirror accessible over HTTP available here:

http://hg.genunix.org/on.hg

This is a read-only mirror too and only pull operations are allowed. (How often is this repository updated?)

The SWAN-internal ONNV sandbox is located here:

/net/tonic-gate.sfbay/gates/onnv-clone

Both pull and push operations are allowed. This sandbox gets reset every Monday.

See Also

• The Mercurial Wiki
• Mercurial Quick Start
• Source Code Management for OpenSolaris
• Mercurial for TeamWare users
• Other Teamware to Mercurial Resources
• Source Code Management Tool Downloads
• Mercurial real life usage for distant cvs repository master
• How to Use Mercurial Repositories
• List of ON Mercurial Repository Mirrors