Print this page
6205 onbld manuals should be declared as 1onbld
Reviewed by: Dan McDonald <danmcd@omniti.com>
Reviewed by: Josef Sipek <jeffpc@josefsipek.net>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/scripts/webrev.1.man.txt
+++ new/usr/src/tools/scripts/webrev.1onbld.man.txt
1 -webrev(1) User Commands webrev(1)
1 +webrev(1ONBLD) illumos Build Tools webrev(1ONBLD)
2 2
3 3
4 4
5 5 NAME
6 6 webrev - Generate HTML codereview materials
7 7
8 8 SYNOPSIS
9 9 webrev [ common-options ]
10 10
11 11 webrev [ common-options ] file-list-file | -
12 12
13 13 webrev [ common-options ] -w wx-file
14 14
15 15
16 16 DESCRIPTION
17 17 webrev builds a set of HTML files suitable for performing code review
18 18 of source changes in a web browser. It supports Mercurial, Git and
19 19 Subversion repositories. At its most basic, usage is:
20 20 $ webrev
21 21
22 22 In which case webrev attempts to figure out the list of files for
23 23 review. If that fails, or if more control over the set of files is
24 24 needed, a file list may be specified. webrev also attempts to deduce a
25 25 basis for comparison (interchangeably called the parent, but see SCM
26 26 INTERACTIONS below). A basis for comparison is needed in order to
27 27 determine the differences introduced by the code changes under review.
28 28
29 29 By default, webrev creates a webrev directory in the workspace
30 30 directory that contains the generated HTML files, a generated PDF
31 31 review, and a patch representing the changes. It also places a copy of
32 32 the file list in that directory, and of both the old and new raw files
33 33 in the $webrev_root/raw_files directory. To output the webrev
34 34 somewhere other than the default location, use the -o <outdir> option,
35 35 or set the WDIR environment variable. For example:
36 36 $ webrev -o ~/public_html/myreview/
37 37
38 38 In the index file, each file is listed on a line with a link to the
39 39 relevant review materials. Comments for each change will be included
40 40 automatically. Cross references to bug (or other information) tracking
41 41 databases in the comments will become hyperlinks in the associated web
42 42 interface, according to the rules in CROSS REFERENCING below.
43 43
44 44 As a review aid, content may be added to the index file in two ways.
45 45 First, the author may manually edit the file (for example by including
46 46 text that explains the changes in front of the links for each file).
47 47 Note that if webrev is run again, manual edits will be lost. Second,
48 48 if a file named webrev-info is present at the root of the workspace, it
49 49 will be automatically included in the index file. To include a
50 50 different file, see the -i option.
51 51
52 52 For each file in the file list, webrev compares the file with the
53 53 version in the basis for comparison (i.e. the parent workspace) and
54 54 generates a variety of HTML renderings of the differences between the
55 55 two files; which of these renderings to use is largely a matter of
56 56 personal preference. Additional, webrev emits a patch, the old and new
57 57 versions of the file, and a "raw" copy of the file which is suitable
58 58 for download. For files which express differences, source is formatted
59 59 according to the following color coding:
60 60
61 61 unchanged : black
62 62 removed : brown
63 63 changed : blue
64 64 new : bold blue
65 65
66 66
|
↓ open down ↓ |
55 lines elided |
↑ open up ↑ |
67 67 SCM INTERACTIONS
68 68 webrev attempts to interact with the source code management system
69 69 currently in use. webrev needs to be able locate the code under review
70 70 (i.e. the workspace) and the basis for comparison (i.e. the parent).
71 71 The method for doing so depends upon the SCM in use, which webrev will
72 72 also attempt to auto-discover. In all cases, webrev must either
73 73 discover the list of files which have changed, or else this list must
74 74 be manually specified, either in "webrev file list" format or in "wx"
75 75 format. See FILE LIST for more details.
76 76
77 - In all cases, if the user has activated the workspace with the ws(1) or
78 - bldenv(1) commands, webrev will use the CODEMGR_PARENT and CODEMGR_WS
79 - environment variables to identify parent and child workspaces
80 - respectively. To manually specify the basis for comparison, use the -p
81 - option or specify the CODEMGR_PARENT variable in either the file list
82 - or the environment.
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 83
84 84
85 85 Discovering the SCM in use.
86 - webrev makes use of which_scm(1) to determine the SCM in use for a
86 + webrev makes use of which_scm(1ONBLD) to determine the SCM in use for a
87 87 given workspace.
88 88
89 89
90 90 Mercurial
91 91 In the case of Mercurial webrev will attempt to use the output from the
92 92 hg(1) "hg root" command to identify the workspace root, and the "hg
93 93 path default" command to identify the parent workspace.
94 94
95 95
96 96 Git
97 97 In the case of Git webrev will attempt to use the output from the
98 98 git(1) "git rev-parse --git-dir" command to identify the workspace
99 99 root, and will attempt to use the remote branch which the current
100 100 branch is tracking as the parent, if none is specified 'origin/master'
101 101 will be used.
102 102
103 103 The parent specified when using git is, in all cases, a git 'tree-ish'
104 104 and never an actual git repository, remote or otherwise. Anything
105 105 specifiable to git as a tree-ish should, similarly, be specifiable as a
106 106 parent for webrev. This includes branches, explicit revisions, reflog
107 107 entries, etc. See git-rev-parse(1)
108 108
109 109
110 110 Subversion
111 111 In the case of Subversion webrev will attempt to use the output from
112 112 the svn(1) "svn info" to find the workspace root and subversion
113 113 repository URL.
114 114
115 115 The file list will be created from the output of the "svn status"
116 116 command.
117 117
118 118
119 119 CROSS REFERENCING
120 120 After extracting comments (see FILE LIST below), webrev will translate
121 121 cross references into hyperlinks. By default, information about
122 122 available information tracking systems can be found in
123 123 /opt/onbld/etc/its.reg, and the specification of a local domain and
124 124 selection and prioritization of systems in /opt/onbld/etc/its.conf.
125 125 These file formats are self documenting. Also see the -I and -C
126 126 options below.
127 127
128 128 OPTIONS
129 129 -C priority-file
130 130 In addition to the system default and an optional user-
131 131 supplied ~/.its.conf, use the specified file to specify a
132 132 local domain list and prioritize the list of information
133 133 tracking systems to be searched automatically when resolving
134 134 cross references.
135 135
136 136 -D Delete remote webrev via SFTP. Default remote host is
137 137 cr.opensolaris.org, default remote directory for removal is
138 138 the same as workspace/repository basename. Remote target can
139 139 be overriden using -t option. If combined with -U the
140 140 deletion will be performed first. Also, if used together with
141 141 -U and the removal fails, no upload is done. Without -U
142 142 option no webrev will be generated, just like if -n option
143 143 was used. The deletion is done by moving the webrev to
144 144 special directory in user's home directory. It is expected
145 145 that the remote host periodically runs a script which deletes
146 146 the contents of this directory. See the ENVIRONMENT VARIABLES
147 147 section for more details about this directory.
148 148
149 149 -I information-file
150 150 Use the specified file to seed the list of information
151 151 tracking systems.
152 152
153 153 -i include-file
154 154 Include the specified file into the index.html file which is
155 155 generated as part of the webrev. This allows a snippet of
156 156 XHTML to be added by the webrev author. User content is
157 157 contained by a <div> tag and the markup should validate as
158 158 XHTML 1.0 Transitional.
159 159
160 160 -N Suppress all comments from all output forms html, txt and
161 161 pdf.
162 162
163 163 -n Do not generate webrev. Useful whenever only upload is
164 164 needed.
165 165
166 166 -O Enable OpenSolaris mode: information tracking system
167 167 hyperlinks are generated using the EXTERNAL_URL field from
168 168 the specified its.reg entry, instead of the default
169 169 INTERNAL_URL_domain field, and sources which appear in
170 170 usr/closed are automatically elided from the review.
171 171
172 172 -o output-dir
173 173 Place output from running the script in the directory
174 174 specified. If specified, this option takes precedence over
175 175 the WDIR environment variable.
176 176
177 177 -p basis-of-comparison
178 178 Specify a basis of comparison meaningful for the SCM
179 179 currently in use. See SCM INTERACTIONS and INCREMENTAL
180 180 REVIEWS.
181 181
182 182 -t target Upload target. Specified in form of URI identifier. For
183 183 SCP/SFTP it is ssh://user@remote_host:remote_dir and for
184 184 rsync it is rsync://user@remote_host:remote_dir. This option
185 185 can override the -o option if the URI is fully specified. The
186 186 target is relative to the top level directory of the default
187 187 sftp/rsync directory tree.
188 188
189 189 -U Upload the webrev. Default remote host is cr.opensolaris.org.
190 190 Default transport is rsync. If it fails, fallback to SCP/SFTP
191 191 transport is done.
192 192
193 193 -w wx-file
194 194 Extract the file list from the wx "active" file specified.
195 195 'wx' uses this mode when invoking webrev. The list is
196 196 assumed to be in the format expected by the wx package. See
197 197 FILE LIST, below.
198 198
199 199
200 200 FILE LIST
201 201 Webrev needs to be told or to discover which files have changed in a
202 202 given workspace. By default, webrev will attempt to autodetect the
203 203 list of changed files by first consulting wx(1). If this information
204 204 is not available, webrev tries to consult the SCM (Source Code Manager)
205 205 currently in use. If that fails, the user must intervene by specifying
206 206 either a file list or additional options specific to the SCM in use.
207 207
208 208
209 209 Webrev Format
210 210 A webrev formatted file list contains a list of all the files to be
211 211 included in the review with paths relative to the workspace directory,
212 212 e.g.
213 213
214 214 usr/src/uts/common/fs/nfs/nfs_subr.c
215 215 usr/src/uts/common/fs/nfs/nfs_export.c
216 216 usr/src/cmd/fs.d/nfs/mountd/mountd.c
217 217
218 218 Include the paths of any files added, deleted, or modified. You can
219 219 keep this list of files in the webrev directory that webrev creates in
220 220 the workspace directory (CODEMGR_WS).
221 221
222 222 If CODEMGR_WS is not set, it may be specified as an environment
223 223 variable within the file list, e.g.
224 224
225 225 CODEMGR_WS=/home/brent/myws
226 226 usr/src/uts/common/fs/nfs/nfs_subr.c
227 227 usr/src/uts/common/fs/nfs/nfs_export.c
228 228 usr/src/cmd/fs.d/nfs/mountd/mountd.c
229 229
230 230 To compare the workspace against one other than the parent (see also
231 231 the -p option), include a CODEMGR_PARENT line in the file list, like:
232 232
233 233 CODEMGR_WS=/home/brent/myws
234 234 CODEMGR_PARENT=/ws/onnv-gate
235 235 usr/src/uts/common/fs/nfs/nfs_subr.c
236 236 usr/src/uts/common/fs/nfs/nfs_export.c
237 237 usr/src/cmd/fs.d/nfs/mountd/mountd.c
238 238
239 239 Finally, run webrev with the name of the file containing the file list
240 240 as an argument, e.g.
241 241 $ webrev file.list
242 242
243 243 If "-" is supplied as the name of the file, then stdin will be used.
244 244
245 245
246 246 wx Format
247 247 If the -w flag is specified then webrev will assume the file list is in
248 248 the format expected by the "wx" package: pathname lines alternating
249 249 with SCCS comment lines separated by blank lines, e.g.
250 250
251 251 usr/src/uts/common/fs/nfs/nfs_subr.c
252 252
253 253 1206578 Fix spelling error in comment
254 254
255 255 usr/src/uts/common/fs/nfs/nfs_export.c
256 256
257 257 4039272 cstyle fixes
258 258
259 259 usr/src/cmd/fs.d/nfs/mountd/mountd.c
260 260
261 261 1927634 mountd daemon doesn't handle expletives
262 262
263 263
264 264 INCREMENTAL REVIEWS
265 265 When conducting multiple rounds of code review, it may be desirable to
266 266 generate a webrev which represents the delta between reviews. In this
267 267 case, set the parent workspace to the path to the old webrev:
268 268
269 269
270 270 $ webrev -o ~/public_html/myreview-rd2/ \
271 271 -p ~/public_html/myreview/
272 272
273 273
274 274 ENVIRONMENT VARIABLES
275 275 The following environment variables allow for customization of webrev:
276 276
277 277
278 278 CDIFFCMD and UDIFFCMD are used when generating Cdiffs and Udiffs
279 279 respectively; their default values are "diff -b -C 5" and "diff -b -U
280 280 5". To generate diffs with more (or less) than 5 lines of context or
281 281 with more (or less) strict whitespace handling, set one or both of
282 282 these variables in the user environment accordingly.
283 283
284 284 WDIR sets the output directory. It is functionally equivalent to the
285 285 -o option.
286 286
287 287 WDIFF specifies the command used to generate Wdiffs. Wdiff generates a
288 288 full unified context listing with line numbers where unchanged sections
289 289 of code may be expanded and collapsed. It also provides a "split"
290 290 feature that shows the same file in two HTML frames one above the
291 291 other. The default path for this script is /ws/onnv-
292 292 gate/public/bin/wdiff but WDIFF may be set to customize this to use a
293 293 more convenient location.
294 294
295 295 WEBREV_TRASH_DIR specifies alternative location of trash directory for
296 296 remote webrev deletion using the -D option. The directory is relative
297 297 to the top level directory of the default sftp/rsync directory tree.
298 298 The default value of this directory is ".trash".
299 299
300 300
301 301 UPLOADING WEBREVS
302 302 A webrev can be uploaded to remote site using the -U option. To simply
303 303 generate new webrev and upload it to the default remote host use the
304 304 following command:
305 305
306 306 $ webrev -U
307 307
308 308 This will generate the webrev to local directory named 'webrev' and
309 309 upload it to remote host with remote directory name equal to local
310 310 workspace/repository name. To change both local and remote directory
311 311 name, -U can be combined with -o option. The following command will
312 312 store the webrev to local directory named "foo.onnv" and upload it to
313 313 the remote host with the same directory name:
314 314
315 315 $ webrev -U -o $CODEMGR_WS/foo.onnv
316 316
317 317 If there is a need for manual change of the webrev before uploading, -U
318 318 can be combined with -n option so that first command will just generate
319 319 the webrev and the second command will upload it without generating it
320 320 again:
321 321
322 322 $ webrev
323 323 $ webrev -n -U
324 324
325 325 For custom remote targets, -t option allows to specify all components:
326 326
327 327 $ webrev -U -t \
328 328 ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
329 329
330 330 If the remote path is specified as absolute, webrev will assume all the
331 331 directories are already created. If the path is relative, webrev will
332 332 try to create all needed directories. This only works with SCP/SFTP
333 333 transport.
334 334
335 335 By default, rsync transport will use SSH for transferring the data to
336 336 remote site. To specify custom username, use entry in SSH client
337 337 configuration file, for example:
338 338
339 339 Host cr.opensolaris.org
340 340 Hostname cr.opensolaris.org
341 341 User vkotal
342 342
343 343
344 344 DELETING WEBREVS
345 345 When deleting a webrev directory on remote site which has a different
346 346 name than the basename of local repository it is necessary to specify
347 347 the output option:
348 348
349 349 $ webrev -Do webrev-foo.onnv
350 350
351 351 Otherwise webrev will attempt to remove remote directory with the same
352 352 name as basename of the local repository.
353 353
|
↓ open down ↓ |
257 lines elided |
↑ open up ↑ |
354 354 For the nested directory case it is necessary to specify the full
355 355 target:
356 356
357 357 $ webrev -D -t \
358 358 ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
359 359
360 360 This will remove just the bugfix.onnv directory.
361 361
362 362
363 363 SEE ALSO
364 - hg(1), git(1), ssh_config(4), svn(1), which_scm(1)
364 + hg(1), git(1), ssh_config(4), svn(1), which_scm(1ONBLD)
365 365
366 366
367 367 ACKNOWLEDGEMENTS
368 368 Acknowledgements to Rob Thurlow, Mike Eisler, Lin Ling, Rod Evans, Mike
369 369 Kupfer, Greg Onufer, Glenn Skinner, Oleg Larin, David Robinson, Matthew
370 370 Cross, David L. Paktor, Neal Gafter, John Beck, Darren Moffat, Norm
371 371 Shulman, Bill Watson, Pedro Rubio and Bill Shannon for valuable
372 372 feedback and insight in building webrev.
373 373
374 374 Have fun!
375 375 Brent Callaghan 11/28/96
376 376
377 377
378 378
379 379
380 - 7 Feb 2014 webrev(1)
380 + 7 Feb 2014 webrev(1ONBLD)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX