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