6857 webrev: add -c and -h options to specify "head" revision

[unleashed.git] / usr / src / tools / scripts / webrev.1onbld

.\"
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\"
.\" Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
.\" Use is subject to license terms.
.\"
.\"
.TH WEBREV 1ONBLD "Mar 27, 2016"
.SH NAME
webrev \- Generate HTML codereview materials
.SH SYNOPSIS
.B webrev
[
.I common-options
]

.B webrev
[
.I common-options
]
.I file-list-file
|
.I -

.B webrev
[
.I common-options
]
.B -w
.I wx-file

.SH DESCRIPTION
.B 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:
.nf
        $ webrev
.fi

In which case \fBwebrev\fR 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 \fIfile list\fR may be specified.
\fBwebrev\fR also attempts to deduce a
.I basis for comparison
(interchangeably called the \fIparent\fR, 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, \fBwebrev\fR creates a \fIwebrev\fR 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 \fB$webrev_root/raw_files\fR directory.
To output the webrev somewhere other than the default location, use the
\fI-o <outdir>\fR option, or set the \fBWDIR\fR environment variable.
For example:
.nf
        $ webrev -o ~/public_html/myreview/
.fi
.PP
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 \fIindex\fR 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 \fIwebrev-info\fR is present at the root of the workspace,
it will be automatically included in the \fIindex\fR file.  To include a
different file, see the \fI-i\fR option.

For each file in the file list, \fBwebrev\fR 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:
.IP
.nf
     unchanged : black
       removed : brown
       changed : blue
           new : bold blue
.fi

.SH SCM INTERACTIONS
.PP
.B webrev
attempts to interact with the source code management system currently in use.
.B 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
.B webrev
will also attempt to auto-discover.  In all cases,
.B 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.
.PP
In all cases, if the user has activated the workspace with the
.BR ws (1ONBLD)
or
.BR bldenv (1ONBLD)
commands, \fBwebrev\fR will use the \fBCODEMGR_PARENT\fR and
\fBCODEMGR_WS\fR environment variables to identify parent and child
workspaces respectively.
To manually specify the basis for comparison, use the -p option or
specify the \fBCODEMGR_PARENT\fR variable in either the file list or
the environment.

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

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

.SS Git
In the case of Git \fBwebrev\fR will attempt to use the output from the
.BR 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
.BR git-rev-parse (1)

.SS Subversion
In the case of Subversion \fBwebrev\fR will attempt to use the output
from the
.BR svn (1)
"svn info" to find the workspace root and subversion repository URL.
.PP
The file list will be created from the output of the "svn status" command.

.SH CROSS REFERENCING
.PP
After extracting comments (see FILE LIST below),
.B 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.
.SH OPTIONS
.TP 10
.BI "-c " revision
Generate webrev for single commit specified by \fIrevision\fR (git only).
.TP 10
.BI "-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.
.TP 10
.BI "-D"
Delete remote webrev via SFTP. Default remote host is \fIcr.opensolaris.org\fR,
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.
.TP 10
.BI "-h " head-revision
Specify the explicit head to generate webrev from (git only).
.TP 10
.BI "-I " information-file
Use the specified file to seed the list of information tracking systems.
.TP 10
.BI "-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.
.TP 10
.BI "-N"
Suppress all comments from all output forms html, txt and pdf.
.TP 10
.BI "-n"
Do not generate webrev. Useful whenever only upload is needed.
.TP 10
.B -O
Enable \fIOpenSolaris\fR 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
\fIusr/closed\fR are automatically elided from the review.
.TP 10
.BI "-o " output-dir
Place output from running the script in the directory specified.  If
specified, this option takes precedence over the WDIR environment variable.
.TP 10
.BI "-p " basis-of-comparison
Specify a basis of comparison meaningful for the SCM currently in use.
See SCM INTERACTIONS and INCREMENTAL REVIEWS.
.TP 10
.BI "-t " target
Upload target. Specified in form of URI identifier. For SCP/SFTP it is
\fIssh://user@remote_host:remote_dir\fR and for rsync it is
\fIrsync://user@remote_host:remote_dir\fR. 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.
.TP 10
.BI "-U"
Upload the webrev. Default remote host is \fIcr.opensolaris.org\fR.
Default transport is rsync. If it fails, fallback to SCP/SFTP transport
is done.
.TP 10
.BI "-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 \fIwx\fR package.  See FILE LIST, below.

.SH FILE LIST
.PP
.B Webrev
needs to be told or to discover which files have changed in a
given workspace.  By default,
.B webrev
will attempt to autodetect the
list of changed files by first consulting
.BR 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.

.SS 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.
.IP
.nf
\f(CWusr/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
.fi
.PP
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.
.IP
.nf
\f(CWCODEMGR_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
.fi
.PP
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:
.IP
.nf
\f(CWCODEMGR_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
.fi
.PP
Finally, run webrev with the name of the file containing the file list as an
argument, e.g.
.nf
        $ webrev file.list
.fi
.PP
If "-" is supplied as the name of the file, then stdin will be used.

.SS wx Format
If the \fI-w\fR flag is specified then \fBwebrev\fR
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.
.IP
.nf
\f(CWusr/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
.fi

.SH 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:

.IP
.nf
\f(CW$ webrev -o ~/public_html/myreview-rd2/ \\
         -p ~/public_html/myreview/
.fi

.SH ENVIRONMENT VARIABLES
The following environment variables allow for customization of \fBwebrev\fR:

.PP
\fBCDIFFCMD\fR and \fBUDIFFCMD\fR 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.

\fBWDIR\fR sets the output directory.  It is functionally equivalent to
the \fI-o\fR option.

\fBWDIFF\fR 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.

\fBWEBREV_TRASH_DIR\fR specifies alternative location of trash directory
for remote webrev deletion using the \fI-D\fR 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".

.SH 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:
.IP
.nf
\f(CW$ webrev -U
.fi
.PP
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:
.IP
.nf
\f(CW$ webrev -U -o $CODEMGR_WS/foo.onnv
.fi
.PP
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:
.IP
.nf
\f(CW$ webrev
\f(CW$ webrev -n -U
.fi
.PP
For custom remote targets, -t option allows to specify all components:
.IP
.nf
\f(CW$ webrev -U -t \\
        ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
.fi
.PP
If the remote path is specified as absolute, \fBwebrev\fR will assume all the
directories are already created. If the path is relative, \fBwebrev\fR will
try to create all needed directories. This only works with SCP/SFTP transport.
.PP
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:
.IP
.nf
\f(CWHost cr.opensolaris.org
  Hostname cr.opensolaris.org
  User vkotal
.fi

.SH 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:
.IP
.nf
\f(CW$ webrev -Do webrev-foo.onnv
.fi
.PP
Otherwise \fBwebrev\fR will attempt to remove remote directory with the same
name as basename of the local repository.
.PP
For the nested directory case it is necessary to specify the full target:
.IP
.nf
\f(CW$ webrev -D -t \\
        ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
.fi
.PP
This will remove just the \fIbugfix.onnv\fR directory.

.SH SEE ALSO
.BR hg "(1),"
.BR git "(1),"
.BR ssh_config "(4),"
.BR svn "(1),"
.BR which_scm "(1ONBLD)"

.SH 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!
.br
.nf
                Brent Callaghan  11/28/96
.fi