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