.\" 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" .TH wx2hg 1 "29 Jul 2008" .SH NAME .I wx2hg \- Convert a wx-managed workspace to Mercurial. .SH SYNOPSIS .B wx2hg [ \fB\-u\fR ] [ \fB\-r\fR \fIhg_rev\fR ] [ \fB\-t\fR \fIhg_ws\fR ] \fItw_ws\fR .LP .SH DESCRIPTION .I 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: .LP Suppose that you have a project workspace, which has some changes relative to its parent workspace. .I wx2hg checks for the existence of, and creates if necessary, a Mercurial workspace called \fItw_ws\fR\-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. .LP .I wx2hg uses .BR wx (1) to determine which files have been renamed or altered. If your workspace is not already controlled by .BR wx (1), .I wx2hg puts it under .BR wx (1) control. If your workspace is already under .BR wx (1) control, .I wx2hg runs .BR wx update to ensure that the .BR wx (1) state files are up-to-date. This step can take a while. If you are sure that .BR wx (1) already has the right list of files, you can skip this step by using the .B \-u option. .LP You can use the .B \-t .I hg_ws option to name the Mercurial target workspace, rather than having .I wx2hg default to using \fItw_ws\fR\-hg. .LP .I 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 .I wx2hg and use the .B \-r .I hg_rev option to specify that revision. (See below for more discussion on recovery from errors.) With the .B \-r option, .I 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. .LP .I wx2hg exits with an error if it detects a rename conflict. .LP If .I wx2hg exits with an error, you can discard any changes made prior to the error, then use the .B \-t option to reuse the workspace. To discard changes made prior to the error, use this command: .LP .RS 5 hg \-R \fIhg_ws\fR update \-C .RE .LP .SH OPTIONS .IP "\fB\-r\fR \fIhg_rev\fR" 10 Use .I 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 .I 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 \fIhg tag -l\fR) or version controlled (ie a tag that the gatekeepers created, such as \fIonnv_96\fR). If you use .I hg_rev without specifying \fIhg_ws\fR, then the tags must resolve correctly in the Mercurial twin(s) of your Teamware parent. If you use .I hg_rev in conjunction with \fIhg_ws\fR, then the tags must resolve correctly in your existing Mercurial repositories. .IP "\fB\-t\fR \fIhg_ws\fR" 10 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. .IP If omitted, .I tw_ws must be a child of /ws/onnv-clone, and .I wx2hg will create the Mercurial workspace \fItw_ws\fR\-hg. .IP \fB\-u\fR Skip the "wx update" step if the workspace is already under .BR wx (1) control. .LP .SH SEE ALSO .BR hg "(1), " wx (1) .LP .SH DIAGNOSTICS .LP wx2hg: .I tw_parent is not recognized as a gate; please provide a Mercurial workspace (-t hg_ws) that matches it. .LP .RS 5 This means that .I tw_parent does not contain a Codemgr_wsdata/hg_twin file pointing at its mercurial equivalent. If necessary, you may reparent .I tw_ws to a workspace that specifies an hg_twin and rerun .IR wx2hg . Otherwise, you must use the .B \-t option to specify an existing Mercurial workspace whose contents matches the parent of .IR tw_ws . .RE .LP teamware parent ... doesn't match its mercurial twin .LP .RS 5 .I wx2hg detected an unexpected difference between the Teamware parent and the Mercurial workspace. This likely means that the parent of your teamware workspace is not in synch with the mercurial parent. In that case, ask the maintainer of the parent workspace to resynchronize them, or use .B \-r to specify a revision of the Mercurial workspace that matches the Teamware parent. .RE .LP wx2hg will only migrate checked-in files; please check in these files with wx ci and try again .LP .RS 5 In order to minimize spurious conflicts due to SCCS keyword substitution, .I wx2hg only migrates changes in checked-in files. Please check in your changes with .I wx delget prior to migration. .RE .SH FILES .IP \fItw_ws\fR/Codemgr_wsdata/hg_twin 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. .RE .SH BUGS 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. .LP There is no attempt at automated recovery in case of a rename conflict. .LP 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.