|
112
|
1 @node Invoking the tools
|
|
|
2 @chapter Invoking the @sc{gnats} tools
|
|
|
3 @cindex usage for the @sc{gnats} tools
|
|
|
4 @cindex invoking the @sc{gnats} tools
|
|
|
5 @cindex tool usage for software maintainers
|
|
|
6
|
|
|
7 The following programs comprise @sc{gnats}:
|
|
|
8
|
|
|
9 @cindex user utilities
|
|
|
10 @subheading User Utilities
|
|
|
11
|
|
|
12 These tools are used by the maintainers of a body of work
|
|
|
13 (@w{@code{send-pr}} is also used by the end users of the product).
|
|
|
14
|
|
|
15 @table @code
|
|
|
16 @item send-pr
|
|
|
17 Used by anyone who has a problem with a body of work to submit a report
|
|
|
18 of the problem to the maintainers of that work
|
|
|
19 (@pxref{send-pr,,Submitting Problem Reports}).
|
|
|
20
|
|
|
21 @item query-pr
|
|
|
22 Used by software maintainers to query the @sc{gnats} database
|
|
|
23 (@pxref{query-pr,,Querying the database}).
|
|
|
24
|
|
|
25 @item edit-pr
|
|
|
26 Used by software maintainers to edit Problem Reports (to record new
|
|
|
27 data, to change the responsible party, etc.) (@pxref{edit-pr,,Editing
|
|
|
28 existing Problem Reports}).
|
|
|
29
|
|
|
30 @item view-pr
|
|
|
31 Used by software maintainers to view individual Problem Reports using
|
|
|
32 Emacs (@pxref{view-pr,,Viewing individual Problem Reports}).
|
|
|
33 @end table
|
|
|
34
|
|
|
35 @cindex administrative utilities
|
|
|
36 @subheading Administrative Utilities
|
|
|
37
|
|
|
38 These tools are used by the @sc{gnats} administrator; see also
|
|
|
39 @ref{Management,,@sc{gnats} Administration}. For complete explanations
|
|
|
40 of these utilities, see @ref{Admin utils,,Administrative utilities}.
|
|
|
41
|
|
|
42 @table @code
|
|
|
43 @item mkcat
|
|
|
44 Creates new categories (@pxref{mkcat,,Adding a problem category}).
|
|
|
45
|
|
|
46 @item rmcat
|
|
|
47 Removes existing categories (@pxref{rmcat,,Removing a problem
|
|
|
48 category}).
|
|
|
49
|
|
|
50 @item gen-index
|
|
|
51 Generates an up-to-date copy of the index used by @code{query-pr} and
|
|
|
52 @code{edit-pr} (@pxref{index file,,The @code{index} file}). Use
|
|
|
53 @code{gen-index} to rebuild the index if it becomes corrupted, or if you
|
|
|
54 need a copy of the current index for some reason
|
|
|
55 (@pxref{gen-index,,Regenerating the index}).
|
|
|
56
|
|
|
57 @item mkdist
|
|
|
58 Creates a distribution of the program @code{send-pr} for offsite
|
|
|
59 submitters of PRs (@pxref{mkdist,,Configuring @code{send-pr} for the
|
|
|
60 outside world}).
|
|
|
61 @end table
|
|
|
62
|
|
|
63 @cindex internal utilities
|
|
|
64 @subheading Internal Utilities
|
|
|
65
|
|
|
66 These tools are used internally by @sc{gnats}. You should not need to
|
|
|
67 run these by hand. For complete explanations of these utilities, see
|
|
|
68 @ref{Internal utils,,Internal utilities}.
|
|
|
69
|
|
|
70 @table @code
|
|
|
71 @item queue-pr
|
|
|
72 Handles incoming bugs, first through a mail alias by queueing incoming
|
|
|
73 PRs as they arrive, and second as a periodic transfer agent between the
|
|
|
74 queue and the database.
|
|
|
75
|
|
|
76 @item file-pr
|
|
|
77 Files Problem Reports as they come in.
|
|
|
78
|
|
|
79 @item at-pr
|
|
|
80 Sends reminders to maintainers based on quoted response times.
|
|
|
81
|
|
|
82 @item pr-edit
|
|
|
83 Used by @code{edit-pr} to error-check and submit edited Problem Reports
|
|
|
84 (also @pxref{edit-pr,,Editing existing Problem Reports}).
|
|
|
85
|
|
|
86 @item pr-addr
|
|
|
87 Used by the @code{edit-pr} script to retrieve correct addresses from the
|
|
|
88 @file{responsible} file.
|
|
|
89 @end table
|
|
|
90
|
|
|
91 @xref{Locations,,Where @sc{gnats} lives}.
|
|
|
92
|
|
|
93 @menu
|
|
|
94 * send-pr:: Submitting Problem Reports
|
|
|
95 * edit-pr:: Editing existing Problem Reports
|
|
|
96 * query-pr:: Querying the database
|
|
|
97 * view-pr:: Viewing individual Problem Reports
|
|
|
98 @end menu
|
|
|
99
|
|
|
100 @node send-pr
|
|
|
101 @section Submitting Problem Reports
|
|
|
102 @cindex @code{send-pr}
|
|
|
103 @cindex using @code{send-pr}
|
|
|
104 @cindex invoking @code{send-pr}
|
|
|
105 @cindex reporting problems with @code{send-pr}
|
|
|
106
|
|
|
107 Use @code{send-pr} to submit Problem Reports to the database.
|
|
|
108 @code{send-pr} is both a shell script and a Lisp program for @sc{gnu}
|
|
|
109 Emacs; both implementations provide a template for submitters to
|
|
|
110 complete. In most cases, @code{send-pr} can determine intelligent
|
|
|
111 default values for several fields, partially automating the
|
|
|
112 bug-reporting process.
|
|
|
113
|
|
|
114 @xref{mkdist,,Configuring @code{send-pr} for the outside world}, for
|
|
|
115 information on distributing a version of @code{send-pr} customized with
|
|
|
116 your site's configuration.
|
|
|
117
|
|
|
118 @lowersections
|
|
|
119 @include s-usage.texi
|
|
|
120 @raisesections
|
|
|
121
|
|
|
122 @c ---------------------------------------------------------------
|
|
|
123 @node edit-pr
|
|
|
124 @section Editing existing Problem Reports
|
|
|
125 @cindex using @code{edit-pr}
|
|
|
126 @cindex invoking @code{edit-pr}
|
|
|
127 @cindex @code{edit-pr}
|
|
|
128
|
|
|
129 Use @code{edit-pr} to make changes to existing PRs in the database.
|
|
|
130 @code{edit-pr} is both a shell script and a Lisp program for @sc{gnu}
|
|
|
131 Emacs. Both implementations are essentially identical, though the Emacs
|
|
|
132 interface provides interactive prompting for some of the fields.
|
|
|
133
|
|
|
134 @code{edit-pr} first examines the PR you wish to edit and locks it if it
|
|
|
135 is not already locked. This is to prevent you from editing a PR at the
|
|
|
136 same time as another user. If the PR you wish to edit is already in the
|
|
|
137 process of being edited, @code{edit-pr} tells you the name of the person
|
|
|
138 who owns the lock.
|
|
|
139
|
|
|
140 You may edit any field in the database that you wish. We recommend that
|
|
|
141 you avoid deleting any information in the @sc{Text} and @sc{MultiText}
|
|
|
142 fields (such as @samp{>Description:} and @samp{>How-To-Repeat:}
|
|
|
143 (@pxref{Fields,,Problem Report format}). We also recommend that you
|
|
|
144 record the final solution to the problem in the @samp{>Fix:} field for
|
|
|
145 future reference.
|
|
|
146
|
|
|
147 If you change the @samp{>Responsible:} field, @code{edit-pr} prompts you
|
|
|
148 to supply a reason for the change. @code{edit-pr} then mails copies of
|
|
|
149 the change message to the previous responsible party, and to the new
|
|
|
150 responsible party. The change is then recorded in the
|
|
|
151 @samp{>Audit-Trail:} section of the PR as follows:
|
|
|
152
|
|
|
153 @table @asis
|
|
|
154 @item @code{Responsible-Changed-<From>-<To>}: The value change, supplied
|
|
|
155 automatically by @code{edit-pr}.
|
|
|
156
|
|
|
157 @item @code{Responsible-Changed-By}: Your name here, supplied
|
|
|
158 automatically by @code{edit-pr}.
|
|
|
159
|
|
|
160 @item @code{Responsible-Changed-When}: The current date, supplied
|
|
|
161 automatically by @code{edit-pr}.
|
|
|
162
|
|
|
163 @item @code{Responsible-Changed-Why}: Your reason for the change; you
|
|
|
164 are prompted for this.
|
|
|
165 @end table
|
|
|
166
|
|
|
167 If you change the @samp{>State:} field, you are prompted to supply a
|
|
|
168 reason for the change. Copies of the change message are then mailed to
|
|
|
169 the responsible party, and to the original submitter of the Problem
|
|
|
170 Report. The change is then recorded in the @samp{Audit-Trail} section
|
|
|
171 of the PR as follows:
|
|
|
172
|
|
|
173 @table @asis
|
|
|
174 @item @code{State-Changed-<From>-<To>}: The value change, supplied
|
|
|
175 automatically by @code{edit-pr}.
|
|
|
176
|
|
|
177 @item @code{State-Changed-By}: Your name here, supplied
|
|
|
178 automatically by @code{edit-pr}.
|
|
|
179
|
|
|
180 @item @code{State-Changed-When}: The current date, supplied
|
|
|
181 automatically by @code{edit-pr}.
|
|
|
182
|
|
|
183 @item @code{State-Changed-Why}: Your reason for the change; you are
|
|
|
184 prompted for this.
|
|
|
185 @end table
|
|
|
186
|
|
|
187 The PR is then resubmitted to the database, and the index is updated
|
|
|
188 (@pxref{index file,,The @code{index} file}). For information on
|
|
|
189 @code{pr-edit}, the main driver for @code{edit-pr}, see @ref{Internal
|
|
|
190 utils,,Internal utilities}.
|
|
|
191
|
|
|
192 @menu
|
|
|
193 * edit-pr in Emacs:: Using @code{edit-pr} from within Emacs
|
|
|
194 * edit-pr from the shell:: Invoking @code{edit-pr} from the shell
|
|
|
195 @end menu
|
|
|
196
|
|
|
197 @node edit-pr in Emacs
|
|
|
198 @subsection Using @code{edit-pr} from within Emacs
|
|
|
199 @cindex @code{edit-pr} in Emacs
|
|
|
200
|
|
|
201 Call @code{edit-pr} from within Emacs with @w{@code{M-x
|
|
|
202 edit-pr}}@footnote{If typing @w{@samp{M-x edit-pr}} doesn't work, see
|
|
|
203 your system administrator for help loading @code{edit-pr} into Emacs.}.
|
|
|
204 When @code{edit-pr} prompts you for a PR identification number, type the
|
|
|
205 number of the PR you wish to edit.
|
|
|
206
|
|
|
207 If the PR is locked, Emacs announces the login name of the person who
|
|
|
208 has locked the file. If not, @w{@code{M-x edit-pr}} locks the PR, loads
|
|
|
209 it into a buffer named @samp{*edit-pr*}, and places the cursor in the
|
|
|
210 @samp{>Number:} field. (@emph{Do not change this field}.)
|
|
|
211
|
|
|
212 Edit the PR to reflect correct information. Resubmit the PR to the
|
|
|
213 database using @w{@samp{C-c C-c}} (see below).
|
|
|
214
|
|
|
215 The easiest way to edit a PR from Emacs is to use the special key
|
|
|
216 bindings provided. These are:
|
|
|
217
|
|
|
218 @table @code
|
|
|
219 @item C-c C-c
|
|
|
220 @itemx M-x gnats-submit-pr
|
|
|
221 Saves and resubmits the PR currently being edited. Do this when you
|
|
|
222 finish editing the PR; if you simply kill the buffer, your changes are
|
|
|
223 lost.
|
|
|
224
|
|
|
225 @item C-x C-s
|
|
|
226 @itemx M-x save-buffer
|
|
|
227 Saves the current buffer tp a file. You are prompted for a filename.
|
|
|
228 This is not a special key binding, but at one point in the history of
|
|
|
229 @sc{gnats} it was used to resubmit the PR (i.e., it was bound to
|
|
|
230 @w{@samp{M-x gnats-submit-pr}}). @w{@samp{C-x C-s}} now simply saves a
|
|
|
231 copy of the PR. This command @emph{does not} resubmit the PR to the
|
|
|
232 database. Use @w{@samp{C-c C-c}} to resubmit the PR.
|
|
|
233
|
|
|
234 @item C-x k
|
|
|
235 @itemx M-x gnats:kill-buffer (@emph{use this only with Emacs 18})
|
|
|
236 @itemx M-x kill-buffer
|
|
|
237 Kills the current buffer (destroying all changes) and unlocks the
|
|
|
238 current PR. Use this to back out of a change without affecting the
|
|
|
239 database.
|
|
|
240
|
|
|
241 @item C-c C-u
|
|
|
242 @itemx M-x unlock-pr
|
|
|
243 Unlocks a PR that you have locked. Use this if you have a locked PR
|
|
|
244 from a failed editing session. You are prompted for the @var{gnats-id}
|
|
|
245 of a PR to unlock.
|
|
|
246
|
|
|
247 @item C-c C-q
|
|
|
248 @item M-x unlock-buffer
|
|
|
249 Removes the lock on the current PR, allowing others to edit it. The
|
|
|
250 buffer remains active and non-writeable. To relock a PR, simply type
|
|
|
251 @samp{e} in the buffer containing the Problem Report.
|
|
|
252
|
|
|
253 @item C-c C-e
|
|
|
254 @itemx M-x edit-pr
|
|
|
255 Runs @code{edit-pr} in a new buffer.
|
|
|
256
|
|
|
257 @item C-c C-f
|
|
|
258 @itemx M-x change-field
|
|
|
259 Changes the field under the cursor. @code{edit-pr} prompts you for a
|
|
|
260 new value. If you use
|
|
|
261
|
|
|
262 @smallexample
|
|
|
263 C-u C-c C-f @emph{or}
|
|
|
264 C-u M-x change-field
|
|
|
265 @end smallexample
|
|
|
266
|
|
|
267 @noindent
|
|
|
268 you are prompted for a field to change.
|
|
|
269
|
|
|
270 @item C-c C-a
|
|
|
271 @itemx M-x gnats-mail-reply
|
|
|
272 Sends mail to the originator of this PR, using the address in the
|
|
|
273 @samp{From:} field of the mail header. The @samp{Subject}, @samp{To:},
|
|
|
274 and @samp{Cc:} fields are constructed from the Problem Report currently
|
|
|
275 being edited. Edit the message, and use @w{@samp{C-c C-c}} to send it.
|
|
|
276
|
|
|
277 @item C-c RET
|
|
|
278 @itemx C-c C-m
|
|
|
279 @itemx M-x gnats-mail-other-window
|
|
|
280 Splits the current window, and starts a mail message. The
|
|
|
281 @samp{Subject:} field is constructed from the Problem Report currently
|
|
|
282 being edited. Edit the message, and use @w{@samp{C-c C-c}} to send it.
|
|
|
283
|
|
|
284 @item C-c C-r
|
|
|
285 @itemx M-x gnats-responsible-change-from-to
|
|
|
286 Changes the @samp{>Responsible:} field. @code{edit-pr} prompts you for
|
|
|
287 the new responsible person, and for a message describing the reason for
|
|
|
288 the change. When you type @w{@samp{C-c C-c}} to resubmit the PR, the
|
|
|
289 cursor is placed in a mail buffer containing a copy of the change. You
|
|
|
290 can then edit this buffer and type @w{@samp{C-c C-c}} again to send the
|
|
|
291 mail.
|
|
|
292
|
|
|
293 @item C-c C-s
|
|
|
294 @itemx M-x gnats-state-change-from-to
|
|
|
295 Changes the @samp{>State:} field. @code{edit-pr} prompts you for the
|
|
|
296 new state, and for a message describing the reason for the change. When
|
|
|
297 you type @w{@samp{C-c C-c}} to resubmit the PR, the cursor is placed in
|
|
|
298 a mail buffer containing a copy of the change. You can then edit this
|
|
|
299 buffer and type @w{@samp{C-c C-c}} again to send the mail.
|
|
|
300
|
|
|
301 @item C-c C-t
|
|
|
302 @itemx M-x category-change-from-to
|
|
|
303 Changes the @samp{>Category:} field of the PR. @code{edit-pr} prompts
|
|
|
304 you for the new category. @code{edit-pr} also prompts you with the
|
|
|
305 question
|
|
|
306
|
|
|
307 @smallexample
|
|
|
308 Update the >Responsible field?
|
|
|
309 @end smallexample
|
|
|
310
|
|
|
311 @noindent
|
|
|
312 Type @samp{y} to change the value of the @samp{>Responsible:} field to
|
|
|
313 the name of the party responsible for the new category. Type @samp{n} to
|
|
|
314 keep the current value of @samp{>Responsible:}.
|
|
|
315
|
|
|
316 @c FIXME:
|
|
|
317 @c @item C-c C-f
|
|
|
318 @c @itemx M-x change-field
|
|
|
319 @c what does this routine do?? I can't figure it out from gnats-el.in...
|
|
|
320
|
|
|
321 @item M-C-b
|
|
|
322 @itemx M-x gnats-backward-field
|
|
|
323 Moves the cursor to the beginning of the value of the current field.
|
|
|
324
|
|
|
325 @item M-C-f
|
|
|
326 @itemx M-x gnats-forward-field
|
|
|
327 Moves the cursor to the end of the value of the current field.
|
|
|
328
|
|
|
329 @item M-p
|
|
|
330 @itemx M-x gnats-previous-field
|
|
|
331 Moves the cursor back one field to the beginning of the value of the
|
|
|
332 previous field.
|
|
|
333
|
|
|
334 @item M-n
|
|
|
335 @itemx M-x gnats-next-field
|
|
|
336 Moves the cursor forward one field to the beginning of the value of the
|
|
|
337 next field.
|
|
|
338 @end table
|
|
|
339
|
|
|
340 @node edit-pr from the shell
|
|
|
341 @subsection Invoking @code{edit-pr} from the shell
|
|
|
342 @cindex @code{edit-pr} from the shell
|
|
|
343
|
|
|
344 The usage for the @code{edit-pr} shell script is:
|
|
|
345
|
|
|
346 @smallexample
|
|
|
347 edit-pr @var{gnats-id} [ -V | --version ] [ -h | --help ]
|
|
|
348 @end smallexample
|
|
|
349
|
|
|
350 @noindent
|
|
|
351 You must first determine which PR you want to edit. The options are:
|
|
|
352
|
|
|
353 @table @code
|
|
|
354 @item -V @emph{or} --version
|
|
|
355 Prints the version number for @code{edit-pr}.
|
|
|
356
|
|
|
357 @item -h @emph{or} --help
|
|
|
358 Prints the usage for @code{edit-pr}.
|
|
|
359 @end table
|
|
|
360
|
|
|
361 @code{edit-pr} calls the editor specified in your environment
|
|
|
362 variable @code{EDITOR} on a temporary copy of that PR. (If you don't
|
|
|
363 have the variable @code{EDITOR} defined in your environment, the default
|
|
|
364 editor @code{vi} is used.)
|
|
|
365
|
|
|
366 Edit the PR, changing any relevant fields or adding to existing
|
|
|
367 information. When you exit the editor, @code{edit-pr} prompts you on
|
|
|
368 standard input for a reason if you've changed either the
|
|
|
369 @samp{>Responsible:} field or the @samp{>State:} field. @code{edit-pr}
|
|
|
370 tracks the information you provide when changing either of these two
|
|
|
371 fields, along with the change that occurred, your name, and the time of
|
|
|
372 change in the @samp{>Audit-Trail:} field.
|
|
|
373
|
|
|
374 @c ---------------------------------------------------------------
|
|
|
375 @node query-pr
|
|
|
376 @section Querying the database
|
|
|
377 @cindex using @code{query-pr}
|
|
|
378 @cindex invoking @code{query-pr}
|
|
|
379 @cindex @code{query-pr}
|
|
|
380 @cindex querying invdividual problem reports
|
|
|
381
|
|
|
382 Obtain information from the database by using the program
|
|
|
383 @w{@code{query-pr}}. @code{query-pr} uses search parameters you provide
|
|
|
384 to find matching Problem Reports in the database. You can invoke
|
|
|
385 @code{query-pr} from the shell or from within Emacs. @code{query-pr}
|
|
|
386 uses the same arguments whether it is invoked from the shell or from
|
|
|
387 Emacs.
|
|
|
388
|
|
|
389 All arguments and options to @code{query-pr} are optional. If you do
|
|
|
390 not specify a PR identification number and do not give any search
|
|
|
391 parameters, @code{query-pr} displays the entire database. All arguments
|
|
|
392 are considered identification numbers of Problem Reports to display.
|
|
|
393 Any number of options can be given (though some make no sense when
|
|
|
394 specified on the same command line); all are connected with a logical
|
|
|
395 @code{AND}.
|
|
|
396
|
|
|
397 @menu
|
|
|
398 * Invoking query-pr::
|
|
|
399 * Example queries::
|
|
|
400 * Reporting::
|
|
|
401 @end menu
|
|
|
402
|
|
|
403 @node Invoking query-pr
|
|
|
404 @subsection Invoking @code{query-pr}
|
|
|
405
|
|
|
406 From the shell, simply type @kbd{query-pr}, followed by any search
|
|
|
407 parameters you wish to exercise. From Emacs, type @w{@kbd{M-x
|
|
|
408 query-pr}}. @code{query-pr} prompts you for search parameters in the
|
|
|
409 minibuffer.
|
|
|
410
|
|
|
411 @cindex @code{query-pr} by mail
|
|
|
412 @code{query-pr} can also be accessed by electronic mail, if your version
|
|
|
413 of @sc{gnats} is configured for this. To use this feature, simply send
|
|
|
414 mail to the address @w{@samp{query-pr@@@var{your-site}}} with command
|
|
|
415 line arguments or options in the @samp{Subject:} line of the mail
|
|
|
416 header. @sc{gnats} replies to your mail with the results of your query.
|
|
|
417 The default settings for the @code{query-pr} mail server are
|
|
|
418
|
|
|
419 @cindex the section on query-by-mail needs to be relocated
|
|
|
420 @smallexample
|
|
|
421 --restricted --state="open|analyzed|feedback|suspended"
|
|
|
422 @end smallexample
|
|
|
423
|
|
|
424 @noindent
|
|
|
425 To override the @samp{--state} parameter, specify
|
|
|
426 @w{@samp{--state=@var{state}}} in the @code{Subject:} line of the mail
|
|
|
427 header. You can not query on confidential Problem Reports by mail.
|
|
|
428
|
|
|
429 The usage for @code{query-pr} is:
|
|
|
430
|
|
|
431 @smallexample
|
|
|
432 query-pr [ @var{gnats-id} ]
|
|
|
433 [ -c @var{category} | --category=@var{category} ]
|
|
|
434 [ -s @var{state} | --state=@var{state} ]
|
|
|
435 [ -r @var{responsible} | --responsible=@var{responsible} ]
|
|
|
436 [ -S @var{submitter} | --submitter=@var{submitter} ]
|
|
|
437 [ -C [ @var{yes} | @var{no} ] | --confidential=[ @var{yes} | @var{no} ] ]
|
|
|
438 [ -e @var{severity} | --severity=@var{severity} ]
|
|
|
439 [ -p @var{priority} | --priority=@var{priority} ]
|
|
|
440 [ -O @var{originator} | --originator=@var{originator} ]
|
|
|
441 [ -L @var{class} | --class=@var{class} ]
|
|
|
442 @c [ -k @var{class} | --class=@var{class} ]
|
|
|
443 [ -t @var{text} | --text=@var{text} ]
|
|
|
444 [ -m @var{text} | --multitext=@var{text} ]
|
|
|
445 [ -R | --restricted ]
|
|
|
446 [ -F | --full ] [ -q | --summary ] [ -i | --sql ]
|
|
|
447 [ -P | --print-path ]
|
|
|
448 [ -d @var{directory} | --directory=@var{directory} ]
|
|
|
449 [ -o @var{outfile} | --output=@var{outfile} ]
|
|
|
450 [ -V | --version ] [ -h | --help ]
|
|
|
451 @end smallexample
|
|
|
452
|
|
|
453 If you run @code{query-pr} from within Emacs, you can use
|
|
|
454
|
|
|
455 @smallexample
|
|
|
456 C-x ` @emph{or} M-x next-error
|
|
|
457 @end smallexample
|
|
|
458
|
|
|
459 @noindent
|
|
|
460 to scroll through Problem Reports one by one after the search is
|
|
|
461 finished.
|
|
|
462
|
|
|
463 @subheading Search criteria
|
|
|
464
|
|
|
465 The following arguments and options specify search criteria. The lack
|
|
|
466 of a criterion indicates that all values for the corresponding field are
|
|
|
467 valid for the search. Regular expressions may be used as arguments to
|
|
|
468 search criteria options; see @ref{Regexps,,Querying using regular
|
|
|
469 expressions}.
|
|
|
470
|
|
|
471 Using an argument to @code{query-pr} specifies the most stringent search
|
|
|
472 criteria, that of a single PR.
|
|
|
473
|
|
|
474 @table @code
|
|
|
475 @item @var{gnats-id}
|
|
|
476 The identification number of the PR you wish to view, as shown in the
|
|
|
477 @samp{>Number:} field. Any number of @var{gnats-id} arguments may be
|
|
|
478 given.
|
|
|
479
|
|
|
480 @item -c @var{category}
|
|
|
481 @itemx --category=@var{category}
|
|
|
482 Search only for PRs with a @samp{>Category:} value of @var{category}.
|
|
|
483 For a list of valid categories, type @w{@samp{send-pr -L}} from the
|
|
|
484 shell.
|
|
|
485
|
|
|
486 @item -s @var{state}
|
|
|
487 @itemx --state=@var{state}
|
|
|
488 Search only for PRs with a @samp{>State:} value of @var{state}.
|
|
|
489 @var{state} must be one of: @samp{open}, @samp{analyzed},
|
|
|
490 @samp{feedback}, @samp{closed}, or @samp{suspended}.
|
|
|
491
|
|
|
492 @noindent
|
|
|
493 This field may be searched using regular expressions. @xref{Regexps,,
|
|
|
494 Querying using regular expressions}. Also see @ref{Example
|
|
|
495 queries,,Example queries}.
|
|
|
496
|
|
|
497 @item -r @var{responsible}
|
|
|
498 @itemx --responsible=@var{responsible}
|
|
|
499 Search only for PRs with a @samp{>Responsible:} value of @var{responsible}.
|
|
|
500
|
|
|
501 @item -S @var{submitter}
|
|
|
502 @itemx --submitter=@var{submitter}
|
|
|
503 Search only for PRs with a @samp{>Submitter:} value of @var{submitter}.
|
|
|
504
|
|
|
505 @item -C [@var{yes} | @var{no}]
|
|
|
506 @itemx --confidential=[@var{yes} | @var{no}]
|
|
|
507 Search only for PRs with a @samp{>Confidential:} value of either
|
|
|
508 @var{yes} or @var{no}. If this option is not given, all PRs are
|
|
|
509 eligible for the search regardless of their confidentiality.
|
|
|
510
|
|
|
511 @item -e @var{severity}
|
|
|
512 @itemx --severity=@var{severity}
|
|
|
513 Search only for PRs with a @samp{>Severity:} value of @var{severity}.
|
|
|
514 @var{severity} must be one of: @samp{critical}, @samp{serious}, or
|
|
|
515 @samp{non-critical}.
|
|
|
516
|
|
|
517 @item -p @var{priority}
|
|
|
518 @itemx --priority=@var{priority}
|
|
|
519 Search only for PRs with a @samp{>Priority:} value of @var{priority}.
|
|
|
520 @var{priority} must be one of: @samp{high}, @samp{medium}, or
|
|
|
521 @samp{low}.
|
|
|
522
|
|
|
523 @item -O @var{originator}
|
|
|
524 @itemx --originator=@var{originator}
|
|
|
525 Search only for PRs with an @samp{>Originator:} value of @var{originator}.
|
|
|
526
|
|
|
527 Since this option does not reference the index, queries using it finish
|
|
|
528 much faster if you also use another search criterion that @emph{is} part
|
|
|
529 of the index (@pxref{index file,,The @code{index} file}).
|
|
|
530
|
|
|
531 @item -L @var{class}
|
|
|
532 @itemx --class=@var{class}
|
|
|
533 Search only for PRs with a @samp{>Class:} value of @var{class}.
|
|
|
534 Since this option does not reference the index, queries using it finish
|
|
|
535 much faster if you also use another search criterion that @emph{is} part
|
|
|
536 of the index (@pxref{index file,,The @code{index} file}).
|
|
|
537
|
|
|
538 @ignore
|
|
|
539 @c FIXME - check if these need @w, and make sure this option goes in!
|
|
|
540 @item -k @var{class}
|
|
|
541 @itemx --class=@var{class}
|
|
|
542 Search only for PRs with a @samp{>Class:} value of @var{class}. @var{class}
|
|
|
543 must be one of: @samp{sw-bug}, @samp{doc-bug}, @samp{change-request},
|
|
|
544 @samp{support}, @samp{duplicate}, or @samp{mistaken}.
|
|
|
545
|
|
|
546 Since this option does not reference the index, queries using it finish
|
|
|
547 much faster if you also use another search criterion that @emph{is} part
|
|
|
548 of the index (@pxref{index file,,The @code{index} file}).
|
|
|
549 @end ignore
|
|
|
550
|
|
|
551 @item -t @var{text}
|
|
|
552 @itemx --text=@var{text}
|
|
|
553 Search the @sc{Text} fields in the database for the regular expression
|
|
|
554 @var{text}. @sc{Text} fields include the following (the
|
|
|
555 @samp{>} and @samp{:} Problem Report fieldname delimiters have been
|
|
|
556 removed for the sake of brevity and readability):
|
|
|
557
|
|
|
558 @smallexample
|
|
|
559 @group
|
|
|
560 Submitter-Id Originator Synopsis
|
|
|
561 Category Release Responsible
|
|
|
562 Arrival-Date
|
|
|
563 @end group
|
|
|
564 @end smallexample
|
|
|
565
|
|
|
566 @noindent
|
|
|
567 @xref{Regexps,,Querying using regular expressions}.
|
|
|
568
|
|
|
569 Queries using this option can be slow. Since this option does not
|
|
|
570 reference the index, queries using it finish much faster if you also use
|
|
|
571 another search criterion that @emph{is} part of the index (@pxref{index
|
|
|
572 file,,The @code{index} file}).
|
|
|
573
|
|
|
574 @item -m @var{text}
|
|
|
575 @item --multitext=@var{text}
|
|
|
576 Search the @sc{MultiText} fields in the database for the regular
|
|
|
577 expression @var{text}. @sc{MultiText} fields include the following
|
|
|
578 (again, the fieldname delimiters @samp{>} and @samp{:} have been
|
|
|
579 omitted):
|
|
|
580
|
|
|
581 @smallexample
|
|
|
582 @group
|
|
|
583 Organization Environment Description
|
|
|
584 How-To-Repeat Fix Audit-Trail
|
|
|
585 Unformatted
|
|
|
586 @end group
|
|
|
587 @end smallexample
|
|
|
588
|
|
|
589 @noindent
|
|
|
590 @xref{Regexps,,Querying using regular expressions}.
|
|
|
591
|
|
|
592 Queries using this option can be very slow. Since this option does not
|
|
|
593 reference the index, queries using it finish much faster if you also use
|
|
|
594 another search criterion that @emph{is} part of the index (@pxref{index
|
|
|
595 file,,The @code{index} file}).
|
|
|
596
|
|
|
597 @item -R
|
|
|
598 @itemx --restricted
|
|
|
599 Omit from the search path PRs whose @samp{>Confidential:} fields contain
|
|
|
600 the value @samp{yes}. This is equivalent to
|
|
|
601
|
|
|
602 @smallexample
|
|
|
603 query-pr --confidential=no
|
|
|
604 @end smallexample
|
|
|
605
|
|
|
606 @noindent
|
|
|
607 and also disallows the use of the options
|
|
|
608 @w{@samp{--outfile=@var{outfile}}} and
|
|
|
609 @w{@samp{--directory=@var{directory}}}. This option is used with the
|
|
|
610 @w{@code{mail-query}} tool.
|
|
|
611
|
|
|
612 @item -x
|
|
|
613 @itemx --skip-closed
|
|
|
614 Omit closed PRs from the search path. This option is ignored if you
|
|
|
615 also use @w{@samp{-s @var{state}}} or @samp{--state=@var{state}}.
|
|
|
616 @end table
|
|
|
617
|
|
|
618 @subheading Output format
|
|
|
619
|
|
|
620 Use the following options to select the format in which the Problem
|
|
|
621 Report is printed. Use only one of these options for a given search.
|
|
|
622 If you do not specify one of these options, a header@footnote{A
|
|
|
623 @dfn{header} includes the mail header fields as well as the following
|
|
|
624 fields: @samp{>Number:}, @samp{>Category:}, @samp{>Synopsis:},
|
|
|
625 @samp{>Confidential:}, @samp{>Severity:}, @samp{>Priority:},
|
|
|
626 @samp{>Responsible:}, @samp{>State:}, @samp{>Class:},
|
|
|
627 @samp{>Submitter-Id:}, @samp{>Originator:}, @samp{>Release:}, and
|
|
|
628 @samp{>Arrival-Date:}. For suggestions on using alternate output
|
|
|
629 formats in database reports, see @ref{Reporting,,Reporting}.} for the
|
|
|
630 Problem Reports meeting the search criteria is printed.
|
|
|
631
|
|
|
632 @table @code
|
|
|
633 @item -F
|
|
|
634 @itemx --full
|
|
|
635 Prints all fields in the Problem Report rather than just summary
|
|
|
636 information.
|
|
|
637
|
|
|
638 @item -q
|
|
|
639 @itemx --summary
|
|
|
640 Print a short single-line summary of PR information, delimited by
|
|
|
641 whitespace, including the following fields in order (the @samp{>} and
|
|
|
642 @samp{:} Problem Report fieldname delimiters have been removed for the
|
|
|
643 sake of brevity and readability):
|
|
|
644
|
|
|
645 @smallexample
|
|
|
646 Number Responsible Category
|
|
|
647 State Severity Priority
|
|
|
648 Submitter-Id Synopsis
|
|
|
649 @end smallexample
|
|
|
650
|
|
|
651 @item -i
|
|
|
652 @itemx --sql
|
|
|
653 Prints information on a single line with fields delimited by pipes
|
|
|
654 (@samp{|}), which can be uploaded into a relational database. When you
|
|
|
655 use this option, @code{query-pr} outputs @sc{Enumerated} fields
|
|
|
656 numerically rather than textually; see @ref{Reporting,,Reporting on
|
|
|
657 groups of Problem Reports}.
|
|
|
658
|
|
|
659 @samp{query-pr -i} outputs the following fields, in order (again, the
|
|
|
660 fieldname delimiters @samp{>} and @samp{:} have been omitted):
|
|
|
661
|
|
|
662 @smallexample
|
|
|
663 Number Category Synopsis
|
|
|
664 Confidential Severity Priority
|
|
|
665 Responsible State Class
|
|
|
666 Submitter-Id Arrival-Date Originator
|
|
|
667 Release
|
|
|
668 @end smallexample
|
|
|
669
|
|
|
670 When you use the @samp{-i} option, @samp{query-pr} outputs the
|
|
|
671 @sc{Enumerated} fields in the database, namely @samp{>Severity:},
|
|
|
672 @samp{>Priority:}, @samp{>State:}, and @samp{>Class:}, as numbers rather
|
|
|
673 than text. @xref{Reporting,,Reporting on groups of Problem Reports},
|
|
|
674 for details.
|
|
|
675
|
|
|
676 @end table
|
|
|
677
|
|
|
678 @subheading Other options
|
|
|
679
|
|
|
680 @code{query-pr} also accepts the following options:
|
|
|
681
|
|
|
682 @table @code
|
|
|
683 @item -P
|
|
|
684 @itemx --print-path
|
|
|
685 Prints the path which @code{query-pr} used to find the current PR. A
|
|
|
686 line of the form @samp{@var{directory}/@var{number}:@var{number}} is
|
|
|
687 printed before each PR. This option is automatically used from within
|
|
|
688 Emacs to facilitate scrolling through groups of PRs with @w{@kbd{C-x `}}.
|
|
|
689
|
|
|
690 @item -d @var{directory}
|
|
|
691 @itemx --directory=@var{directory}
|
|
|
692 Changes the search directory to @var{directory} from @var{GNATS_ROOT}.
|
|
|
693
|
|
|
694 @item -o @var{outfile}
|
|
|
695 @itemx --output=@var{outfile}
|
|
|
696 Prints all output to @var{outfile} rather than to the standard output.
|
|
|
697
|
|
|
698 @item -V
|
|
|
699 @itemx --version
|
|
|
700 Prints the version number for @code{query-pr}.
|
|
|
701
|
|
|
702 @item -h
|
|
|
703 @itemx --help
|
|
|
704 Prints the usage for @code{query-pr}.
|
|
|
705 @end table
|
|
|
706
|
|
|
707
|
|
|
708 @node Example queries
|
|
|
709 @subsection Example queries
|
|
|
710 @cindex example queries
|
|
|
711
|
|
|
712 The following simple query:
|
|
|
713
|
|
|
714 @smallexample
|
|
|
715 query-pr --category=rats --responsible=fred --state=analyzed
|
|
|
716 @end smallexample
|
|
|
717
|
|
|
718 @noindent
|
|
|
719 yields all PRs in the database which contain the field values:
|
|
|
720
|
|
|
721 @smallexample
|
|
|
722 >Category: rats @emph{and}
|
|
|
723 >Responsible: fred @emph{and}
|
|
|
724 >State: analyzed
|
|
|
725 @end smallexample
|
|
|
726
|
|
|
727 The following query:
|
|
|
728
|
|
|
729 @smallexample
|
|
|
730 query-pr --state="o|a"
|
|
|
731 @end smallexample
|
|
|
732
|
|
|
733 @noindent
|
|
|
734 yields all PRs in the database whose @samp{>State:} values match either
|
|
|
735 @samp{open} or @samp{analyzed} (@pxref{Regexps,,Querying using regular
|
|
|
736 expressions}. This search is useful as a daily report that lists all
|
|
|
737 Problem Reports which require attention.
|
|
|
738
|
|
|
739 The report can be further altered using an alternate output format for
|
|
|
740 @code{query-pr}; see @ref{Reporting,,Reporting on groups of Problem
|
|
|
741 Reports}. A more fine-grained report may be obtained by specifying more
|
|
|
742 search parameters, e.g. narrowing the search down by
|
|
|
743 @w{@samp{>Submitter:}} or by @samp{>Responsible:}.
|
|
|
744
|
|
|
745 The following query:
|
|
|
746
|
|
|
747 @smallexample
|
|
|
748 query-pr --text="The quick.*brown fox"
|
|
|
749 @end smallexample
|
|
|
750
|
|
|
751 @noindent
|
|
|
752 yields all PRs whose @sc{Text} fields contain the text @samp{The quick}
|
|
|
753 followed by @samp{brown fox} within the same field.
|
|
|
754 @xref{Regexps,,Querying using regular expressions}.
|
|
|
755
|
|
|
756 @node Reporting
|
|
|
757 @subsection Reporting on groups of Problem Reports
|
|
|
758 @cindex reporting
|
|
|
759 @cindex writing reports
|
|
|
760
|
|
|
761 There currently exists no separate reporting mechanism in @sc{gnats} from
|
|
|
762 @code{query-pr}. However, the @samp{-q} and @samp{-i} options to
|
|
|
763 @code{query-pr} allow for easy reporting.
|
|
|
764
|
|
|
765 For example, a report on the current open Problem Reports in the
|
|
|
766 database can be obtained using @code{awk} with
|
|
|
767
|
|
|
768 @smallexample
|
|
|
769 query-pr -q | awk '@{print $3 "/" $1 ": " $4@}'
|
|
|
770 @end smallexample
|
|
|
771
|
|
|
772 @noindent
|
|
|
773 which yields a list of the form
|
|
|
774
|
|
|
775 @smallexample
|
|
|
776 @var{category}/@var{gnats-id}: @var{state}
|
|
|
777 @emph{etc@dots{}}
|
|
|
778 @end smallexample
|
|
|
779
|
|
|
780 @noindent
|
|
|
781 For example:
|
|
|
782
|
|
|
783 @smallexample
|
|
|
784 sprockets/123: open
|
|
|
785 widgets/456: analyzed
|
|
|
786 @emph{etc@dots{}}
|
|
|
787 @end smallexample
|
|
|
788
|
|
|
789 @noindent
|
|
|
790 The @samp{-i} option to @code{query-pr} yields output delimited by pipes
|
|
|
791 (@samp{|}). This results in the following:
|
|
|
792
|
|
|
793 @smallexample
|
|
|
794 @var{gnats-id}|@var{category}|@var{synopsis}|@var{confidential}|\
|
|
|
795 @var{severity}|@var{priority}|@var{responsible}|@var{state}|@var{class}|\
|
|
|
796 @var{submitter-id}|@var{arrival-date}|@var{originator}|@var{release}
|
|
|
797 @end smallexample
|
|
|
798
|
|
|
799 A report on Problem Reports in the database that are currently
|
|
|
800 @samp{open} or @samp{analyzed} might resemble the following (the example
|
|
|
801 is split into two lines in order to fit onto the page; it is intended to
|
|
|
802 be typed on one command line):
|
|
|
803
|
|
|
804 @smallexample
|
|
|
805 query-pr -i -s "o|a" | \
|
|
|
806 awk -F\| '@{print $1 " " $2 " " $8 " " $3@}'
|
|
|
807 @end smallexample
|
|
|
808
|
|
|
809 @noindent
|
|
|
810 which yields
|
|
|
811
|
|
|
812 @smallexample
|
|
|
813 @var{gnats-id} @var{category} @var{state} @var{responsible} @var{synopsis}
|
|
|
814 @emph{etc@dots{}}
|
|
|
815 @end smallexample
|
|
|
816
|
|
|
817 @noindent
|
|
|
818 For example:
|
|
|
819
|
|
|
820 @smallexample
|
|
|
821 123 sprockets 1 fred The sprockets program gives bad output
|
|
|
822 456 widgets 2 barney The foo widget doesn't work with 'bar'
|
|
|
823 789 widgets 1 wilma The 'baz' widget is broken
|
|
|
824 @end smallexample
|
|
|
825
|
|
|
826 @noindent
|
|
|
827 When you use the @samp{-i} option, @samp{query-pr} outputs the
|
|
|
828 @sc{Enumerated} fields in the database, namely @samp{>Severity:},
|
|
|
829 @samp{>Priority:}, @samp{>State:}, and @samp{>Class:}, as numbers rather
|
|
|
830 than text. In the example above, a @samp{>State:} value of @samp{1}
|
|
|
831 means @samp{open}, @samp{2} means @samp{analyzed}, and so forth.
|
|
|
832 @sc{Enumerated} fields are output according to the following paradigm:
|
|
|
833
|
|
|
834 @smallexample
|
|
|
835 >Severity: >Priority:
|
|
|
836 critical 1 high 1
|
|
|
837 serious 2 medium 2
|
|
|
838 non-critical 3 low 3
|
|
|
839
|
|
|
840 >State: >Class:
|
|
|
841 open 1 sw-bug 1
|
|
|
842 analyzed 2 doc-bug 2
|
|
|
843 suspended 3 support 3
|
|
|
844 feedback 4 change-request 4
|
|
|
845 closed 5 mistaken 5
|
|
|
846 duplicate 6
|
|
|
847 @end smallexample
|
|
|
848
|
|
|
849 This makes sorting on these values easy, when combined with @code{sort}.
|
|
|
850 It is left as an exercise for the reader to figure out how to do this.
|
|
|
851
|
|
|
852 @ignore
|
|
|
853 @c it works something like...
|
|
|
854 @smallexample
|
|
|
855 query-pr -i -s "o|a" | \
|
|
|
856 awk -F\| '@{print $8 "|" $1 "|" $2 "|" $3@}' | \
|
|
|
857 sort -n | \
|
|
|
858 awk -F\| '@{if $1 = "1" then \
|
|
|
859 print "Open bugs:\n" $2 " " $3 " " $3@}' \
|
|
|
860 '@{if $1 = "2" then \
|
|
|
861 print "Analyzed bugs:\n" $2 " " $3 " " $3@}'
|
|
|
862 @end smallexample
|
|
|
863 @end ignore
|
|
|
864
|
|
|
865 @node view-pr
|
|
|
866 @section Viewing individual Problem Reports
|
|
|
867 @cindex @code{view-pr} in Emacs
|
|
|
868
|
|
|
869 Use @code{view-pr} from within Emacs to view individual Problem Reports.
|
|
|
870 Invoke @code{view-pr} with
|
|
|
871
|
|
|
872 @smallexample
|
|
|
873 M-x view-pr
|
|
|
874 @end smallexample
|
|
|
875
|
|
|
876 You are prompted to enter a Problem Report identification number
|
|
|
877 (@var{gnats-id}). You can also invoke @code{view-pr} with
|
|
|
878
|
|
|
879 @smallexample
|
|
|
880 C-u @var{gnats-id} M-x view-pr
|
|
|
881 @end smallexample
|
|
|
882
|
|
|
883 @code{view-pr} allows you to view @var{gnats-id}. This is identical to
|
|
|
884 using
|
|
|
885
|
|
|
886 @smallexample
|
|
|
887 C-u @var{gnats-id} M-x query-pr
|
|
|
888 @end smallexample
|
|
|
889
|
|
|
890 except that you may choose to edit the PR at any time by pressing
|
|
|
891 @samp{e}.
|
