OpenSolaris_b135/tools/scripts/wx2hg.1

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