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)