3810 remove support for teamware from webrev

          --- old/usr/src/tools/scripts/webrev.1
          +++ new/usr/src/tools/scripts/webrev.1

   1    1  .\"
   2    2  .\" CDDL HEADER START
   3    3  .\"
   4    4  .\" The contents of this file are subject to the terms of the
   5    5  .\" Common Development and Distribution License (the "License").
   6    6  .\" You may not use this file except in compliance with the License.
   7    7  .\"
   8    8  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9    9  .\" or http://www.opensolaris.org/os/licensing.
  10   10  .\" See the License for the specific language governing permissions
  11   11  .\" and limitations under the License.
  12   12  .\"
  13   13  .\" When distributing Covered Code, include this CDDL HEADER in each
  14   14  .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15   15  .\" If applicable, add the following below this CDDL HEADER, with the
  16   16  .\" fields enclosed by brackets "[]" replaced with your own identifying
  17   17  .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18   18  .\"
  19   19  .\" CDDL HEADER END
  20   20  .\"
  21   21  .\" Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
  22   22  .\" Use is subject to license terms.
  23   23  .\"
  24   24  .\"
  25   25  .TH webrev 1 "6 Dec 2010"
  26   26  .SH NAME
  27   27  webrev \- Generate HTML codereview materials
  28   28  .SH SYNOPSIS
  29   29  .B webrev
  30   30  [
  31   31  .I common-options
  32   32  ]
  33   33  
  34   34  .B webrev
  35   35  [
  36   36  .I common-options
  37   37  ]
  38   38  .I file-list-file

  39   39  |
  40   40  .I -
  41   41  
  42   42  .B webrev
  43   43  [
  44   44  .I common-options
  45   45  ]
  46   46  .B -w
  47   47  .I wx-file
  48   48  
  49      -.B webrev 
  50      -[
  51      -.I common-options
  52      -]
  53      -.B -l
  54      -.I arguments to 'putback'
  55      -
  56      -See OPTIONS for common-options.  
  57      -Note that the -l option is only applicable to TeamWare workspaces.
  58      -
  59   49  .SH DESCRIPTION
  60   50  .B webrev
  61   51  builds a set of HTML files suitable for performing code review of
  62   52  source changes in a web browser.
  63      -It supports Mercurial, Git, Subversion and Teamware repositories.
       53 +It supports Mercurial, Git and Subversion repositories.
  64   54  At its most basic, usage is:
  65   55  .nf
  66   56          $ webrev
  67   57  .fi
  68   58  
  69   59  In which case \fBwebrev\fR attempts to figure out the list of files
  70      -for review (note that when using Teamware \fBputback\fR, this may take
  71      -a long time; see the -l option).  If that fails, or if more control
       60 +for review.  If that fails, or if more control
  72   61  over the set of files is needed, a \fIfile list\fR may be specified.
  73   62  \fBwebrev\fR also attempts to deduce a
  74   63  .I basis for comparison
  75   64  (interchangeably called the \fIparent\fR, but see SCM INTERACTIONS below).
  76   65  A basis for comparison is needed in order to determine the differences
  77   66  introduced by the code changes under review.
  78   67  
  79   68  By default, \fBwebrev\fR creates a \fIwebrev\fR directory in the
  80   69  workspace directory that contains the generated HTML files, a generated
  81   70  PDF review, and a patch representing the changes.  It also places a

  82   71  copy of the file list in that directory, and of both the old and new
  83   72  raw files in the \fB$webrev_root/raw_files\fR directory.
  84   73  To output the webrev somewhere other than the default location, use the
  85   74  \fI-o <outdir>\fR option, or set the \fBWDIR\fR environment variable.
  86   75  For example:
  87   76  .nf
  88   77          $ webrev -o ~/public_html/myreview/
  89   78  .fi
  90   79  .PP
  91   80  In the index file, each file is listed on a line with a link to the
  92   81  relevant review materials.  Comments for each change will be included
  93   82  automatically.  Cross references to bug (or other information) tracking
  94   83  databases in the comments will become hyperlinks in the associated web
  95   84  interface, according to the rules in CROSS REFERENCING below.
  96   85  
  97   86  As a review aid, content may be added to the \fIindex\fR file in two ways.
  98   87  First, the author may manually edit the file (for example by including
  99   88  text that explains the changes in front of the links for each file).
 100   89  Note that if webrev is run again, manual edits will be lost.  Second,
 101   90  if a file named \fIwebrev-info\fR is present at the root of the workspace,
 102   91  it will be automatically included in the \fIindex\fR file.  To include a
 103   92  different file, see the \fI-i\fR option.
 104   93  
 105   94  For each file in the file list, \fBwebrev\fR compares the file with the
 106   95  version in the basis for comparison (i.e. the parent workspace) and
 107   96  generates a variety of HTML renderings of the differences between
 108   97  the two files; which of these renderings to use is largely a matter
 109   98  of personal preference.  Additional, webrev emits a patch, the old
 110   99  and new versions of the file, and a "raw" copy of the file which is
 111  100  suitable for download.  For files which express differences, source
 112  101  is formatted according to the following color coding:
 113  102  .IP
 114  103  .nf
 115  104       unchanged : black
 116  105         removed : brown
 117  106         changed : blue
 118  107             new : bold blue
 119  108  .fi
 120  109  
 121  110  .SH SCM INTERACTIONS
 122  111  .PP
 123  112  .B webrev
 124  113  attempts to interact with the source code management system currently in use.  
 125  114  .B webrev
 126  115  needs to be able locate the code under review (i.e. the workspace) and
 127  116  the basis for comparison (i.e. the parent).  The method for doing so
 128  117  depends upon the SCM in use, which
 129  118  .B webrev
 130  119  will also attempt to auto-discover.  In all cases,
 131  120  .B webrev
 132  121  must either discover the list of files which have changed, or else this list
 133  122  must be manually specified, either in "webrev file list" format or in "wx"
 134  123  format.
 135  124  See FILE LIST for more details.
 136  125  .PP
 137  126  In all cases, if the user has activated the workspace with the
 138  127  .BR ws (1)
 139  128  or
 140  129  .BR bldenv (1)
 141  130  commands, \fBwebrev\fR will use the \fBCODEMGR_PARENT\fR and
 142  131  \fBCODEMGR_WS\fR environment variables to identify parent and child
 143  132  workspaces respectively.

 144  133  To manually specify the basis for comparison, use the -p option or
 145  134  specify the \fBCODEMGR_PARENT\fR variable in either the file list or
 146  135  the environment.
 147  136  
 148  137  .SS Discovering the SCM in use.
 149  138  .B webrev
 150  139  makes use of
 151  140  .BR which_scm (1)
 152  141  to determine the SCM in use for a given workspace.
 153  142  
 154      -.SS TeamWare
 155      -In the case of TeamWare \fBwebrev\fR will use the output of "workspace
 156      -name" to discover the workspace root, if not otherwise specified.
 157      -.PP
 158      -\fBwebrev\fR will attempt to use a 
 159      -.BR wx (1) 
 160      -active list in
 161      -\fBCODEMGR_WS/wx/active\fR.
 162      -To direct \fBwebrev\fR to determine the file list from the output of
 163      -.BR putback "(1),"
 164      -use the -l option.  (Note that \fBwebrev\fR may also elect to use
 165      -\fBputback\fR if it cannot determine the file list from
 166      -.BR wx "(1))."
 167      -The -l option indicates that subsequent arguments should be
 168      -treated as arguments to
 169      -.BR putback "(1)."
 170      -This can be used to prune the set of files which putback examines,
 171      -or to reference a teamware flp (file list program).
 172      -
 173  143  .SS Mercurial
 174  144  In the case of Mercurial \fBwebrev\fR will attempt to use the output
 175  145  from the
 176  146  .BR hg (1)
 177  147  "hg root" command to identify the workspace root, and the
 178  148  "hg path default" command to identify the parent workspace.
 179  149  
 180  150  .SS Git
 181  151  In the case of Git \fBwebrev\fR will attempt to use the output from the
 182  152  .BR git (1)

 183  153  "git rev-parse --git-dir" command to identify the workspace root, and will
 184  154  attempt to use the remote branch which the current branch is tracking as the
 185  155  parent, if none is specified 'origin/master' will be used.
 186  156  
 187  157  The parent specified when using git is, in all cases, a git 'tree-ish' and
 188  158  never an actual git repository, remote or otherwise.  Anything specifiable to
 189  159  git as a tree-ish should, similarly, be specifiable as a parent for webrev.
 190  160  This includes branches, explicit revisions, reflog entries, etc. See
 191  161  .BR git-rev-parse (1)
 192  162  
 193  163  .SS Subversion
 194  164  In the case of Subversion \fBwebrev\fR will attempt to use the output
 195  165  from the
 196  166  .BR svn (1)
 197  167  "svn info" to find the workspace root and subversion repository URL.
 198  168  .PP
 199  169  The file list will be created from the output of the "svn status" command.
 200  170  
 201  171  .SH CROSS REFERENCING
 202  172  .PP
 203  173  After extracting comments (see FILE LIST below),
 204  174  .B webrev
 205  175  will translate cross references into hyperlinks.  By default, information
 206  176  about available information tracking systems can be found in
 207  177  /opt/onbld/etc/its.reg, and the specification of a local domain and
 208  178  selection and prioritization of systems
 209  179  in /opt/onbld/etc/its.conf.  These file formats are self documenting.  Also
 210  180  see the -I and -C options below.
 211  181  .SH OPTIONS
 212  182  .TP 10
 213  183  .BI "-C " priority-file
 214  184  In addition to the system default and an optional user-supplied ~/.its.conf,
 215  185  use the specified file to specify a local domain list and prioritize the list
 216  186  of information tracking systems to be searched automatically when resolving cross
 217  187  references.
 218  188  .TP 10
 219  189  .BI "-D"
 220  190  Delete remote webrev via SFTP. Default remote host is \fIcr.opensolaris.org\fR,
 221  191  default remote directory for removal is the same as workspace/repository
 222  192  basename. Remote target can be overriden using -t option. If combined with
 223  193  -U the deletion will be performed first. Also, if used together with -U
 224  194  and the removal fails, no upload is done. Without -U option no webrev will
 225  195  be generated, just like if -n option was used. The deletion is done by
 226  196  moving the webrev to special directory in user's home directory. It is
 227  197  expected that the remote host periodically runs a script which deletes
 228  198  the contents of this directory. See the ENVIRONMENT VARIABLES section for
 229  199  more details about this directory.

 230  200  .TP 10
 231  201  .BI "-I " information-file
 232  202  Use the specified file to seed the list of information tracking systems.
 233  203  .TP 10
 234  204  .BI "-i " include-file
 235  205  Include the specified file into the index.html file which is generated
 236  206  as part of the webrev.  This allows a snippet of XHTML to be added by
 237  207  the webrev author. User content is contained by a <div> tag and
 238  208  the markup should validate as XHTML 1.0 Transitional.
 239  209  .TP 10
 240      -.BI "-l " putback-args
 241      -Extract the file list from the output of 
 242      -.I putback -n.
 243      -Any arguments supplied will be passed to 
 244      -.BR putback "(1)."
 245      -See SCM INTERACTIONS.  For more information about file
 246      -lists, see FILE LIST.  This argument should appear last.
 247      -.TP 10
 248  210  .BI "-N"
 249  211  Suppress all comments from all output forms html, txt and pdf.
 250  212  .TP 10
 251  213  .BI "-n"
 252  214  Do not generate webrev. Useful whenever only upload is needed.
 253  215  .TP 10
 254  216  .B -O
 255  217  Enable \fIOpenSolaris\fR mode: information tracking system hyperlinks
 256  218  are generated using the EXTERNAL_URL field from the specified its.reg entry,
 257  219  instead of the default INTERNAL_URL_domain field, and sources which appear in

 258  220  \fIusr/closed\fR are automatically elided from the review.
 259  221  .TP 10
 260  222  .BI "-o " output-dir
 261  223  Place output from running the script in the directory specified.  If
 262  224  specified, this option takes precedence over the WDIR environment variable.
 263  225  .TP 10
 264  226  .BI "-p " basis-of-comparison
 265  227  Specify a basis of comparison meaningful for the SCM currently in use.
 266  228  See SCM INTERACTIONS and INCREMENTAL REVIEWS.
 267  229  .TP 10
 268  230  .BI "-t " target
 269  231  Upload target. Specified in form of URI identifier. For SCP/SFTP it is
 270  232  \fIssh://user@remote_host:remote_dir\fR and for rsync it is
 271  233  \fIrsync://user@remote_host:remote_dir\fR. This option can override the
 272  234  -o option if the URI is fully specified. The target is relative to
 273  235  the top level directory of the default sftp/rsync directory tree.
 274  236  .TP 10
 275  237  .BI "-U"
 276  238  Upload the webrev. Default remote host is \fIcr.opensolaris.org\fR.
 277  239  Default transport is rsync. If it fails, fallback to SCP/SFTP transport
 278  240  is done.
 279  241  .TP 10
 280  242  .BI "-w " wx-file
 281  243  Extract the file list from the wx "active" file specified.  'wx' uses
 282  244  this mode when invoking webrev.  The list is assumed to be in the
 283  245  format expected by the \fIwx\fR package.  See FILE LIST, below.
 284  246  
 285  247  .SH FILE LIST
 286  248  .PP
 287  249  .B Webrev
 288  250  needs to be told or to discover which files have changed in a
 289  251  given workspace.  By default,
 290  252  .B webrev
 291  253  will attempt to autodetect the
 292  254  list of changed files by first consulting 
 293  255  .BR wx "(1)."
 294  256  If this information is not available, webrev tries to consult the SCM (Source
 295  257  Code Manager) currently in use.  If that fails, the user must intervene by
 296  258  specifying either a file list or additional options specific to the SCM in use.
 297  259  
 298  260  .SS Webrev Format
 299  261  A webrev formatted file list contains a list of all the files to
 300  262  be included in the review with paths relative to the workspace
 301  263  directory, e.g.
 302  264  .IP
 303  265  .nf
 304  266  \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c
 305  267  usr/src/uts/common/fs/nfs/nfs_export.c
 306  268  usr/src/cmd/fs.d/nfs/mountd/mountd.c
 307  269  .fi
 308  270  .PP
 309  271  Include the paths of any files added, deleted, or modified.
 310  272  You can keep this list of files in the webrev directory
 311  273  that webrev creates in the workspace directory
 312  274  (CODEMGR_WS).
 313  275  
 314  276  If CODEMGR_WS is not set, it may be specified as an environment variable
 315  277  within the file list, e.g.
 316  278  .IP
 317  279  .nf
 318  280  \f(CWCODEMGR_WS=/home/brent/myws
 319  281  usr/src/uts/common/fs/nfs/nfs_subr.c
 320  282  usr/src/uts/common/fs/nfs/nfs_export.c
 321  283  usr/src/cmd/fs.d/nfs/mountd/mountd.c
 322  284  .fi
 323  285  .PP
 324  286  To compare the workspace against one other than the parent (see also
 325  287  the -p option), include a CODEMGR_PARENT line in the file list, like:
 326  288  .IP
 327  289  .nf
 328  290  \f(CWCODEMGR_WS=/home/brent/myws
 329  291  CODEMGR_PARENT=/ws/onnv-gate
 330  292  usr/src/uts/common/fs/nfs/nfs_subr.c
 331  293  usr/src/uts/common/fs/nfs/nfs_export.c
 332  294  usr/src/cmd/fs.d/nfs/mountd/mountd.c
 333  295  .fi
 334  296  .PP
 335  297  Finally, run webrev with the name of the file containing the file list as an
 336  298  argument, e.g.
 337  299  .nf
 338  300          $ webrev file.list
 339  301  .fi
 340  302  .PP
 341  303  If "-" is supplied as the name of the file, then stdin will be used.
 342  304  
 343  305  .SS wx Format
 344  306  If the \fI-w\fR flag is specified then \fBwebrev\fR
 345  307  will assume the file list is in the format expected by the "wx" package:
 346  308  pathname lines alternating with SCCS comment lines separated by blank
 347  309  lines, e.g.
 348  310  .IP
 349  311  .nf
 350  312  \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c
 351  313  
 352  314  1206578 Fix spelling error in comment
 353  315  
 354  316  usr/src/uts/common/fs/nfs/nfs_export.c
 355  317  
 356  318  4039272 cstyle fixes
 357  319  
 358  320  usr/src/cmd/fs.d/nfs/mountd/mountd.c
 359  321  
 360  322  1927634 mountd daemon doesn't handle expletives
 361  323  .fi
 362  324  
 363  325  .SH INCREMENTAL REVIEWS
 364  326  When conducting multiple rounds of code review, it may be desirable to
 365  327  generate a webrev which represents the delta between reviews.  In this
 366  328  case, set the parent workspace to the path to the old webrev:
 367  329  
 368  330  .IP
 369  331  .nf
 370  332  \f(CW$ webrev -o ~/public_html/myreview-rd2/ \\
 371  333           -p ~/public_html/myreview/
 372  334  .fi
 373  335  
 374  336  .SH ENVIRONMENT VARIABLES
 375  337  The following environment variables allow for customization of \fBwebrev\fR:
 376  338  
 377  339  .PP
 378  340  \fBCDIFFCMD\fR and \fBUDIFFCMD\fR are used when generating Cdiffs and Udiffs
 379  341  respectively; their default values are "diff -b -C 5" and "diff -b -U
 380  342  5".  To generate diffs with more (or less) than 5 lines of context or
 381  343  with more (or less) strict whitespace handling, set one or both of
 382  344  these variables in the user environment accordingly.
 383  345  
 384  346  \fBWDIR\fR sets the output directory.  It is functionally equivalent to
 385  347  the \fI-o\fR option.
 386  348  
 387  349  \fBWDIFF\fR specifies the command used to generate Wdiffs. Wdiff generates a
 388  350  full unified context listing with line numbers where unchanged
 389  351  sections of code may be expanded and collapsed.  It also provides a
 390  352  "split" feature that shows the same file in two HTML frames one above the
 391  353  other.  The default path for this script is
 392  354  /ws/onnv-gate/public/bin/wdiff but WDIFF may be set to customize this
 393  355  to use a more convenient location.
 394  356  
 395  357  \fBWEBREV_TRASH_DIR\fR specifies alternative location of trash directory
 396  358  for remote webrev deletion using the \fI-D\fR option. The directory is
 397  359  relative to the top level directory of the default sftp/rsync directory tree.
 398  360  The default value of this directory is ".trash".
 399  361  
 400  362  .SH UPLOADING WEBREVS
 401  363  A webrev can be uploaded to remote site using the -U option. To simply
 402  364  generate new webrev and upload it to the default remote host use the following
 403  365  command:
 404  366  .IP
 405  367  .nf
 406  368  \f(CW$ webrev -U
 407  369  .fi
 408  370  .PP
 409  371  This will generate the webrev to local directory named 'webrev' and upload it
 410  372  to remote host with remote directory name equal to local workspace/repository
 411  373  name. To change both local and remote directory name, -U can be combined with
 412  374  -o option. The following command will store the webrev to local directory named
 413  375  "foo.onnv" and upload it to the remote host with the same directory name:
 414  376  .IP
 415  377  .nf
 416  378  \f(CW$ webrev -U -o $CODEMGR_WS/foo.onnv
 417  379  .fi
 418  380  .PP
 419  381  If there is a need for manual change of the webrev before uploading,
 420  382  -U can be combined with -n option so that first command will just generate
 421  383  the webrev and the second command will upload it without generating it again:
 422  384  .IP
 423  385  .nf
 424  386  \f(CW$ webrev
 425  387  \f(CW$ webrev -n -U
 426  388  .fi
 427  389  .PP
 428  390  For custom remote targets, -t option allows to specify all components:
 429  391  .IP
 430  392  .nf
 431  393  \f(CW$ webrev -U -t \\
 432  394          ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
 433  395  .fi
 434  396  .PP
 435  397  If the remote path is specified as absolute, \fBwebrev\fR will assume all the
 436  398  directories are already created. If the path is relative, \fBwebrev\fR will
 437  399  try to create all needed directories. This only works with SCP/SFTP transport.
 438  400  .PP
 439  401  By default, rsync transport will use SSH for transferring the data to remote
 440  402  site. To specify custom username, use entry in SSH client configuration file,
 441  403  for example:
 442  404  .IP
 443  405  .nf
 444  406  \f(CWHost cr.opensolaris.org
 445  407    Hostname cr.opensolaris.org
 446  408    User vkotal
 447  409  .fi
 448  410  
 449  411  .SH DELETING WEBREVS
 450  412  When deleting a webrev directory on remote site which has a different name
 451  413  than the basename of local repository it is necessary to specify the output
 452  414  option:
 453  415  .IP
 454  416  .nf
 455  417  \f(CW$ webrev -Do webrev-foo.onnv
 456  418  .fi
 457  419  .PP
 458  420  Otherwise \fBwebrev\fR will attempt to remove remote directory with the same
 459  421  name as basename of the local repository.
 460  422  .PP

 461  423  For the nested directory case it is necessary to specify the full target:
 462  424  .IP
 463  425  .nf
 464  426  \f(CW$ webrev -D -t \\
 465  427          ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
 466  428  .fi
 467  429  .PP
 468  430  This will remove just the \fIbugfix.onnv\fR directory.
 469  431  
 470  432  .SH SEE ALSO
 471      -.BR putback "(1),"
 472  433  .BR workspace "(1),"
 473  434  .BR hg "(1),"
 474  435  .BR git "(1),"
 475  436  .BR ssh_config "(4),"
 476  437  .BR svn "(1),"
 477  438  .BR which_scm "(1)"
 478  439  
 479  440  .SH ACKNOWLEDGEMENTS
 480  441  Acknowledgements to Rob Thurlow, Mike Eisler, Lin Ling,
 481  442  Rod Evans, Mike Kupfer, Greg Onufer, Glenn Skinner,
 482  443  Oleg Larin, David Robinson, Matthew Cross, David L. Paktor,
 483  444  Neal Gafter, John Beck, Darren Moffat, Norm Shulman, Bill Watson,
 484  445  Pedro Rubio and Bill Shannon for valuable feedback and insight in
 485  446  building webrev.
 486  447  
 487  448  Have fun!
 488  449  .br
 489  450                  Brent Callaghan  11/28/96
 490  451  
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX