4 .\" The contents of this file are subject to the terms of the
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 1ONBLD "Mar 27, 2016"
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 ]
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 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
81 relevant review materials. Comments for each change will be included
82 automatically. Cross references to bug (or other information) tracking
83 databases in the comments will become hyperlinks in the associated web
84 interface, according to the rules in CROSS REFERENCING below.
85
86 As a review aid, content may be added to the \fIindex\fR file in two ways.
87 First, the author may manually edit the file (for example by including
88 text that explains the changes in front of the links for each file).
89 Note that if webrev is run again, manual edits will be lost. Second,
90 if a file named \fIwebrev-info\fR is present at the root of the workspace,
91 it will be automatically included in the \fIindex\fR file. To include a
92 different file, see the \fI-i\fR option.
93
94 For each file in the file list, \fBwebrev\fR compares the file with the
95 version in the basis for comparison (i.e. the parent workspace) and
96 generates a variety of HTML renderings of the differences between
97 the two files; which of these renderings to use is largely a matter
98 of personal preference. Additional, webrev emits a patch, the old
99 and new versions of the file, and a "raw" copy of the file which is
100 suitable for download. For files which express differences, source
101 is formatted according to the following color coding:
102 .IP
103 .nf
104 unchanged : black
105 removed : brown
106 changed : blue
107 new : bold blue
108 .fi
109
110 .SH SCM INTERACTIONS
111 .PP
112 .B webrev
113 attempts to interact with the source code management system currently in use.
114 .B webrev
115 needs to be able locate the code under review (i.e. the workspace) and
116 the basis for comparison (i.e. the parent). The method for doing so
117 depends upon the SCM in use, which
118 .B webrev
119 will also attempt to auto-discover. In all cases,
120 .B webrev
121 must either discover the list of files which have changed, or else this list
122 must be manually specified, either in "webrev file list" format or in "wx"
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 (1ONBLD)
128 or
129 .BR bldenv (1ONBLD)
130 commands, \fBwebrev\fR will use the \fBCODEMGR_PARENT\fR and
131 \fBCODEMGR_WS\fR environment variables to identify parent and child
145 .BR git (1)
146 "git rev-parse --git-dir" command to identify the workspace root, and will
147 attempt to use the remote branch which the current branch is tracking as the
148 parent, if none is specified 'origin/master' will be used.
149
150 The parent specified when using git is, in all cases, a git 'tree-ish' and
151 never an actual git repository, remote or otherwise. Anything specifiable to
152 git as a tree-ish should, similarly, be specifiable as a parent for webrev.
153 This includes branches, explicit revisions, reflog entries, etc. See
154 .BR git-rev-parse (1)
155
156 .SS Subversion
157 In the case of Subversion \fBwebrev\fR will attempt to use the output
158 from the
159 .BR svn (1)
160 "svn info" to find the workspace root and subversion repository URL.
161 .PP
162 The file list will be created from the output of the "svn status" command.
163
164 .SH CROSS REFERENCING
165 .PP
166 After extracting comments (see FILE LIST below),
167 .B webrev
168 will translate cross references into hyperlinks. By default, information
169 about available information tracking systems can be found in
170 /opt/onbld/etc/its.reg, and the specification of a local domain and
171 selection and prioritization of systems
172 in /opt/onbld/etc/its.conf. These file formats are self documenting. Also
173 see the -I and -C options below.
174 .SH OPTIONS
175 .TP 10
176 .BI "-c " revision
177 Generate webrev for single commit specified by \fIrevision\fR (git only).
178 .TP 10
179 .BI "-C " priority-file
180 In addition to the system default and an optional user-supplied ~/.its.conf,
181 use the specified file to specify a local domain list and prioritize the list
182 of information tracking systems to be searched automatically when resolving cross
183 references.
184 .TP 10
185 .BI "-D"
186 Delete remote webrev via SFTP. Default remote host is \fIcr.opensolaris.org\fR,
187 default remote directory for removal is the same as workspace/repository
188 basename. Remote target can be overriden using -t option. If combined with
189 -U the deletion will be performed first. Also, if used together with -U
190 and the removal fails, no upload is done. Without -U option no webrev will
191 be generated, just like if -n option was used. The deletion is done by
192 moving the webrev to special directory in user's home directory. It is
193 expected that the remote host periodically runs a script which deletes
194 the contents of this directory. See the ENVIRONMENT VARIABLES section for
195 more details about this directory.
196 .TP 10
197 .BI "-h " head-revision
198 Specify the explicit head to generate webrev from (git only).
199 .TP 10
200 .BI "-I " information-file
201 Use the specified file to seed the list of information tracking systems.
202 .TP 10
203 .BI "-i " include-file
204 Include the specified file into the index.html file which is generated
205 as part of the webrev. This allows a snippet of XHTML to be added by
206 the webrev author. User content is contained by a <div> tag and
207 the markup should validate as XHTML 1.0 Transitional.
208 .TP 10
209 .BI "-N"
210 Suppress all comments from all output forms html, txt and pdf.
211 .TP 10
212 .BI "-n"
213 Do not generate webrev. Useful whenever only upload is needed.
214 .TP 10
215 .B -O
216 Enable \fIOpenSolaris\fR mode: information tracking system hyperlinks
217 are generated using the EXTERNAL_URL field from the specified its.reg entry,
218 instead of the default INTERNAL_URL_domain field, and sources which appear in
219 \fIusr/closed\fR are automatically elided from the review.
220 .TP 10
221 .BI "-o " output-dir
222 Place output from running the script in the directory specified. If
223 specified, this option takes precedence over the WDIR environment variable.
224 .TP 10
225 .BI "-p " basis-of-comparison
226 Specify a basis of comparison meaningful for the SCM currently in use.
227 See SCM INTERACTIONS and INCREMENTAL REVIEWS.
228 .TP 10
229 .BI "-t " target
230 Upload target. Specified in form of URI identifier. For SCP/SFTP it is
231 \fIssh://user@remote_host:remote_dir\fR and for rsync it is
232 \fIrsync://user@remote_host:remote_dir\fR. This option can override the
233 -o option if the URI is fully specified. The target is relative to
234 the top level directory of the default sftp/rsync directory tree.
235 .TP 10
236 .BI "-U"
237 Upload the webrev. Default remote host is \fIcr.opensolaris.org\fR.
238 Default transport is rsync. If it fails, fallback to SCP/SFTP transport
239 is done.
240 .TP 10
241 .BI "-w " wx-file
242 Extract the file list from the wx "active" file specified. 'wx' uses
243 this mode when invoking webrev. The list is assumed to be in the
244 format expected by the \fIwx\fR package. See FILE LIST, below.
245
246 .SH FILE LIST
247 .PP
248 .B Webrev
249 needs to be told or to discover which files have changed in a
250 given workspace. By default,
251 .B webrev
252 will attempt to autodetect the
253 list of changed files by first consulting
254 .BR wx "(1)."
255 If this information is not available, webrev tries to consult the SCM (Source
256 Code Manager) currently in use. If that fails, the user must intervene by
257 specifying either a file list or additional options specific to the SCM in use.
258
259 .SS Webrev Format
260 A webrev formatted file list contains a list of all the files to
261 be included in the review with paths relative to the workspace
262 directory, e.g.
263 .IP
264 .nf
265 \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c
266 usr/src/uts/common/fs/nfs/nfs_export.c
267 usr/src/cmd/fs.d/nfs/mountd/mountd.c
|
4 .\" The contents of this file are subject to the terms of the
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 .\" Copyright 2019 Joyent, Inc.
25 .\"
26 .TH WEBREV 1ONBLD "Aug 2, 2019"
27 .SH NAME
28 webrev \- Generate HTML codereview materials
29 .SH SYNOPSIS
30 .B webrev
31 [
32 .I common-options
33 ]
34
35 .B webrev
36 [
37 .I common-options
38 ]
39 .I file-list-file
40 |
41 .I -
42
43 .B webrev
44 [
45 .I common-options
46 ]
50 .SH DESCRIPTION
51 .B webrev
52 builds a set of HTML files suitable for performing code review of
53 source changes in a web browser.
54 It supports Git and Subversion repositories.
55 At its most basic, usage is:
56 .nf
57 $ webrev
58 .fi
59
60 In which case \fBwebrev\fR attempts to figure out the list of files
61 for review. If that fails, or if more control
62 over the set of files is needed, a \fIfile list\fR may be specified.
63 \fBwebrev\fR also attempts to deduce a
64 .I basis for comparison
65 (interchangeably called the \fIparent\fR, but see SCM INTERACTIONS below).
66 A basis for comparison is needed in order to determine the differences
67 introduced by the code changes under review.
68
69 By default, \fBwebrev\fR creates a \fIwebrev\fR directory in the
70 workspace directory that contains the generated HTML files, and a patch
71 representing the changes. It also places a copy of the file list in
72 that directory, and of both the old and new raw files in the
73 \fB$webrev_root/raw_files\fR directory.
74 To output the webrev somewhere other than the default location, use the
75 \fI-o <outdir>\fR option, or set the \fBWDIR\fR environment variable.
76 For example:
77 .nf
78 $ webrev -o ~/public_html/myreview/
79 .fi
80 .PP
81 In the index file, each file is listed on a line with a link to the
82 relevant review materials. Comments for each change will be included
83 automatically. Cross references to bug (or other information) tracking
84 databases in the comments will become hyperlinks in the associated web
85 interface, according to the rules in CROSS REFERENCING below.
86
87 As a review aid, content may be added to the \fIindex\fR file in two ways.
88 First, the author may manually edit the file (for example by including
89 text that explains the changes in front of the links for each file).
90 Note that if webrev is run again, manual edits will be lost. Second,
91 if a file named \fIwebrev-info\fR is present at the root of the workspace,
92 it will be automatically included in the \fIindex\fR file. To include a
93 different file, see the \fI-i\fR option.
94
95 For each file in the file list, \fBwebrev\fR compares the file with the
96 version in the basis for comparison (i.e. the parent workspace) and
97 generates a variety of HTML renderings of the differences between
98 the two files; which of these renderings to use is largely a matter
99 of personal preference. Additional, webrev emits a patch, the old
100 and new versions of the file, and a "raw" copy of the file which is
101 suitable for download. For files which express differences, source
102 is formatted according to the following color coding:
103 .IP
104 .nf
105 unchanged : black
106 removed : brown
107 changed : blue
108 new : bold blue
109 .fi
110
111 .SH SCM INTERACTIONS
112 .B webrev
113 attempts to interact with the source code management system currently in use.
114 .B webrev
115 needs to be able locate the code under review (i.e. the workspace) and
116 the basis for comparison (i.e. the parent). The method for doing so
117 depends upon the SCM in use, which
118 .B webrev
119 will also attempt to auto-discover. In all cases,
120 .B webrev
121 must either discover the list of files which have changed, or else this list
122 must be manually specified, either in "webrev file list" format or in "wx"
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 (1ONBLD)
128 or
129 .BR bldenv (1ONBLD)
130 commands, \fBwebrev\fR will use the \fBCODEMGR_PARENT\fR and
131 \fBCODEMGR_WS\fR environment variables to identify parent and child
145 .BR git (1)
146 "git rev-parse --git-dir" command to identify the workspace root, and will
147 attempt to use the remote branch which the current branch is tracking as the
148 parent, if none is specified 'origin/master' will be used.
149
150 The parent specified when using git is, in all cases, a git 'tree-ish' and
151 never an actual git repository, remote or otherwise. Anything specifiable to
152 git as a tree-ish should, similarly, be specifiable as a parent for webrev.
153 This includes branches, explicit revisions, reflog entries, etc. See
154 .BR git-rev-parse (1)
155
156 .SS Subversion
157 In the case of Subversion \fBwebrev\fR will attempt to use the output
158 from the
159 .BR svn (1)
160 "svn info" to find the workspace root and subversion repository URL.
161 .PP
162 The file list will be created from the output of the "svn status" command.
163
164 .SH CROSS REFERENCING
165 After extracting comments (see FILE LIST below),
166 .B webrev
167 will translate cross references into hyperlinks. By default, information
168 about available information tracking systems can be found in
169 /opt/onbld/etc/its.reg, and the specification of a local domain and
170 selection and prioritization of systems
171 in /opt/onbld/etc/its.conf. These file formats are self documenting. Also
172 see the -I and -C options below.
173 .SH OPTIONS
174 .TP 10
175 .BI "-c " revision
176 Generate webrev for single commit specified by \fIrevision\fR (git only).
177 .TP 10
178 .BI "-C " priority-file
179 In addition to the system default and an optional user-supplied ~/.its.conf,
180 use the specified file to specify a local domain list and prioritize the list
181 of information tracking systems to be searched automatically when resolving cross
182 references.
183 .TP 10
184 .BI "-D"
185 Delete remote webrev via SFTP. Default remote host is \fIcr.opensolaris.org\fR,
186 default remote directory for removal is the same as workspace/repository
187 basename. Remote target can be overridden using -t option. If combined with
188 -U the deletion will be performed first. Also, if used together with -U
189 and the removal fails, no upload is done. Without -U option no webrev will
190 be generated, just like if -n option was used. The deletion is done by
191 moving the webrev to special directory in user's home directory. It is
192 expected that the remote host periodically runs a script which deletes
193 the contents of this directory. See the ENVIRONMENT VARIABLES section for
194 more details about this directory.
195 .TP 10
196 .BI "-h " head-revision
197 Specify the explicit head to generate webrev from (git only).
198 .TP 10
199 .BI "-I " information-file
200 Use the specified file to seed the list of information tracking systems.
201 .TP 10
202 .BI "-i " include-file
203 Include the specified file into the index.html file which is generated
204 as part of the webrev. This allows a snippet of XHTML to be added by
205 the webrev author. User content is contained by a <div> tag and
206 the markup should validate as XHTML 1.0 Transitional.
207 .TP 10
208 .BI "-N"
209 Suppress all comments from all output forms.
210 .TP 10
211 .BI "-n"
212 Do not generate webrev. Useful whenever only upload is needed.
213 .TP 10
214 .B -O
215 Enable \fIOpenSolaris\fR mode: information tracking system hyperlinks
216 are generated using the EXTERNAL_URL field from the specified its.reg entry,
217 instead of the default INTERNAL_URL_domain field, and sources which appear in
218 \fIusr/closed\fR are automatically elided from the review.
219 .TP 10
220 .BI "-o " output-dir
221 Place output from running the script in the directory specified. If
222 specified, this option takes precedence over the WDIR environment variable.
223 .TP 10
224 .BI "-p " basis-of-comparison
225 Specify a basis of comparison meaningful for the SCM currently in use.
226 See SCM INTERACTIONS and INCREMENTAL REVIEWS.
227 .TP 10
228 .BI "-t " target
229 Upload target. Specified in form of URI identifier. For SCP/SFTP it is
230 \fIssh://user@remote_host:remote_dir\fR and for rsync it is
231 \fIrsync://user@remote_host:remote_dir\fR. This option can override the
232 -o option if the URI is fully specified. The target is relative to
233 the top level directory of the default sftp/rsync directory tree.
234 .TP 10
235 .BI "-U"
236 Upload the webrev. Default remote host is \fIcr.opensolaris.org\fR.
237 Default transport is rsync. If it fails, fallback to SCP/SFTP transport
238 is done.
239 .TP 10
240 .BI "-w " wx-file
241 Extract the file list from the wx "active" file specified. 'wx' uses
242 this mode when invoking webrev. The list is assumed to be in the
243 format expected by the \fIwx\fR package. See FILE LIST, below.
244
245 .SH FILE LIST
246 .B Webrev
247 needs to be told or to discover which files have changed in a
248 given workspace. By default,
249 .B webrev
250 will attempt to autodetect the
251 list of changed files by first consulting
252 .BR wx "(1)."
253 If this information is not available, webrev tries to consult the SCM (Source
254 Code Manager) currently in use. If that fails, the user must intervene by
255 specifying either a file list or additional options specific to the SCM in use.
256
257 .SS Webrev Format
258 A webrev formatted file list contains a list of all the files to
259 be included in the review with paths relative to the workspace
260 directory, e.g.
261 .IP
262 .nf
263 \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c
264 usr/src/uts/common/fs/nfs/nfs_export.c
265 usr/src/cmd/fs.d/nfs/mountd/mountd.c
|