| blob | 6bb605c53218971ad8ab99377ba368ecb1d299cf |
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.