Print this page
3810 remove support for teamware from webrev
Reviewed by: Andrew Stormont <AStormont@racktopsystems.com>
Reviewed by: Garrett D'Amore <garrett@damore.org>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/scripts/webrev.1
+++ new/usr/src/tools/scripts/webrev.1
1 1 .\"
2 2 .\" CDDL HEADER START
3 3 .\"
4 4 .\" The contents of this file are subject to the terms of the
5 5 .\" Common Development and Distribution License (the "License").
6 6 .\" You may not use this file except in compliance with the License.
7 7 .\"
8 8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 9 .\" or http://www.opensolaris.org/os/licensing.
10 10 .\" See the License for the specific language governing permissions
11 11 .\" and limitations under the License.
12 12 .\"
13 13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
|
↓ open down ↓ |
14 lines elided |
↑ open up ↑ |
15 15 .\" If applicable, add the following below this CDDL HEADER, with the
16 16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 18 .\"
19 19 .\" CDDL HEADER END
20 20 .\"
21 21 .\" Copyright 2010 Sun Microsystems, Inc. All rights reserved.
22 22 .\" Use is subject to license terms.
23 23 .\"
24 24 .\"
25 -.TH webrev 1 "6 Dec 2010"
25 +.TH webrev 1 "7 Feb 2014"
26 26 .SH NAME
27 27 webrev \- Generate HTML codereview materials
28 28 .SH SYNOPSIS
29 29 .B webrev
30 30 [
31 31 .I common-options
32 32 ]
33 33
34 34 .B webrev
35 35 [
36 36 .I common-options
37 37 ]
38 38 .I file-list-file
|
↓ open down ↓ |
3 lines elided |
↑ open up ↑ |
39 39 |
40 40 .I -
41 41
42 42 .B webrev
43 43 [
44 44 .I common-options
45 45 ]
46 46 .B -w
47 47 .I wx-file
48 48
49 -.B webrev
50 -[
51 -.I common-options
52 -]
53 -.B -l
54 -.I arguments to 'putback'
55 -
56 -See OPTIONS for common-options.
57 -Note that the -l option is only applicable to TeamWare workspaces.
58 -
59 49 .SH DESCRIPTION
60 50 .B webrev
61 51 builds a set of HTML files suitable for performing code review of
62 52 source changes in a web browser.
63 -It supports Mercurial, Git, Subversion and Teamware repositories.
53 +It supports Mercurial, Git and Subversion repositories.
64 54 At its most basic, usage is:
65 55 .nf
66 56 $ webrev
67 57 .fi
68 58
69 59 In which case \fBwebrev\fR attempts to figure out the list of files
70 -for review (note that when using Teamware \fBputback\fR, this may take
71 -a long time; see the -l option). If that fails, or if more control
60 +for review. If that fails, or if more control
72 61 over the set of files is needed, a \fIfile list\fR may be specified.
73 62 \fBwebrev\fR also attempts to deduce a
74 63 .I basis for comparison
75 64 (interchangeably called the \fIparent\fR, but see SCM INTERACTIONS below).
76 65 A basis for comparison is needed in order to determine the differences
77 66 introduced by the code changes under review.
78 67
79 68 By default, \fBwebrev\fR creates a \fIwebrev\fR directory in the
80 69 workspace directory that contains the generated HTML files, a generated
81 70 PDF review, and a patch representing the changes. It also places a
82 71 copy of the file list in that directory, and of both the old and new
83 72 raw files in the \fB$webrev_root/raw_files\fR directory.
84 73 To output the webrev somewhere other than the default location, use the
85 74 \fI-o <outdir>\fR option, or set the \fBWDIR\fR environment variable.
86 75 For example:
87 76 .nf
88 77 $ webrev -o ~/public_html/myreview/
89 78 .fi
90 79 .PP
91 80 In the index file, each file is listed on a line with a link to the
92 81 relevant review materials. Comments for each change will be included
93 82 automatically. Cross references to bug (or other information) tracking
94 83 databases in the comments will become hyperlinks in the associated web
95 84 interface, according to the rules in CROSS REFERENCING below.
96 85
97 86 As a review aid, content may be added to the \fIindex\fR file in two ways.
98 87 First, the author may manually edit the file (for example by including
99 88 text that explains the changes in front of the links for each file).
100 89 Note that if webrev is run again, manual edits will be lost. Second,
101 90 if a file named \fIwebrev-info\fR is present at the root of the workspace,
102 91 it will be automatically included in the \fIindex\fR file. To include a
103 92 different file, see the \fI-i\fR option.
104 93
105 94 For each file in the file list, \fBwebrev\fR compares the file with the
106 95 version in the basis for comparison (i.e. the parent workspace) and
107 96 generates a variety of HTML renderings of the differences between
108 97 the two files; which of these renderings to use is largely a matter
109 98 of personal preference. Additional, webrev emits a patch, the old
110 99 and new versions of the file, and a "raw" copy of the file which is
111 100 suitable for download. For files which express differences, source
112 101 is formatted according to the following color coding:
113 102 .IP
114 103 .nf
115 104 unchanged : black
116 105 removed : brown
117 106 changed : blue
118 107 new : bold blue
119 108 .fi
120 109
121 110 .SH SCM INTERACTIONS
122 111 .PP
123 112 .B webrev
124 113 attempts to interact with the source code management system currently in use.
125 114 .B webrev
126 115 needs to be able locate the code under review (i.e. the workspace) and
127 116 the basis for comparison (i.e. the parent). The method for doing so
128 117 depends upon the SCM in use, which
129 118 .B webrev
130 119 will also attempt to auto-discover. In all cases,
131 120 .B webrev
132 121 must either discover the list of files which have changed, or else this list
133 122 must be manually specified, either in "webrev file list" format or in "wx"
134 123 format.
135 124 See FILE LIST for more details.
136 125 .PP
137 126 In all cases, if the user has activated the workspace with the
138 127 .BR ws (1)
139 128 or
140 129 .BR bldenv (1)
141 130 commands, \fBwebrev\fR will use the \fBCODEMGR_PARENT\fR and
142 131 \fBCODEMGR_WS\fR environment variables to identify parent and child
143 132 workspaces respectively.
|
↓ open down ↓ |
62 lines elided |
↑ open up ↑ |
144 133 To manually specify the basis for comparison, use the -p option or
145 134 specify the \fBCODEMGR_PARENT\fR variable in either the file list or
146 135 the environment.
147 136
148 137 .SS Discovering the SCM in use.
149 138 .B webrev
150 139 makes use of
151 140 .BR which_scm (1)
152 141 to determine the SCM in use for a given workspace.
153 142
154 -.SS TeamWare
155 -In the case of TeamWare \fBwebrev\fR will use the output of "workspace
156 -name" to discover the workspace root, if not otherwise specified.
157 -.PP
158 -\fBwebrev\fR will attempt to use a
159 -.BR wx (1)
160 -active list in
161 -\fBCODEMGR_WS/wx/active\fR.
162 -To direct \fBwebrev\fR to determine the file list from the output of
163 -.BR putback "(1),"
164 -use the -l option. (Note that \fBwebrev\fR may also elect to use
165 -\fBputback\fR if it cannot determine the file list from
166 -.BR wx "(1))."
167 -The -l option indicates that subsequent arguments should be
168 -treated as arguments to
169 -.BR putback "(1)."
170 -This can be used to prune the set of files which putback examines,
171 -or to reference a teamware flp (file list program).
172 -
173 143 .SS Mercurial
174 144 In the case of Mercurial \fBwebrev\fR will attempt to use the output
175 145 from the
176 146 .BR hg (1)
177 147 "hg root" command to identify the workspace root, and the
178 148 "hg path default" command to identify the parent workspace.
179 149
180 150 .SS Git
181 151 In the case of Git \fBwebrev\fR will attempt to use the output from the
182 152 .BR git (1)
183 153 "git rev-parse --git-dir" command to identify the workspace root, and will
184 154 attempt to use the remote branch which the current branch is tracking as the
185 155 parent, if none is specified 'origin/master' will be used.
186 156
187 157 The parent specified when using git is, in all cases, a git 'tree-ish' and
188 158 never an actual git repository, remote or otherwise. Anything specifiable to
189 159 git as a tree-ish should, similarly, be specifiable as a parent for webrev.
190 160 This includes branches, explicit revisions, reflog entries, etc. See
191 161 .BR git-rev-parse (1)
192 162
193 163 .SS Subversion
194 164 In the case of Subversion \fBwebrev\fR will attempt to use the output
195 165 from the
196 166 .BR svn (1)
197 167 "svn info" to find the workspace root and subversion repository URL.
198 168 .PP
199 169 The file list will be created from the output of the "svn status" command.
200 170
201 171 .SH CROSS REFERENCING
202 172 .PP
203 173 After extracting comments (see FILE LIST below),
204 174 .B webrev
205 175 will translate cross references into hyperlinks. By default, information
206 176 about available information tracking systems can be found in
207 177 /opt/onbld/etc/its.reg, and the specification of a local domain and
208 178 selection and prioritization of systems
209 179 in /opt/onbld/etc/its.conf. These file formats are self documenting. Also
210 180 see the -I and -C options below.
211 181 .SH OPTIONS
212 182 .TP 10
213 183 .BI "-C " priority-file
214 184 In addition to the system default and an optional user-supplied ~/.its.conf,
215 185 use the specified file to specify a local domain list and prioritize the list
216 186 of information tracking systems to be searched automatically when resolving cross
217 187 references.
218 188 .TP 10
219 189 .BI "-D"
220 190 Delete remote webrev via SFTP. Default remote host is \fIcr.opensolaris.org\fR,
221 191 default remote directory for removal is the same as workspace/repository
222 192 basename. Remote target can be overriden using -t option. If combined with
223 193 -U the deletion will be performed first. Also, if used together with -U
224 194 and the removal fails, no upload is done. Without -U option no webrev will
225 195 be generated, just like if -n option was used. The deletion is done by
226 196 moving the webrev to special directory in user's home directory. It is
227 197 expected that the remote host periodically runs a script which deletes
228 198 the contents of this directory. See the ENVIRONMENT VARIABLES section for
229 199 more details about this directory.
|
↓ open down ↓ |
47 lines elided |
↑ open up ↑ |
230 200 .TP 10
231 201 .BI "-I " information-file
232 202 Use the specified file to seed the list of information tracking systems.
233 203 .TP 10
234 204 .BI "-i " include-file
235 205 Include the specified file into the index.html file which is generated
236 206 as part of the webrev. This allows a snippet of XHTML to be added by
237 207 the webrev author. User content is contained by a <div> tag and
238 208 the markup should validate as XHTML 1.0 Transitional.
239 209 .TP 10
240 -.BI "-l " putback-args
241 -Extract the file list from the output of
242 -.I putback -n.
243 -Any arguments supplied will be passed to
244 -.BR putback "(1)."
245 -See SCM INTERACTIONS. For more information about file
246 -lists, see FILE LIST. This argument should appear last.
247 -.TP 10
248 210 .BI "-N"
249 211 Suppress all comments from all output forms html, txt and pdf.
250 212 .TP 10
251 213 .BI "-n"
252 214 Do not generate webrev. Useful whenever only upload is needed.
253 215 .TP 10
254 216 .B -O
255 217 Enable \fIOpenSolaris\fR mode: information tracking system hyperlinks
256 218 are generated using the EXTERNAL_URL field from the specified its.reg entry,
257 219 instead of the default INTERNAL_URL_domain field, and sources which appear in
258 220 \fIusr/closed\fR are automatically elided from the review.
259 221 .TP 10
260 222 .BI "-o " output-dir
261 223 Place output from running the script in the directory specified. If
262 224 specified, this option takes precedence over the WDIR environment variable.
263 225 .TP 10
264 226 .BI "-p " basis-of-comparison
265 227 Specify a basis of comparison meaningful for the SCM currently in use.
266 228 See SCM INTERACTIONS and INCREMENTAL REVIEWS.
267 229 .TP 10
268 230 .BI "-t " target
269 231 Upload target. Specified in form of URI identifier. For SCP/SFTP it is
270 232 \fIssh://user@remote_host:remote_dir\fR and for rsync it is
271 233 \fIrsync://user@remote_host:remote_dir\fR. This option can override the
272 234 -o option if the URI is fully specified. The target is relative to
273 235 the top level directory of the default sftp/rsync directory tree.
274 236 .TP 10
275 237 .BI "-U"
276 238 Upload the webrev. Default remote host is \fIcr.opensolaris.org\fR.
277 239 Default transport is rsync. If it fails, fallback to SCP/SFTP transport
278 240 is done.
279 241 .TP 10
280 242 .BI "-w " wx-file
281 243 Extract the file list from the wx "active" file specified. 'wx' uses
282 244 this mode when invoking webrev. The list is assumed to be in the
283 245 format expected by the \fIwx\fR package. See FILE LIST, below.
284 246
285 247 .SH FILE LIST
286 248 .PP
287 249 .B Webrev
288 250 needs to be told or to discover which files have changed in a
289 251 given workspace. By default,
290 252 .B webrev
291 253 will attempt to autodetect the
292 254 list of changed files by first consulting
293 255 .BR wx "(1)."
294 256 If this information is not available, webrev tries to consult the SCM (Source
295 257 Code Manager) currently in use. If that fails, the user must intervene by
296 258 specifying either a file list or additional options specific to the SCM in use.
297 259
298 260 .SS Webrev Format
299 261 A webrev formatted file list contains a list of all the files to
300 262 be included in the review with paths relative to the workspace
301 263 directory, e.g.
302 264 .IP
303 265 .nf
304 266 \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c
305 267 usr/src/uts/common/fs/nfs/nfs_export.c
306 268 usr/src/cmd/fs.d/nfs/mountd/mountd.c
307 269 .fi
308 270 .PP
309 271 Include the paths of any files added, deleted, or modified.
310 272 You can keep this list of files in the webrev directory
311 273 that webrev creates in the workspace directory
312 274 (CODEMGR_WS).
313 275
314 276 If CODEMGR_WS is not set, it may be specified as an environment variable
315 277 within the file list, e.g.
316 278 .IP
317 279 .nf
318 280 \f(CWCODEMGR_WS=/home/brent/myws
319 281 usr/src/uts/common/fs/nfs/nfs_subr.c
320 282 usr/src/uts/common/fs/nfs/nfs_export.c
321 283 usr/src/cmd/fs.d/nfs/mountd/mountd.c
322 284 .fi
323 285 .PP
324 286 To compare the workspace against one other than the parent (see also
325 287 the -p option), include a CODEMGR_PARENT line in the file list, like:
326 288 .IP
327 289 .nf
328 290 \f(CWCODEMGR_WS=/home/brent/myws
329 291 CODEMGR_PARENT=/ws/onnv-gate
330 292 usr/src/uts/common/fs/nfs/nfs_subr.c
331 293 usr/src/uts/common/fs/nfs/nfs_export.c
332 294 usr/src/cmd/fs.d/nfs/mountd/mountd.c
333 295 .fi
334 296 .PP
335 297 Finally, run webrev with the name of the file containing the file list as an
336 298 argument, e.g.
337 299 .nf
338 300 $ webrev file.list
339 301 .fi
340 302 .PP
341 303 If "-" is supplied as the name of the file, then stdin will be used.
342 304
343 305 .SS wx Format
344 306 If the \fI-w\fR flag is specified then \fBwebrev\fR
345 307 will assume the file list is in the format expected by the "wx" package:
346 308 pathname lines alternating with SCCS comment lines separated by blank
347 309 lines, e.g.
348 310 .IP
349 311 .nf
350 312 \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c
351 313
352 314 1206578 Fix spelling error in comment
353 315
354 316 usr/src/uts/common/fs/nfs/nfs_export.c
355 317
356 318 4039272 cstyle fixes
357 319
358 320 usr/src/cmd/fs.d/nfs/mountd/mountd.c
359 321
360 322 1927634 mountd daemon doesn't handle expletives
361 323 .fi
362 324
363 325 .SH INCREMENTAL REVIEWS
364 326 When conducting multiple rounds of code review, it may be desirable to
365 327 generate a webrev which represents the delta between reviews. In this
366 328 case, set the parent workspace to the path to the old webrev:
367 329
368 330 .IP
369 331 .nf
370 332 \f(CW$ webrev -o ~/public_html/myreview-rd2/ \\
371 333 -p ~/public_html/myreview/
372 334 .fi
373 335
374 336 .SH ENVIRONMENT VARIABLES
375 337 The following environment variables allow for customization of \fBwebrev\fR:
376 338
377 339 .PP
378 340 \fBCDIFFCMD\fR and \fBUDIFFCMD\fR are used when generating Cdiffs and Udiffs
379 341 respectively; their default values are "diff -b -C 5" and "diff -b -U
380 342 5". To generate diffs with more (or less) than 5 lines of context or
381 343 with more (or less) strict whitespace handling, set one or both of
382 344 these variables in the user environment accordingly.
383 345
384 346 \fBWDIR\fR sets the output directory. It is functionally equivalent to
385 347 the \fI-o\fR option.
386 348
387 349 \fBWDIFF\fR specifies the command used to generate Wdiffs. Wdiff generates a
388 350 full unified context listing with line numbers where unchanged
389 351 sections of code may be expanded and collapsed. It also provides a
390 352 "split" feature that shows the same file in two HTML frames one above the
391 353 other. The default path for this script is
392 354 /ws/onnv-gate/public/bin/wdiff but WDIFF may be set to customize this
393 355 to use a more convenient location.
394 356
395 357 \fBWEBREV_TRASH_DIR\fR specifies alternative location of trash directory
396 358 for remote webrev deletion using the \fI-D\fR option. The directory is
397 359 relative to the top level directory of the default sftp/rsync directory tree.
398 360 The default value of this directory is ".trash".
399 361
400 362 .SH UPLOADING WEBREVS
401 363 A webrev can be uploaded to remote site using the -U option. To simply
402 364 generate new webrev and upload it to the default remote host use the following
403 365 command:
404 366 .IP
405 367 .nf
406 368 \f(CW$ webrev -U
407 369 .fi
408 370 .PP
409 371 This will generate the webrev to local directory named 'webrev' and upload it
410 372 to remote host with remote directory name equal to local workspace/repository
411 373 name. To change both local and remote directory name, -U can be combined with
412 374 -o option. The following command will store the webrev to local directory named
413 375 "foo.onnv" and upload it to the remote host with the same directory name:
414 376 .IP
415 377 .nf
416 378 \f(CW$ webrev -U -o $CODEMGR_WS/foo.onnv
417 379 .fi
418 380 .PP
419 381 If there is a need for manual change of the webrev before uploading,
420 382 -U can be combined with -n option so that first command will just generate
421 383 the webrev and the second command will upload it without generating it again:
422 384 .IP
423 385 .nf
424 386 \f(CW$ webrev
425 387 \f(CW$ webrev -n -U
426 388 .fi
427 389 .PP
428 390 For custom remote targets, -t option allows to specify all components:
429 391 .IP
430 392 .nf
431 393 \f(CW$ webrev -U -t \\
432 394 ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
433 395 .fi
434 396 .PP
435 397 If the remote path is specified as absolute, \fBwebrev\fR will assume all the
436 398 directories are already created. If the path is relative, \fBwebrev\fR will
437 399 try to create all needed directories. This only works with SCP/SFTP transport.
438 400 .PP
439 401 By default, rsync transport will use SSH for transferring the data to remote
440 402 site. To specify custom username, use entry in SSH client configuration file,
441 403 for example:
442 404 .IP
443 405 .nf
444 406 \f(CWHost cr.opensolaris.org
445 407 Hostname cr.opensolaris.org
446 408 User vkotal
447 409 .fi
448 410
449 411 .SH DELETING WEBREVS
450 412 When deleting a webrev directory on remote site which has a different name
451 413 than the basename of local repository it is necessary to specify the output
452 414 option:
453 415 .IP
454 416 .nf
455 417 \f(CW$ webrev -Do webrev-foo.onnv
456 418 .fi
457 419 .PP
458 420 Otherwise \fBwebrev\fR will attempt to remove remote directory with the same
459 421 name as basename of the local repository.
460 422 .PP
|
↓ open down ↓ |
203 lines elided |
↑ open up ↑ |
461 423 For the nested directory case it is necessary to specify the full target:
462 424 .IP
463 425 .nf
464 426 \f(CW$ webrev -D -t \\
465 427 ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
466 428 .fi
467 429 .PP
468 430 This will remove just the \fIbugfix.onnv\fR directory.
469 431
470 432 .SH SEE ALSO
471 -.BR putback "(1),"
472 -.BR workspace "(1),"
473 433 .BR hg "(1),"
474 434 .BR git "(1),"
475 435 .BR ssh_config "(4),"
476 436 .BR svn "(1),"
477 437 .BR which_scm "(1)"
478 438
479 439 .SH ACKNOWLEDGEMENTS
480 440 Acknowledgements to Rob Thurlow, Mike Eisler, Lin Ling,
481 441 Rod Evans, Mike Kupfer, Greg Onufer, Glenn Skinner,
482 442 Oleg Larin, David Robinson, Matthew Cross, David L. Paktor,
483 443 Neal Gafter, John Beck, Darren Moffat, Norm Shulman, Bill Watson,
484 444 Pedro Rubio and Bill Shannon for valuable feedback and insight in
485 445 building webrev.
486 446
487 447 Have fun!
488 448 .br
489 449 Brent Callaghan 11/28/96
490 450
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX