WEBREV(1ONBLD) illumos Build Tools WEBREV(1ONBLD)


NAME


webrev - Generate HTML codereview materials

SYNOPSIS


webrev [ common-options ]

webrev [ common-options ] file-list-file | -

webrev [ common-options ] -w wx-file


DESCRIPTION


webrev builds a set of HTML files suitable for performing code review of
source changes in a web browser. It supports Mercurial, Git and
Subversion repositories. At its most basic, usage is:
$ webrev

In which case webrev attempts to figure out the list of files for review.
If that fails, or if more control over the set of files is needed, a file
list may be specified. webrev also attempts to deduce a basis for
comparison (interchangeably called the parent, but see SCM INTERACTIONS
below). A basis for comparison is needed in order to determine the
differences introduced by the code changes under review.

By default, webrev creates a webrev directory in the workspace directory
that contains the generated HTML files, a generated PDF review, and a
patch representing the changes. It also places a copy of the file list
in that directory, and of both the old and new raw files in the
$webrev_root/raw_files directory. To output the webrev somewhere other
than the default location, use the -o <outdir> option, or set the WDIR
environment variable. For example:
$ webrev -o ~/public_html/myreview/

In the index file, each file is listed on a line with a link to the
relevant review materials. Comments for each change will be included
automatically. Cross references to bug (or other information) tracking
databases in the comments will become hyperlinks in the associated web
interface, according to the rules in CROSS REFERENCING below.

As a review aid, content may be added to the index file in two ways.
First, the author may manually edit the file (for example by including
text that explains the changes in front of the links for each file).
Note that if webrev is run again, manual edits will be lost. Second, if
a file named webrev-info is present at the root of the workspace, it will
be automatically included in the index file. To include a different
file, see the -i option.

For each file in the file list, webrev compares the file with the version
in the basis for comparison (i.e. the parent workspace) and generates a
variety of HTML renderings of the differences between the two files;
which of these renderings to use is largely a matter of personal
preference. Additional, webrev emits a patch, the old and new versions
of the file, and a "raw" copy of the file which is suitable for download.
For files which express differences, source is formatted according to the
following color coding:

unchanged : black
removed : brown
changed : blue
new : bold blue


SCM INTERACTIONS


webrev attempts to interact with the source code management system
currently in use. webrev needs to be able locate the code under review
(i.e. the workspace) and the basis for comparison (i.e. the parent). The
method for doing so depends upon the SCM in use, which webrev will also
attempt to auto-discover. In all cases, webrev must either discover the
list of files which have changed, or else this list must be manually
specified, either in "webrev file list" format or in "wx" format. See
FILE LIST for more details.

In all cases, if the user has activated the workspace with the ws(1ONBLD)
or bldenv(1ONBLD) commands, webrev will use the CODEMGR_PARENT and
CODEMGR_WS environment variables to identify parent and child workspaces
respectively. To manually specify the basis for comparison, use the -p
option or specify the CODEMGR_PARENT variable in either the file list or
the environment.


Discovering the SCM in use.
webrev makes use of which_scm(1ONBLD) to determine the SCM in use for a
given workspace.


Mercurial


In the case of Mercurial webrev will attempt to use the output from the
hg(1) "hg root" command to identify the workspace root, and the "hg path
default" command to identify the parent workspace.


Git


In the case of Git webrev will attempt to use the output from the git(1)
"git rev-parse --git-dir" command to identify the workspace root, and
will attempt to use the remote branch which the current branch is
tracking as the parent, if none is specified 'origin/master' will be
used.

The parent specified when using git is, in all cases, a git 'tree-ish'
and never an actual git repository, remote or otherwise. Anything
specifiable to git as a tree-ish should, similarly, be specifiable as a
parent for webrev. This includes branches, explicit revisions, reflog
entries, etc. See git-rev-parse(1)


Subversion


In the case of Subversion webrev will attempt to use the output from the
svn(1) "svn info" to find the workspace root and subversion repository
URL.

The file list will be created from the output of the "svn status"
command.


CROSS REFERENCING


After extracting comments (see FILE LIST below), webrev will translate
cross references into hyperlinks. By default, information about
available information tracking systems can be found in
/opt/onbld/etc/its.reg, and the specification of a local domain and
selection and prioritization of systems in /opt/onbld/etc/its.conf.
These file formats are self documenting. Also see the -I and -C options
below.

