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