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