Print this page
9001 cdm is useless, remove it
9002 webrev should know how to get the git user name
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
Reviewed by: Joshua M. Clulow <jmc@joyent.com>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/scripts/webrev.1onbld
+++ 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.
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 25 .TH WEBREV 1ONBLD "Mar 27, 2016"
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
|
↓ open down ↓ |
42 lines elided |
↑ open up ↑ |
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 -It supports Mercurial, Git and Subversion repositories.
53 +It supports 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
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 127 .BR ws (1ONBLD)
128 128 or
129 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.
|
↓ open down ↓ |
69 lines elided |
↑ open up ↑ |
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 140 .BR which_scm (1ONBLD)
141 141 to determine the SCM in use for a given workspace.
142 142
143 -.SS Mercurial
144 -In the case of Mercurial \fBwebrev\fR will attempt to use the output
145 -from the
146 -.BR hg (1)
147 -"hg root" command to identify the workspace root, and the
148 -"hg path default" command to identify the parent workspace.
149 -
150 143 .SS Git
151 144 In the case of Git \fBwebrev\fR will attempt to use the output from the
152 145 .BR git (1)
153 146 "git rev-parse --git-dir" command to identify the workspace root, and will
154 147 attempt to use the remote branch which the current branch is tracking as the
155 148 parent, if none is specified 'origin/master' will be used.
156 149
157 150 The parent specified when using git is, in all cases, a git 'tree-ish' and
158 151 never an actual git repository, remote or otherwise. Anything specifiable to
159 152 git as a tree-ish should, similarly, be specifiable as a parent for webrev.
160 153 This includes branches, explicit revisions, reflog entries, etc. See
161 154 .BR git-rev-parse (1)
162 155
163 156 .SS Subversion
164 157 In the case of Subversion \fBwebrev\fR will attempt to use the output
165 158 from the
166 159 .BR svn (1)
167 160 "svn info" to find the workspace root and subversion repository URL.
168 161 .PP
169 162 The file list will be created from the output of the "svn status" command.
170 163
171 164 .SH CROSS REFERENCING
172 165 .PP
173 166 After extracting comments (see FILE LIST below),
174 167 .B webrev
175 168 will translate cross references into hyperlinks. By default, information
176 169 about available information tracking systems can be found in
177 170 /opt/onbld/etc/its.reg, and the specification of a local domain and
178 171 selection and prioritization of systems
179 172 in /opt/onbld/etc/its.conf. These file formats are self documenting. Also
180 173 see the -I and -C options below.
181 174 .SH OPTIONS
182 175 .TP 10
183 176 .BI "-c " revision
184 177 Generate webrev for single commit specified by \fIrevision\fR (git only).
185 178 .TP 10
186 179 .BI "-C " priority-file
187 180 In addition to the system default and an optional user-supplied ~/.its.conf,
188 181 use the specified file to specify a local domain list and prioritize the list
189 182 of information tracking systems to be searched automatically when resolving cross
190 183 references.
191 184 .TP 10
192 185 .BI "-D"
193 186 Delete remote webrev via SFTP. Default remote host is \fIcr.opensolaris.org\fR,
194 187 default remote directory for removal is the same as workspace/repository
195 188 basename. Remote target can be overriden using -t option. If combined with
196 189 -U the deletion will be performed first. Also, if used together with -U
197 190 and the removal fails, no upload is done. Without -U option no webrev will
198 191 be generated, just like if -n option was used. The deletion is done by
199 192 moving the webrev to special directory in user's home directory. It is
200 193 expected that the remote host periodically runs a script which deletes
201 194 the contents of this directory. See the ENVIRONMENT VARIABLES section for
202 195 more details about this directory.
203 196 .TP 10
204 197 .BI "-h " head-revision
205 198 Specify the explicit head to generate webrev from (git only).
206 199 .TP 10
207 200 .BI "-I " information-file
208 201 Use the specified file to seed the list of information tracking systems.
209 202 .TP 10
210 203 .BI "-i " include-file
211 204 Include the specified file into the index.html file which is generated
212 205 as part of the webrev. This allows a snippet of XHTML to be added by
213 206 the webrev author. User content is contained by a <div> tag and
214 207 the markup should validate as XHTML 1.0 Transitional.
215 208 .TP 10
216 209 .BI "-N"
217 210 Suppress all comments from all output forms html, txt and pdf.
218 211 .TP 10
219 212 .BI "-n"
220 213 Do not generate webrev. Useful whenever only upload is needed.
221 214 .TP 10
222 215 .B -O
223 216 Enable \fIOpenSolaris\fR mode: information tracking system hyperlinks
224 217 are generated using the EXTERNAL_URL field from the specified its.reg entry,
225 218 instead of the default INTERNAL_URL_domain field, and sources which appear in
226 219 \fIusr/closed\fR are automatically elided from the review.
227 220 .TP 10
228 221 .BI "-o " output-dir
229 222 Place output from running the script in the directory specified. If
230 223 specified, this option takes precedence over the WDIR environment variable.
231 224 .TP 10
232 225 .BI "-p " basis-of-comparison
233 226 Specify a basis of comparison meaningful for the SCM currently in use.
234 227 See SCM INTERACTIONS and INCREMENTAL REVIEWS.
235 228 .TP 10
236 229 .BI "-t " target
237 230 Upload target. Specified in form of URI identifier. For SCP/SFTP it is
238 231 \fIssh://user@remote_host:remote_dir\fR and for rsync it is
239 232 \fIrsync://user@remote_host:remote_dir\fR. This option can override the
240 233 -o option if the URI is fully specified. The target is relative to
241 234 the top level directory of the default sftp/rsync directory tree.
242 235 .TP 10
243 236 .BI "-U"
244 237 Upload the webrev. Default remote host is \fIcr.opensolaris.org\fR.
245 238 Default transport is rsync. If it fails, fallback to SCP/SFTP transport
246 239 is done.
247 240 .TP 10
248 241 .BI "-w " wx-file
249 242 Extract the file list from the wx "active" file specified. 'wx' uses
250 243 this mode when invoking webrev. The list is assumed to be in the
251 244 format expected by the \fIwx\fR package. See FILE LIST, below.
252 245
253 246 .SH FILE LIST
254 247 .PP
255 248 .B Webrev
256 249 needs to be told or to discover which files have changed in a
257 250 given workspace. By default,
258 251 .B webrev
259 252 will attempt to autodetect the
260 253 list of changed files by first consulting
261 254 .BR wx "(1)."
262 255 If this information is not available, webrev tries to consult the SCM (Source
263 256 Code Manager) currently in use. If that fails, the user must intervene by
264 257 specifying either a file list or additional options specific to the SCM in use.
265 258
266 259 .SS Webrev Format
267 260 A webrev formatted file list contains a list of all the files to
268 261 be included in the review with paths relative to the workspace
269 262 directory, e.g.
270 263 .IP
271 264 .nf
272 265 \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c
273 266 usr/src/uts/common/fs/nfs/nfs_export.c
274 267 usr/src/cmd/fs.d/nfs/mountd/mountd.c
275 268 .fi
276 269 .PP
277 270 Include the paths of any files added, deleted, or modified.
278 271 You can keep this list of files in the webrev directory
279 272 that webrev creates in the workspace directory
280 273 (CODEMGR_WS).
281 274
282 275 If CODEMGR_WS is not set, it may be specified as an environment variable
283 276 within the file list, e.g.
284 277 .IP
285 278 .nf
286 279 \f(CWCODEMGR_WS=/home/brent/myws
287 280 usr/src/uts/common/fs/nfs/nfs_subr.c
288 281 usr/src/uts/common/fs/nfs/nfs_export.c
289 282 usr/src/cmd/fs.d/nfs/mountd/mountd.c
290 283 .fi
291 284 .PP
292 285 To compare the workspace against one other than the parent (see also
293 286 the -p option), include a CODEMGR_PARENT line in the file list, like:
294 287 .IP
295 288 .nf
296 289 \f(CWCODEMGR_WS=/home/brent/myws
297 290 CODEMGR_PARENT=/ws/onnv-gate
298 291 usr/src/uts/common/fs/nfs/nfs_subr.c
299 292 usr/src/uts/common/fs/nfs/nfs_export.c
300 293 usr/src/cmd/fs.d/nfs/mountd/mountd.c
301 294 .fi
302 295 .PP
303 296 Finally, run webrev with the name of the file containing the file list as an
304 297 argument, e.g.
305 298 .nf
306 299 $ webrev file.list
307 300 .fi
308 301 .PP
309 302 If "-" is supplied as the name of the file, then stdin will be used.
310 303
311 304 .SS wx Format
312 305 If the \fI-w\fR flag is specified then \fBwebrev\fR
313 306 will assume the file list is in the format expected by the "wx" package:
314 307 pathname lines alternating with SCCS comment lines separated by blank
315 308 lines, e.g.
316 309 .IP
317 310 .nf
318 311 \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c
319 312
320 313 1206578 Fix spelling error in comment
321 314
322 315 usr/src/uts/common/fs/nfs/nfs_export.c
323 316
324 317 4039272 cstyle fixes
325 318
326 319 usr/src/cmd/fs.d/nfs/mountd/mountd.c
327 320
328 321 1927634 mountd daemon doesn't handle expletives
329 322 .fi
330 323
331 324 .SH INCREMENTAL REVIEWS
332 325 When conducting multiple rounds of code review, it may be desirable to
333 326 generate a webrev which represents the delta between reviews. In this
334 327 case, set the parent workspace to the path to the old webrev:
335 328
336 329 .IP
337 330 .nf
338 331 \f(CW$ webrev -o ~/public_html/myreview-rd2/ \\
339 332 -p ~/public_html/myreview/
340 333 .fi
341 334
342 335 .SH ENVIRONMENT VARIABLES
343 336 The following environment variables allow for customization of \fBwebrev\fR:
344 337
345 338 .PP
346 339 \fBCDIFFCMD\fR and \fBUDIFFCMD\fR are used when generating Cdiffs and Udiffs
347 340 respectively; their default values are "diff -b -C 5" and "diff -b -U
348 341 5". To generate diffs with more (or less) than 5 lines of context or
349 342 with more (or less) strict whitespace handling, set one or both of
350 343 these variables in the user environment accordingly.
351 344
352 345 \fBWDIR\fR sets the output directory. It is functionally equivalent to
353 346 the \fI-o\fR option.
354 347
355 348 \fBWDIFF\fR specifies the command used to generate Wdiffs. Wdiff generates a
356 349 full unified context listing with line numbers where unchanged
357 350 sections of code may be expanded and collapsed. It also provides a
358 351 "split" feature that shows the same file in two HTML frames one above the
359 352 other. The default path for this script is
360 353 /ws/onnv-gate/public/bin/wdiff but WDIFF may be set to customize this
361 354 to use a more convenient location.
362 355
363 356 \fBWEBREV_TRASH_DIR\fR specifies alternative location of trash directory
364 357 for remote webrev deletion using the \fI-D\fR option. The directory is
365 358 relative to the top level directory of the default sftp/rsync directory tree.
366 359 The default value of this directory is ".trash".
367 360
368 361 .SH UPLOADING WEBREVS
369 362 A webrev can be uploaded to remote site using the -U option. To simply
370 363 generate new webrev and upload it to the default remote host use the following
371 364 command:
372 365 .IP
373 366 .nf
374 367 \f(CW$ webrev -U
375 368 .fi
376 369 .PP
377 370 This will generate the webrev to local directory named 'webrev' and upload it
378 371 to remote host with remote directory name equal to local workspace/repository
379 372 name. To change both local and remote directory name, -U can be combined with
380 373 -o option. The following command will store the webrev to local directory named
381 374 "foo.onnv" and upload it to the remote host with the same directory name:
382 375 .IP
383 376 .nf
384 377 \f(CW$ webrev -U -o $CODEMGR_WS/foo.onnv
385 378 .fi
386 379 .PP
387 380 If there is a need for manual change of the webrev before uploading,
388 381 -U can be combined with -n option so that first command will just generate
389 382 the webrev and the second command will upload it without generating it again:
390 383 .IP
391 384 .nf
392 385 \f(CW$ webrev
393 386 \f(CW$ webrev -n -U
394 387 .fi
395 388 .PP
396 389 For custom remote targets, -t option allows to specify all components:
397 390 .IP
398 391 .nf
399 392 \f(CW$ webrev -U -t \\
400 393 ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
401 394 .fi
402 395 .PP
403 396 If the remote path is specified as absolute, \fBwebrev\fR will assume all the
404 397 directories are already created. If the path is relative, \fBwebrev\fR will
405 398 try to create all needed directories. This only works with SCP/SFTP transport.
406 399 .PP
407 400 By default, rsync transport will use SSH for transferring the data to remote
408 401 site. To specify custom username, use entry in SSH client configuration file,
409 402 for example:
410 403 .IP
411 404 .nf
412 405 \f(CWHost cr.opensolaris.org
413 406 Hostname cr.opensolaris.org
414 407 User vkotal
415 408 .fi
416 409
417 410 .SH DELETING WEBREVS
418 411 When deleting a webrev directory on remote site which has a different name
419 412 than the basename of local repository it is necessary to specify the output
420 413 option:
421 414 .IP
422 415 .nf
423 416 \f(CW$ webrev -Do webrev-foo.onnv
424 417 .fi
425 418 .PP
426 419 Otherwise \fBwebrev\fR will attempt to remove remote directory with the same
427 420 name as basename of the local repository.
428 421 .PP
|
↓ open down ↓ |
269 lines elided |
↑ open up ↑ |
429 422 For the nested directory case it is necessary to specify the full target:
430 423 .IP
431 424 .nf
432 425 \f(CW$ webrev -D -t \\
433 426 ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
434 427 .fi
435 428 .PP
436 429 This will remove just the \fIbugfix.onnv\fR directory.
437 430
438 431 .SH SEE ALSO
439 -.BR hg "(1),"
440 432 .BR git "(1),"
441 433 .BR ssh_config "(4),"
442 434 .BR svn "(1),"
443 435 .BR which_scm "(1ONBLD)"
444 436
445 437 .SH ACKNOWLEDGEMENTS
446 438 Acknowledgements to Rob Thurlow, Mike Eisler, Lin Ling,
447 439 Rod Evans, Mike Kupfer, Greg Onufer, Glenn Skinner,
448 440 Oleg Larin, David Robinson, Matthew Cross, David L. Paktor,
449 441 Neal Gafter, John Beck, Darren Moffat, Norm Shulman, Bill Watson,
450 442 Pedro Rubio and Bill Shannon for valuable feedback and insight in
451 443 building webrev.
452 444
453 445 Have fun!
454 446 .br
455 447 .nf
456 448 Brent Callaghan 11/28/96
457 449 .fi
458 450
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX