CDDL HEADER START

The contents of this file are subject to the terms of the
Common Development and Distribution License (the "License").
You may not use this file except in compliance with the License.

You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.

When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]

CDDL HEADER END

Copyright 2008 Sun Microsystems, Inc. All rights reserved.
Use is subject to license terms.

ident "%Z%%M% %I% %E% SMI"
wx2hg - Convert a wx-managed workspace to Mercurial. wx2hg [ -u ] [ -r hg_rev ] [ -t hg_ws ] tw_ws

wx2hg takes a Teamware workspace and converts it to a workspace that is managed by Mercurial. It is aimed at OS/Net projects that were started under Teamware but which expect to deliver into a Mercurial gate. As such, it assumes the following usage model:

Suppose that you have a project workspace, which has some changes relative to its parent workspace. wx2hg checks for the existence of, and creates if necessary, a Mercurial workspace called tw_ws-hg that is in sync with the Mercurial twin of its parent workspace. Then it applies the changes from your project workspace to this Mercurial workspace. You can review the changes before committing them. Note that any intermediate deltas will be lost; note also that your child workspace must be up-to-date with respect to the parent.

wx2hg uses wx (1) to determine which files have been renamed or altered. If your workspace is not already controlled by wx (1), wx2hg puts it under wx (1) control. If your workspace is already under wx (1) control, wx2hg runs wx update to ensure that the wx (1) state files are up-to-date. This step can take a while. If you are sure that wx (1) already has the right list of files, you can skip this step by using the -u option.

You can use the -t hg_ws option to name the Mercurial target workspace, rather than having wx2hg default to using tw_ws-hg.

wx2hg checks the Mercurial workspace against the Teamware parent. If it finds a discrepancy, it assumes that the Teamware parent corresponds to an older revision within the mercurial workspace. You must rerun wx2hg and use the -r hg_rev option to specify that revision. (See below for more discussion on recovery from errors.) With the -r option, wx2hg updates the Mercurial working directory to that older revision and then applies your changes. You will need to use mercurial to merge your changes with later changes in the workspace before pushing your changes to a parent workspace.

wx2hg exits with an error if it detects a rename conflict.

If wx2hg exits with an error, you can discard any changes made prior to the error, then use the -t option to reuse the workspace. To discard changes made prior to the error, use this command:

Use hg_rev as the Mercurial changeset that corresponds to the point in time at which your teamware workspace was synchronized with its parent. If you don't have any nested repositories, you may specify hg_rev as a changeset id or a Mercurial tag. If you have nested repositories, like usr/closed in ON, then you should specify a Mercurial tag common to both (or all) repositories. This tag may be local (ie a local tag that you create yourself using hg tag -l) or version controlled (ie a tag that the gatekeepers created, such as onnv_96). If you use hg_rev without specifying hg_ws, then the tags must resolve correctly in the Mercurial twin(s) of your Teamware parent. If you use hg_rev in conjunction with hg_ws, then the tags must resolve correctly in your existing Mercurial repositories. Use an existing Mercurial workspace as the target, rather than creating one. If you use an existing workspace, you must also create any nested repositories (like usr/closed) before running wx2hg. If omitted, tw_ws must be a child of /ws/onnv-clone, and wx2hg will create the Mercurial workspace tw_ws-hg. Skip the "wx update" step if the workspace is already under wx (1) control.

hg "(1), " wx (1)

wx2hg: tw_parent is not recognized as a gate; please provide a Mercurial workspace (-t hg_ws) that matches it.

teamware parent ... doesn't match its mercurial twin

wx2hg will only migrate checked-in files; please check in these files with wx ci and try again

is read by wx2hg from the parent workspace of the teamware workspace being converted in order to find the mercurial equivalent of that workspace. The first line of hg_twin contains the URL of the mercurial equivalent workspace. Since a single teamware workspace may be split into multiple mercurial repositories, the 2nd and subsequent lines of the file contain the relative paths within the first repository of additional child repositories. The maintainer of a gate being converted is responsible for creating this file to allow teamware children of the teamware gate to be converted into mercurial children of the mercurial gate. If a file is both renamed and updated, doing an "hg diff" in the Mercurial workspace will show the entire (new) contents of the file, not just the updates.

There is no attempt at automated recovery in case of a rename conflict.

If a Teamware workspace is split into multiple Mercurial twin workspaces (as is the case with the ON closed source tree), then Teamware filemv commands that result in moving across repository boundaries will result in file removal from the source repository and file addition to the destination repository. So a webrev will not show changes to such files, merely entire old and new contents.