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