5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\"
21 .\" Copyright 2010 Sun Microsystems, Inc. All rights reserved.
22 .\" Use is subject to license terms.
23 .\"
24 .\"
25 .TH webrev 1 "6 Dec 2010"
26 .SH NAME
27 webrev \- Generate HTML codereview materials
28 .SH SYNOPSIS
29 .B webrev
30 [
31 .I common-options
32 ]
33
34 .B webrev
35 [
36 .I common-options
37 ]
38 .I file-list-file
39 |
40 .I -
41
42 .B webrev
43 [
44 .I common-options
45 ]
46 .B -w
47 .I wx-file
48
49 .B webrev
50 [
51 .I common-options
52 ]
53 .B -l
54 .I arguments to 'putback'
55
56 See OPTIONS for common-options.
57 Note that the -l option is only applicable to TeamWare workspaces.
58
59 .SH DESCRIPTION
60 .B webrev
61 builds a set of HTML files suitable for performing code review of
62 source changes in a web browser.
63 It supports Mercurial, Git, Subversion and Teamware repositories.
64 At its most basic, usage is:
65 .nf
66 $ webrev
67 .fi
68
69 In which case \fBwebrev\fR attempts to figure out the list of files
70 for review (note that when using Teamware \fBputback\fR, this may take
71 a long time; see the -l option). If that fails, or if more control
72 over the set of files is needed, a \fIfile list\fR may be specified.
73 \fBwebrev\fR also attempts to deduce a
74 .I basis for comparison
75 (interchangeably called the \fIparent\fR, but see SCM INTERACTIONS below).
76 A basis for comparison is needed in order to determine the differences
77 introduced by the code changes under review.
78
79 By default, \fBwebrev\fR creates a \fIwebrev\fR directory in the
80 workspace directory that contains the generated HTML files, a generated
81 PDF review, and a patch representing the changes. It also places a
82 copy of the file list in that directory, and of both the old and new
83 raw files in the \fB$webrev_root/raw_files\fR directory.
84 To output the webrev somewhere other than the default location, use the
85 \fI-o <outdir>\fR option, or set the \fBWDIR\fR environment variable.
86 For example:
87 .nf
88 $ webrev -o ~/public_html/myreview/
89 .fi
90 .PP
91 In the index file, each file is listed on a line with a link to the
134 format.
135 See FILE LIST for more details.
136 .PP
137 In all cases, if the user has activated the workspace with the
138 .BR ws (1)
139 or
140 .BR bldenv (1)
141 commands, \fBwebrev\fR will use the \fBCODEMGR_PARENT\fR and
142 \fBCODEMGR_WS\fR environment variables to identify parent and child
143 workspaces respectively.
144 To manually specify the basis for comparison, use the -p option or
145 specify the \fBCODEMGR_PARENT\fR variable in either the file list or
146 the environment.
147
148 .SS Discovering the SCM in use.
149 .B webrev
150 makes use of
151 .BR which_scm (1)
152 to determine the SCM in use for a given workspace.
153
154 .SS TeamWare
155 In the case of TeamWare \fBwebrev\fR will use the output of "workspace
156 name" to discover the workspace root, if not otherwise specified.
157 .PP
158 \fBwebrev\fR will attempt to use a
159 .BR wx (1)
160 active list in
161 \fBCODEMGR_WS/wx/active\fR.
162 To direct \fBwebrev\fR to determine the file list from the output of
163 .BR putback "(1),"
164 use the -l option. (Note that \fBwebrev\fR may also elect to use
165 \fBputback\fR if it cannot determine the file list from
166 .BR wx "(1))."
167 The -l option indicates that subsequent arguments should be
168 treated as arguments to
169 .BR putback "(1)."
170 This can be used to prune the set of files which putback examines,
171 or to reference a teamware flp (file list program).
172
173 .SS Mercurial
174 In the case of Mercurial \fBwebrev\fR will attempt to use the output
175 from the
176 .BR hg (1)
177 "hg root" command to identify the workspace root, and the
178 "hg path default" command to identify the parent workspace.
179
180 .SS Git
181 In the case of Git \fBwebrev\fR will attempt to use the output from the
182 .BR git (1)
183 "git rev-parse --git-dir" command to identify the workspace root, and will
184 attempt to use the remote branch which the current branch is tracking as the
185 parent, if none is specified 'origin/master' will be used.
186
187 The parent specified when using git is, in all cases, a git 'tree-ish' and
188 never an actual git repository, remote or otherwise. Anything specifiable to
189 git as a tree-ish should, similarly, be specifiable as a parent for webrev.
190 This includes branches, explicit revisions, reflog entries, etc. See
191 .BR git-rev-parse (1)
192
220 Delete remote webrev via SFTP. Default remote host is \fIcr.opensolaris.org\fR,
221 default remote directory for removal is the same as workspace/repository
222 basename. Remote target can be overriden using -t option. If combined with
223 -U the deletion will be performed first. Also, if used together with -U
224 and the removal fails, no upload is done. Without -U option no webrev will
225 be generated, just like if -n option was used. The deletion is done by
226 moving the webrev to special directory in user's home directory. It is
227 expected that the remote host periodically runs a script which deletes
228 the contents of this directory. See the ENVIRONMENT VARIABLES section for
229 more details about this directory.
230 .TP 10
231 .BI "-I " information-file
232 Use the specified file to seed the list of information tracking systems.
233 .TP 10
234 .BI "-i " include-file
235 Include the specified file into the index.html file which is generated
236 as part of the webrev. This allows a snippet of XHTML to be added by
237 the webrev author. User content is contained by a <div> tag and
238 the markup should validate as XHTML 1.0 Transitional.
239 .TP 10
240 .BI "-l " putback-args
241 Extract the file list from the output of
242 .I putback -n.
243 Any arguments supplied will be passed to
244 .BR putback "(1)."
245 See SCM INTERACTIONS. For more information about file
246 lists, see FILE LIST. This argument should appear last.
247 .TP 10
248 .BI "-N"
249 Suppress all comments from all output forms html, txt and pdf.
250 .TP 10
251 .BI "-n"
252 Do not generate webrev. Useful whenever only upload is needed.
253 .TP 10
254 .B -O
255 Enable \fIOpenSolaris\fR mode: information tracking system hyperlinks
256 are generated using the EXTERNAL_URL field from the specified its.reg entry,
257 instead of the default INTERNAL_URL_domain field, and sources which appear in
258 \fIusr/closed\fR are automatically elided from the review.
259 .TP 10
260 .BI "-o " output-dir
261 Place output from running the script in the directory specified. If
262 specified, this option takes precedence over the WDIR environment variable.
263 .TP 10
264 .BI "-p " basis-of-comparison
265 Specify a basis of comparison meaningful for the SCM currently in use.
266 See SCM INTERACTIONS and INCREMENTAL REVIEWS.
267 .TP 10
451 than the basename of local repository it is necessary to specify the output
452 option:
453 .IP
454 .nf
455 \f(CW$ webrev -Do webrev-foo.onnv
456 .fi
457 .PP
458 Otherwise \fBwebrev\fR will attempt to remove remote directory with the same
459 name as basename of the local repository.
460 .PP
461 For the nested directory case it is necessary to specify the full target:
462 .IP
463 .nf
464 \f(CW$ webrev -D -t \\
465 ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
466 .fi
467 .PP
468 This will remove just the \fIbugfix.onnv\fR directory.
469
470 .SH SEE ALSO
471 .BR putback "(1),"
472 .BR workspace "(1),"
473 .BR hg "(1),"
474 .BR git "(1),"
475 .BR ssh_config "(4),"
476 .BR svn "(1),"
477 .BR which_scm "(1)"
478
479 .SH ACKNOWLEDGEMENTS
480 Acknowledgements to Rob Thurlow, Mike Eisler, Lin Ling,
481 Rod Evans, Mike Kupfer, Greg Onufer, Glenn Skinner,
482 Oleg Larin, David Robinson, Matthew Cross, David L. Paktor,
483 Neal Gafter, John Beck, Darren Moffat, Norm Shulman, Bill Watson,
484 Pedro Rubio and Bill Shannon for valuable feedback and insight in
485 building webrev.
486
487 Have fun!
488 .br
489 Brent Callaghan 11/28/96
490
|
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\"
21 .\" Copyright 2010 Sun Microsystems, Inc. All rights reserved.
22 .\" Use is subject to license terms.
23 .\"
24 .\"
25 .TH webrev 1 "7 Feb 2014"
26 .SH NAME
27 webrev \- Generate HTML codereview materials
28 .SH SYNOPSIS
29 .B webrev
30 [
31 .I common-options
32 ]
33
34 .B webrev
35 [
36 .I common-options
37 ]
38 .I file-list-file
39 |
40 .I -
41
42 .B webrev
43 [
44 .I common-options
45 ]
46 .B -w
47 .I wx-file
48
49 .SH DESCRIPTION
50 .B webrev
51 builds a set of HTML files suitable for performing code review of
52 source changes in a web browser.
53 It supports Mercurial, Git and Subversion repositories.
54 At its most basic, usage is:
55 .nf
56 $ webrev
57 .fi
58
59 In which case \fBwebrev\fR attempts to figure out the list of files
60 for review. If that fails, or if more control
61 over the set of files is needed, a \fIfile list\fR may be specified.
62 \fBwebrev\fR also attempts to deduce a
63 .I basis for comparison
64 (interchangeably called the \fIparent\fR, but see SCM INTERACTIONS below).
65 A basis for comparison is needed in order to determine the differences
66 introduced by the code changes under review.
67
68 By default, \fBwebrev\fR creates a \fIwebrev\fR directory in the
69 workspace directory that contains the generated HTML files, a generated
70 PDF review, and a patch representing the changes. It also places a
71 copy of the file list in that directory, and of both the old and new
72 raw files in the \fB$webrev_root/raw_files\fR directory.
73 To output the webrev somewhere other than the default location, use the
74 \fI-o <outdir>\fR option, or set the \fBWDIR\fR environment variable.
75 For example:
76 .nf
77 $ webrev -o ~/public_html/myreview/
78 .fi
79 .PP
80 In the index file, each file is listed on a line with a link to the
123 format.
124 See FILE LIST for more details.
125 .PP
126 In all cases, if the user has activated the workspace with the
127 .BR ws (1)
128 or
129 .BR bldenv (1)
130 commands, \fBwebrev\fR will use the \fBCODEMGR_PARENT\fR and
131 \fBCODEMGR_WS\fR environment variables to identify parent and child
132 workspaces respectively.
133 To manually specify the basis for comparison, use the -p option or
134 specify the \fBCODEMGR_PARENT\fR variable in either the file list or
135 the environment.
136
137 .SS Discovering the SCM in use.
138 .B webrev
139 makes use of
140 .BR which_scm (1)
141 to determine the SCM in use for a given workspace.
142
143 .SS Mercurial
144 In the case of Mercurial \fBwebrev\fR will attempt to use the output
145 from the
146 .BR hg (1)
147 "hg root" command to identify the workspace root, and the
148 "hg path default" command to identify the parent workspace.
149
150 .SS Git
151 In the case of Git \fBwebrev\fR will attempt to use the output from the
152 .BR git (1)
153 "git rev-parse --git-dir" command to identify the workspace root, and will
154 attempt to use the remote branch which the current branch is tracking as the
155 parent, if none is specified 'origin/master' will be used.
156
157 The parent specified when using git is, in all cases, a git 'tree-ish' and
158 never an actual git repository, remote or otherwise. Anything specifiable to
159 git as a tree-ish should, similarly, be specifiable as a parent for webrev.
160 This includes branches, explicit revisions, reflog entries, etc. See
161 .BR git-rev-parse (1)
162
190 Delete remote webrev via SFTP. Default remote host is \fIcr.opensolaris.org\fR,
191 default remote directory for removal is the same as workspace/repository
192 basename. Remote target can be overriden using -t option. If combined with
193 -U the deletion will be performed first. Also, if used together with -U
194 and the removal fails, no upload is done. Without -U option no webrev will
195 be generated, just like if -n option was used. The deletion is done by
196 moving the webrev to special directory in user's home directory. It is
197 expected that the remote host periodically runs a script which deletes
198 the contents of this directory. See the ENVIRONMENT VARIABLES section for
199 more details about this directory.
200 .TP 10
201 .BI "-I " information-file
202 Use the specified file to seed the list of information tracking systems.
203 .TP 10
204 .BI "-i " include-file
205 Include the specified file into the index.html file which is generated
206 as part of the webrev. This allows a snippet of XHTML to be added by
207 the webrev author. User content is contained by a <div> tag and
208 the markup should validate as XHTML 1.0 Transitional.
209 .TP 10
210 .BI "-N"
211 Suppress all comments from all output forms html, txt and pdf.
212 .TP 10
213 .BI "-n"
214 Do not generate webrev. Useful whenever only upload is needed.
215 .TP 10
216 .B -O
217 Enable \fIOpenSolaris\fR mode: information tracking system hyperlinks
218 are generated using the EXTERNAL_URL field from the specified its.reg entry,
219 instead of the default INTERNAL_URL_domain field, and sources which appear in
220 \fIusr/closed\fR are automatically elided from the review.
221 .TP 10
222 .BI "-o " output-dir
223 Place output from running the script in the directory specified. If
224 specified, this option takes precedence over the WDIR environment variable.
225 .TP 10
226 .BI "-p " basis-of-comparison
227 Specify a basis of comparison meaningful for the SCM currently in use.
228 See SCM INTERACTIONS and INCREMENTAL REVIEWS.
229 .TP 10
413 than the basename of local repository it is necessary to specify the output
414 option:
415 .IP
416 .nf
417 \f(CW$ webrev -Do webrev-foo.onnv
418 .fi
419 .PP
420 Otherwise \fBwebrev\fR will attempt to remove remote directory with the same
421 name as basename of the local repository.
422 .PP
423 For the nested directory case it is necessary to specify the full target:
424 .IP
425 .nf
426 \f(CW$ webrev -D -t \\
427 ssh://user@cr.opensolaris.org:foo/bar/bugfix.onnv
428 .fi
429 .PP
430 This will remove just the \fIbugfix.onnv\fR directory.
431
432 .SH SEE ALSO
433 .BR hg "(1),"
434 .BR git "(1),"
435 .BR ssh_config "(4),"
436 .BR svn "(1),"
437 .BR which_scm "(1)"
438
439 .SH ACKNOWLEDGEMENTS
440 Acknowledgements to Rob Thurlow, Mike Eisler, Lin Ling,
441 Rod Evans, Mike Kupfer, Greg Onufer, Glenn Skinner,
442 Oleg Larin, David Robinson, Matthew Cross, David L. Paktor,
443 Neal Gafter, John Beck, Darren Moffat, Norm Shulman, Bill Watson,
444 Pedro Rubio and Bill Shannon for valuable feedback and insight in
445 building webrev.
446
447 Have fun!
448 .br
449 Brent Callaghan 11/28/96
450
|