OPTIONS


-c revision
Generate webrev for single commit specified by revision (git
only).

-C priority-file
In addition to the system default and an optional user-supplied
~/.its.conf, use the specified file to specify a local domain
list and prioritize the list of information tracking systems to
be searched automatically when resolving cross references.

-D Delete remote webrev via SFTP. Default remote host is
cr.opensolaris.org, default remote directory for removal is the
same as workspace/repository basename. Remote target can be
overriden using -t option. If combined with -U the deletion
will be performed first. Also, if used together with -U and the
removal fails, no upload is done. Without -U option no webrev
will be generated, just like if -n option was used. The
deletion is done by moving the webrev to special directory in
user's home directory. It is expected that the remote host
periodically runs a script which deletes the contents of this
directory. See the ENVIRONMENT VARIABLES section for more
details about this directory.

-h head-revision
Specify the explicit head to generate webrev from (git only).

-I information-file
Use the specified file to seed the list of information tracking
systems.

-i include-file
Include the specified file into the index.html file which is
generated as part of the webrev. This allows a snippet of
XHTML to be added by the webrev author. User content is
contained by a <div> tag and the markup should validate as
XHTML 1.0 Transitional.

-N Suppress all comments from all output forms html, txt and pdf.

-n Do not generate webrev. Useful whenever only upload is needed.

-O Enable OpenSolaris mode: information tracking system hyperlinks
are generated using the EXTERNAL_URL field from the specified
its.reg entry, instead of the default INTERNAL_URL_domain
field, and sources which appear in usr/closed are automatically
elided from the review.

-o output-dir
Place output from running the script in the directory
specified. If specified, this option takes precedence over the
WDIR environment variable.

-p basis-of-comparison
Specify a basis of comparison meaningful for the SCM currently
in use. See SCM INTERACTIONS and INCREMENTAL REVIEWS.

-t target Upload target. Specified in form of URI identifier. For
SCP/SFTP it is ssh://user@remote_host:remote_dir and for rsync
it is rsync://user@remote_host:remote_dir. This option can
override the -o option if the URI is fully specified. The
target is relative to the top level directory of the default
sftp/rsync directory tree.

-U Upload the webrev. Default remote host is cr.opensolaris.org.
Default transport is rsync. If it fails, fallback to SCP/SFTP
transport is done.

-w wx-file
Extract the file list from the wx "active" file specified.
'wx' uses this mode when invoking webrev. The list is assumed
to be in the format expected by the wx package. See FILE LIST,
below.


FILE LIST


Webrev needs to be told or to discover which files have changed in a
given workspace. By default, webrev will attempt to autodetect the list
of changed files by first consulting wx(1). If this information is not
available, webrev tries to consult the SCM (Source Code Manager)
currently in use. If that fails, the user must intervene by specifying
either a file list or additional options specific to the SCM in use.


Webrev Format


A webrev formatted file list contains a list of all the files to be
included in the review with paths relative to the workspace directory,
e.g.

usr/src/uts/common/fs/nfs/nfs_subr.c
usr/src/uts/common/fs/nfs/nfs_export.c
usr/src/cmd/fs.d/nfs/mountd/mountd.c

Include the paths of any files added, deleted, or modified. You can keep
this list of files in the webrev directory that webrev creates in the
workspace directory (CODEMGR_WS).

If CODEMGR_WS is not set, it may be specified as an environment variable
within the file list, e.g.

CODEMGR_WS=/home/brent/myws
usr/src/uts/common/fs/nfs/nfs_subr.c
usr/src/uts/common/fs/nfs/nfs_export.c
usr/src/cmd/fs.d/nfs/mountd/mountd.c

To compare the workspace against one other than the parent (see also the
-p option), include a CODEMGR_PARENT line in the file list, like:

CODEMGR_WS=/home/brent/myws
CODEMGR_PARENT=/ws/onnv-gate
usr/src/uts/common/fs/nfs/nfs_subr.c
usr/src/uts/common/fs/nfs/nfs_export.c
usr/src/cmd/fs.d/nfs/mountd/mountd.c

