WEBREV(1ONBLD) illumos Build Tools WEBREV(1ONBLD) NNAAMMEE webrev - Generate HTML codereview materials SSYYNNOOPPSSIISS wweebbrreevv [ _c_o_m_m_o_n_-_o_p_t_i_o_n_s ] wweebbrreevv [ _c_o_m_m_o_n_-_o_p_t_i_o_n_s ] _f_i_l_e_-_l_i_s_t_-_f_i_l_e | _- wweebbrreevv [ _c_o_m_m_o_n_-_o_p_t_i_o_n_s ] --ww _w_x_-_f_i_l_e DDEESSCCRRIIPPTTIIOONN wweebbrreevv builds a set of HTML files suitable for performing code review of source changes in a web browser. It supports Git and Subversion repositories. At its most basic, usage is: $ webrev In which case wweebbrreevv 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 _f_i_l_e _l_i_s_t may be specified. wweebbrreevv also attempts to deduce a _b_a_s_i_s _f_o_r _c_o_m_p_a_r_i_s_o_n (interchangeably called the _p_a_r_e_n_t, 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, wweebbrreevv creates a _w_e_b_r_e_v 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 $$wweebbrreevv__rroooott//rraaww__ffiilleess directory. To output the webrev somewhere other than the default location, use the _-_o _<_o_u_t_d_i_r_> option, or set the WWDDIIRR 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 _i_n_d_e_x 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 _w_e_b_r_e_v_-_i_n_f_o is present at the root of the workspace, it will be automatically included in the _i_n_d_e_x file. To include a different file, see the _-_i option. For each file in the file list, wweebbrreevv 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 SSCCMM IINNTTEERRAACCTTIIOONNSS wweebbrreevv attempts to interact with the source code management system currently in use. wweebbrreevv 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 wweebbrreevv will also attempt to auto-discover. In all cases, wweebbrreevv 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 wwss(1ONBLD) or bbllddeennvv(1ONBLD) commands, wweebbrreevv will use the CCOODDEEMMGGRR__PPAARREENNTT and CCOODDEEMMGGRR__WWSS environment variables to identify parent and child workspaces respectively. To manually specify the basis for comparison, use the -p option or specify the CCOODDEEMMGGRR__PPAARREENNTT variable in either the file list or the environment. DDiissccoovveerriinngg tthhee SSCCMM iinn uussee.. wweebbrreevv makes use of wwhhiicchh__ssccmm(1ONBLD) to determine the SCM in use for a given workspace. GGiitt In the case of Git wweebbrreevv will attempt to use the output from the ggiitt(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 ggiitt--rreevv--ppaarrssee(1) SSuubbvveerrssiioonn In the case of Subversion wweebbrreevv will attempt to use the output from the ssvvnn(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. CCRROOSSSS RREEFFEERREENNCCIINNGG After extracting comments (see FILE LIST below), wweebbrreevv 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. OOPPTTIIOONNSS --cc _r_e_v_i_s_i_o_n Generate webrev for single commit specified by _r_e_v_i_s_i_o_n (git only). --CC _p_r_i_o_r_i_t_y_-_f_i_l_e 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. --DD Delete remote webrev via SFTP. Default remote host is _c_r_._o_p_e_n_s_o_l_a_r_i_s_._o_r_g, 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. --hh _h_e_a_d_-_r_e_v_i_s_i_o_n Specify the explicit head to generate webrev from (git only). --II _i_n_f_o_r_m_a_t_i_o_n_-_f_i_l_e Use the specified file to seed the list of information tracking systems. --ii _i_n_c_l_u_d_e_-_f_i_l_e 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
tag and the markup should validate as XHTML 1.0 Transitional. --NN Suppress all comments from all output forms html, txt and pdf. --nn Do not generate webrev. Useful whenever only upload is needed. --OO Enable _O_p_e_n_S_o_l_a_r_i_s 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 _u_s_r_/_c_l_o_s_e_d are automatically elided from the review. --oo _o_u_t_p_u_t_-_d_i_r Place output from running the script in the directory specified. If specified, this option takes precedence over the WDIR environment variable. --pp _b_a_s_i_s_-_o_f_-_c_o_m_p_a_r_i_s_o_n Specify a basis of comparison meaningful for the SCM currently in use. See SCM INTERACTIONS and INCREMENTAL REVIEWS. --tt _t_a_r_g_e_t Upload target. Specified in form of URI identifier. For SCP/SFTP it is _s_s_h_:_/_/_u_s_e_r_@_r_e_m_o_t_e___h_o_s_t_:_r_e_m_o_t_e___d_i_r and for rsync it is _r_s_y_n_c_:_/_/_u_s_e_r_@_r_e_m_o_t_e___h_o_s_t_:_r_e_m_o_t_e___d_i_r. 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. --UU Upload the webrev. Default remote host is _c_r_._o_p_e_n_s_o_l_a_r_i_s_._o_r_g. Default transport is rsync. If it fails, fallback to SCP/SFTP transport is done. --ww _w_x_-_f_i_l_e 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 _w_x package. See FILE LIST, below. FFIILLEE LLIISSTT WWeebbrreevv needs to be told or to discover which files have changed in a given workspace. By default, wweebbrreevv will attempt to autodetect the list of changed files by first consulting wwxx(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. WWeebbrreevv FFoorrmmaatt 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. wwxx FFoorrmmaatt If the _-_w flag is specified then wweebbrreevv 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 IINNCCRREEMMEENNTTAALL RREEVVIIEEWWSS 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/ EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS The following environment variables allow for customization of wweebbrreevv: CCDDIIFFFFCCMMDD and UUDDIIFFFFCCMMDD 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. WWDDIIRR sets the output directory. It is functionally equivalent to the _-_o option. WWDDIIFFFF 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. WWEEBBRREEVV__TTRRAASSHH__DDIIRR 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". UUPPLLOOAADDIINNGG WWEEBBRREEVVSS 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, wweebbrreevv will assume all the directories are already created. If the path is relative, wweebbrreevv 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 DDEELLEETTIINNGG WWEEBBRREEVVSS 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 wweebbrreevv 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 _b_u_g_f_i_x_._o_n_n_v directory. SSEEEE AALLSSOO ggiitt(1), sssshh__ccoonnffiigg(4), ssvvnn(1), wwhhiicchh__ssccmm(1ONBLD) AACCKKNNOOWWLLEEDDGGEEMMEENNTTSS 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)