1 .\" CDDL HEADER START
   2 .\"
   3 .\" The contents of this file are subject to the terms of the
   4 .\" Common Development and Distribution License (the "License").
   5 .\" You may not use this file except in compliance with the License.
   6 .\"
   7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   8 .\" or http://www.opensolaris.org/os/licensing.
   9 .\" See the License for the specific language governing permissions
  10 .\" and limitations under the License.
  11 .\"
  12 .\" When distributing Covered Code, include this CDDL HEADER in each
  13 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  14 .\" If applicable, add the following below this CDDL HEADER, with the
  15 .\" fields enclosed by brackets "[]" replaced with your own identifying
  16 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  17 .\"
  18 .\" CDDL HEADER END
  19 .\"
  20 .\" Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
  21 .\" Use is subject to license terms.
  22 .\"
  23 .\" ident       "%Z%%M% %I%     %E% SMI"
  24 .TH wx2hg 1 "29 Jul 2008"
  25 .SH NAME
  26 .I wx2hg
  27 \- Convert a wx-managed workspace to Mercurial.
  28 .SH SYNOPSIS
  29 .B wx2hg
  30 [ \fB\-u\fR ]
  31 [ \fB\-r\fR \fIhg_rev\fR ]
  32 [ \fB\-t\fR \fIhg_ws\fR ]
  33 \fItw_ws\fR
  34 .LP
  35 .SH DESCRIPTION
  36 .I wx2hg
  37 takes a Teamware workspace
  38 and converts it to a workspace that is managed by
  39 Mercurial.  It is aimed at OS/Net projects that were started under
  40 Teamware but which expect to deliver into a
  41 Mercurial gate.  As such, it assumes the following usage model:
  42 .LP
  43 Suppose that you have a project workspace, which has some changes
  44 relative to its parent workspace.
  45 .I wx2hg
  46 checks for the existence of, and creates if necessary,
  47 a Mercurial workspace called
  48 \fItw_ws\fR\-hg that is in sync with the Mercurial twin
  49 of its parent workspace.
  50 Then it applies the changes from your project workspace to this Mercurial
  51 workspace.
  52 You can review the changes
  53 before committing them.  Note that any
  54 intermediate deltas will be lost; note also that your child workspace
  55 must be up-to-date with respect to the parent.
  56 .LP
  57 .I wx2hg
  58 uses 
  59 .BR wx (1)
  60 to determine which files have been renamed or altered.  If your
  61 workspace is not already controlled by
  62 .BR wx (1),
  63 .I wx2hg
  64 puts it under
  65 .BR wx (1)
  66 control.  If your workspace is already under 
  67 .BR wx (1)
  68 control,
  69 .I wx2hg
  70 runs 
  71 .BR wx update
  72 to ensure that the
  73 .BR wx (1)
  74 state files are up-to-date.  This step can take a while.  If you are
  75 sure that 
  76 .BR wx (1)
  77 already has the right list of files, you can skip this step by using
  78 the
  79 .B \-u
  80 option.
  81 .LP
  82 You can use the
  83 .B \-t
  84 .I hg_ws
  85 option to name the Mercurial target workspace, rather than having
  86 .I wx2hg
  87 default to using \fItw_ws\fR\-hg.  
  88 .LP
  89 .I wx2hg
  90 checks the Mercurial workspace against the Teamware parent.  If it
  91 finds a discrepancy, it assumes that the Teamware parent corresponds
  92 to an older revision within the mercurial workspace.  You must rerun 
  93 .I wx2hg 
  94 and use the
  95 .B \-r 
  96 .I hg_rev
  97 option to specify that revision.  (See below for more discussion on
  98 recovery from errors.)
  99 With the 
 100 .B \-r
 101 option,
 102 .I wx2hg
 103 updates the Mercurial working directory
 104 to that older revision and then applies your
 105 changes.  You will need to use mercurial to merge your changes with
 106 later changes in the workspace before pushing your changes to a parent
 107 workspace.
 108 .LP
 109 .I wx2hg
 110 exits with an error if it detects a rename conflict.
 111 .LP
 112 If 
 113 .I wx2hg
 114 exits with an error, you can discard any changes made prior to the
 115 error, then use the
 116 .B \-t
 117 option to reuse the workspace.  To discard changes made prior to the
 118 error, use this command:
 119 .LP
 120 .RS 5
 121 hg \-R \fIhg_ws\fR update \-C
 122 .RE
 123 .LP
 124 .SH OPTIONS
 125 .IP "\fB\-r\fR \fIhg_rev\fR" 10
 126 Use
 127 .I hg_rev
 128 as the Mercurial changeset that corresponds to the point
 129 in time at which your teamware workspace was synchronized with its parent.
 130 If you don't have any nested repositories, you may specify
 131 .I hg_rev
 132 as a changeset id or a Mercurial tag.  If you have nested repositories,
 133 like usr/closed in ON, then you should specify a Mercurial tag common to
 134 both (or all) repositories.  This tag may be local (ie a local tag that you
 135 create yourself using \fIhg tag -l\fR) or version controlled (ie a tag
 136 that the gatekeepers created, such as \fIonnv_96\fR).
 137 If you use
 138 .I hg_rev
 139 without specifying \fIhg_ws\fR, then the tags must resolve correctly
 140 in the Mercurial twin(s) of your Teamware parent.
 141 If you use
 142 .I hg_rev
 143 in conjunction with \fIhg_ws\fR, then the tags must resolve correctly
 144 in your existing Mercurial repositories.
 145 .IP "\fB\-t\fR \fIhg_ws\fR" 10
 146 Use an existing Mercurial workspace as the target, rather than
 147 creating one.  If you use an existing workspace, you must also create any
 148 nested repositories (like usr/closed) before running wx2hg.
 149 .IP
 150 If omitted, 
 151 .I tw_ws
 152 must be a child of /ws/onnv-clone, and
 153 .I wx2hg
 154 will create the Mercurial workspace \fItw_ws\fR\-hg.
 155 .IP \fB\-u\fR
 156 Skip the "wx update" step if the workspace is already under
 157 .BR wx (1)
 158 control.
 159 .LP
 160 .SH SEE ALSO
 161 .BR hg "(1), " wx (1)
 162 .LP
 163 .SH DIAGNOSTICS
 164 .LP
 165 wx2hg: 
 166 .I tw_parent
 167 is not recognized as a gate; please provide a Mercurial workspace (-t
 168 hg_ws) that matches it.
 169 .LP
 170 .RS 5
 171 This means that 
 172 .I tw_parent
 173 does not contain a Codemgr_wsdata/hg_twin file pointing at its mercurial
 174 equivalent.  If necessary, you may reparent
 175 .I tw_ws
 176 to a workspace that specifies an hg_twin
 177 and rerun 
 178 .IR wx2hg .
 179 Otherwise, you must use the
 180 .B \-t
 181 option to specify an existing
 182 Mercurial workspace whose contents matches the parent of
 183 .IR tw_ws .
 184 .RE
 185 .LP
 186 teamware parent ... doesn't match its mercurial twin
 187 .LP
 188 .RS 5
 189 .I wx2hg
 190 detected an unexpected difference between the Teamware parent and the
 191 Mercurial workspace.  This likely means that the parent of your
 192 teamware workspace is not in synch with the mercurial parent.  In that
 193 case, ask the maintainer of the parent workspace to resynchronize
 194 them, or use
 195 .B \-r
 196 to specify a revision of the Mercurial workspace that matches the
 197 Teamware parent.
 198 .RE
 199 .LP
 200 wx2hg will only migrate checked-in files; please check in these files with wx
 201 ci and try again
 202 .LP
 203 .RS 5
 204 In order to minimize spurious conflicts due to SCCS keyword
 205 substitution, 
 206 .I wx2hg
 207 only migrates changes in checked-in files.  Please check in your
 208 changes with 
 209 .I wx delget
 210 prior to migration.
 211 .RE
 212 .SH FILES
 213 .IP \fItw_ws\fR/Codemgr_wsdata/hg_twin
 214 is read by wx2hg from the parent workspace of the teamware workspace
 215 being converted in order to find the mercurial equivalent of that
 216 workspace.  The first line of hg_twin contains the URL of the
 217 mercurial equivalent workspace.  Since a single teamware workspace may
 218 be split into multiple mercurial repositories, the 2nd and subsequent
 219 lines of the file contain the relative paths within the first
 220 repository of additional child repositories.  The maintainer of a gate
 221 being converted is responsible for creating this file to allow
 222 teamware children of the teamware gate to be converted into mercurial
 223 children of the mercurial gate.
 224 .RE
 225 .SH BUGS
 226 If a file is both renamed and updated, doing an "hg diff" in the
 227 Mercurial workspace will
 228 show the entire (new) contents of the file, not just the updates.
 229 .LP
 230 There is no attempt at automated recovery in case of a rename
 231 conflict.
 232 .LP
 233 If a Teamware workspace is split into multiple Mercurial twin
 234 workspaces (as is the case with the ON closed source tree), then
 235 Teamware filemv commands that result in moving across repository
 236 boundaries will result in file removal from the source repository and
 237 file addition to the destination repository.  So a webrev will not
 238 show changes to such files, merely entire old and new contents.