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