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