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