Finally, run webrev with the name of the file containing the file list as
an argument, e.g.
$ webrev file.list

If "-" is supplied as the name of the file, then stdin will be used.


wx Format
If the -w flag is specified then webrev will assume the file list is in
the format expected by the "wx" package: pathname lines alternating with
SCCS comment lines separated by blank lines, e.g.

usr/src/uts/common/fs/nfs/nfs_subr.c

1206578 Fix spelling error in comment

usr/src/uts/common/fs/nfs/nfs_export.c

4039272 cstyle fixes

usr/src/cmd/fs.d/nfs/mountd/mountd.c

1927634 mountd daemon doesn't handle expletives


INCREMENTAL REVIEWS


When conducting multiple rounds of code review, it may be desirable to
generate a webrev which represents the delta between reviews. In this
case, set the parent workspace to the path to the old webrev:


$ webrev -o ~/public_html/myreview-rd2/ \
-p ~/public_html/myreview/


ENVIRONMENT VARIABLES


The following environment variables allow for customization of webrev:


CDIFFCMD and UDIFFCMD are used when generating Cdiffs and Udiffs
respectively; their default values are "diff -b -C 5" and "diff -b -U 5".
To generate diffs with more (or less) than 5 lines of context or with
more (or less) strict whitespace handling, set one or both of these
variables in the user environment accordingly.

WDIR sets the output directory. It is functionally equivalent to the -o
option.

WDIFF specifies the command used to generate Wdiffs. Wdiff generates a
full unified context listing with line numbers where unchanged sections
of code may be expanded and collapsed. It also provides a "split"
feature that shows the same file in two HTML frames one above the other.
The default path for this script is /ws/onnv-gate/public/bin/wdiff but
WDIFF may be set to customize this to use a more convenient location.

WEBREV_TRASH_DIR specifies alternative location of trash directory for
remote webrev deletion using the -D option. The directory is relative to
the top level directory of the default sftp/rsync directory tree. The
default value of this directory is ".trash".


UPLOADING WEBREVS


A webrev can be uploaded to remote site using the -U option. To simply
generate new webrev and upload it to the default remote host use the
following command:

$ webrev -U

This will generate the webrev to local directory named 'webrev' and
upload it to remote host with remote directory name equal to local
workspace/repository name. To change both local and remote directory
name, -U can be combined with -o option. The following command will store
the webrev to local directory named "foo.onnv" and upload it to the
remote host with the same directory name:

$ webrev -U -o $CODEMGR_WS/foo.onnv

If there is a need for manual change of the webrev before uploading, -U
can be combined with -n option so that first command will just generate
the webrev and the second command will upload it without generating it
again:

$ webrev
$ webrev -n -U

For custom remote targets, -t option allows to specify all components:

$ webrev -U -t \
ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv

If the remote path is specified as absolute, webrev will assume all the
directories are already created. If the path is relative, webrev will try
to create all needed directories. This only works with SCP/SFTP
transport.

By default, rsync transport will use SSH for transferring the data to
remote site. To specify custom username, use entry in SSH client
configuration file, for example:

Host cr.opensolaris.org
Hostname cr.opensolaris.org
User vkotal


DELETING WEBREVS


When deleting a webrev directory on remote site which has a different
name than the basename of local repository it is necessary to specify the
output option:

$ webrev -Do webrev-foo.onnv

Otherwise webrev will attempt to remove remote directory with the same
name as basename of the local repository.

For the nested directory case it is necessary to specify the full target:

$ webrev -D -t \
ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv

This will remove just the bugfix.onnv directory.


SEE ALSO


hg(1), git(1), ssh_config(4), svn(1), which_scm(1ONBLD)


ACKNOWLEDGEMENTS


Acknowledgements to Rob Thurlow, Mike Eisler, Lin Ling, Rod Evans, Mike
Kupfer, Greg Onufer, Glenn Skinner, Oleg Larin, David Robinson, Matthew
Cross, David L. Paktor, Neal Gafter, John Beck, Darren Moffat, Norm
Shulman, Bill Watson, Pedro Rubio and Bill Shannon for valuable feedback
and insight in building webrev.

Have fun!
Brent Callaghan 11/28/96


March 27, 2016 WEBREV(1ONBLD)