[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Invoking the GNATS tools

The following programs comprise GNATS:

User Utilities

These tools are used by the maintainers of a body of work (send-pr is also used by the end users of the product).

send-pr
Used by anyone who has a problem with a body of work to submit a report of the problem to the maintainers of that work (see section Submitting Problem Reports).

query-pr
Used by software maintainers to query the GNATS database (see section Querying the database).

edit-pr
Used by software maintainers to edit Problem Reports (to record new data, to change the responsible party, etc.) (see section Editing existing Problem Reports).

view-pr
Used by software maintainers to view individual Problem Reports using Emacs (see section Viewing individual Problem Reports).

Administrative Utilities

These tools are used by the GNATS administrator; see also GNATS Administration. For complete explanations of these utilities, see Administrative utilities.

mkcat
Creates new categories (see section Adding a problem category).

rmcat
Removes existing categories (see section Removing a problem category).

gen-index
Generates an up-to-date copy of the index used by query-pr and edit-pr (see section The index file). Use gen-index to rebuild the index if it becomes corrupted, or if you need a copy of the current index for some reason (see section Regenerating the index).

mkdist
Creates a distribution of the program send-pr for offsite submitters of PRs (see section Configuring send-pr for the outside world).

Internal Utilities

These tools are used internally by GNATS. You should not need to run these by hand. For complete explanations of these utilities, see Internal utilities.

queue-pr
Handles incoming bugs, first through a mail alias by queueing incoming PRs as they arrive, and second as a periodic transfer agent between the queue and the database.

file-pr
Files Problem Reports as they come in.

at-pr
Sends reminders to maintainers based on quoted response times.

pr-edit
Used by edit-pr to error-check and submit edited Problem Reports (also see section Editing existing Problem Reports).

pr-addr
Used by the edit-pr script to retrieve correct addresses from the `responsible' file.

See section Where GNATS lives.

2.1 Submitting Problem Reports  
2.2 Editing existing Problem Reports  
2.3 Querying the database  
2.4 Viewing individual Problem Reports  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 Submitting Problem Reports

Use send-pr to submit Problem Reports to the database. send-pr is both a shell script and a Lisp program for GNU Emacs; both implementations provide a template for submitters to complete. In most cases, send-pr can determine intelligent default values for several fields, partially automating the bug-reporting process.

See section Configuring send-pr for the outside world, for information on distributing a version of send-pr customized with your site's configuration.

You can invoke send-pr from a shell prompt or from within GNU Emacs using `M-x send-pr'.

2.1.1 Creating new Problem Reports  
2.1.2 Using send-pr from within Emacs  Using send-pr from within Emacs
2.1.3 Invoking send-pr from the shell  Invoking send-pr from the shell
2.1.4 Helpful hints  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.1 Creating new Problem Reports

Invoking send-pr presents a PR template with a number of fields already filled in. Complete the template as thoroughly as possible to make a useful bug report. Submit only one bug with each PR.

A template consists of three sections:

Comments
The top several lines of a blank template consist of a series of comments that provide some basic instructions for completing the Problem Report, as well as a list of valid entries for the `>Category:' field. These comments are all preceded by the string `SEND-PR:' and are erased automatically when the PR is submitted. The instructional comments within `<' and `>' are also removed. (Only these comments are removed; lines you provide that happen to have those characters in them, such as examples of shell-level redirection, are not affected.)

Mail Header
send-pr creates a standard mail header. send-pr completes all fields except the `Subject:' line with default values. (See section Problem Report format.)

GNATS fields
These are the informational fields that GNATS uses to route your Problem Report to the responsible party for further action. They should be filled out as completely as possible. (See section Problem Report format. Also see Helpful hints.)

The default template contains your preconfigured `>Submitter-Id:'. send-pr attempts to determine values for the `>Originator:' and `>Organization:' fields (see section Problem Report format). send-pr will set the `>Originator:' field to the value of the NAME environment variable if it has been set; similarly, `>Organization:' will be set to the value of ORGANIZATION. send-pr also attempts to find out some information about your system and architecture, and places this information in the `>Environment:' field if it finds any.

You may submit problem reports to different Support Sites from the default site by specifying the alternate site when you invoke send-pr. Each site has its own list of categories for which it accepts Problem Reports.

send-pr also provides the mail header section of the template with default values in the `To:', `From:', and `Reply-To:' fields. The `Subject:' field is empty.

The template begins with a comment section:

 
SEND-PR: -*- send-pr  -*-
SEND-PR: Lines starting with `SEND-PR' will be removed
SEND-PR: automatically as well as all comments (the text 
SEND-PR: below enclosed in `<' and `>').
SEND-PR: 
SEND-PR: Please consult the document `Reporting Problems 
SEND-PR: Using send-pr' if you are not sure how to fill out
SEND-PR: a problem report.
SEND-PR:
SEND-PR: Choose from the following categories:

and also contains a list of valid >Category: values for the Support Site to whom you are submitting this Problem Report. One (and only one) of these values should be placed in the >Category: field.

The mail header is just below the comment section. Fill out the `Subject:' field, if it is not already completed using the value of `>Synopsis:'. The other mail header fields contain default values.

 
To: support-site
Subject: complete this field
From: your-login@your-site
Reply-To: your-login@your-site
X-send-pr-version: send-pr 3.101

where support-site is an alias for the Support Site you wish to submit this PR to.

The rest of the template contains GNATS fields. Each field is either automatically completed with valid information (such as your `>Submitter-Id:') or contains a one-line instruction specifying the information that field requires in order to be correct. For example, the `>Confidential:' field expects a value of `yes' or `no', and the answer must fit on one line; similarly, the `>Synopsis:' field expects a short synopsis of the problem, which must also fit on one line. Fill out the fields as completely as possible. See section Helpful hints, for suggestions as to what kinds of information to include.

In this example, words in italics are filled in with pre-configured information:

 
>Submitter-Id: your submitter-id
>Originator:   your name here
>Organization:  
    your organization
>Confidential:<[ yes | no ] (one line)>
>Synopsis:    <synopsis of the problem (one line)>
>Severity:    <[non-critical | serious | critical](one line)>
>Priority:    <[ low | medium | high ] (one line)>
>Category:    <name of the product (one line)>
>Class:       <[sw-bug | doc-bug | change-request | support]>
>Release:     <release number (one line)>
>Environment:
         <machine, os, target, libraries (multiple lines)>

>Description:
       <precise description of the problem (multiple lines)>
>How-To-Repeat:
       <code/input/activities to reproduce (multiple lines)>
>Fix:
       <how to correct or work around the problem, if known 
        (multiple lines)>

When you finish editing the Problem Report, send-pr mails it to the address named in the `To:' field in the mail header. send-pr checks that the complete form contains a valid `>Category:'.

If your PR has an invalid value in one of the ENUMERATED fields (see section Problem Report format), send-pr places the PR in a temporary file named `/tmp/pbadnnnn' on your machine. nnnn is the process identification number given to your current send-pr session. If you are running send-pr from the shell, you are prompted as to whether or not you wish to try editing the same Problem Report again. If you are running send-pr from Emacs, the Problem Report is placed in the buffer `*send-pr-error*'; you can edit this file and then submit it with

 
M-x gnats-submit-pr

Any further mail concerning this Problem Report should be carbon-copied to the GNATS mailing address as well, with the category and identification number in the `Subject:' line of the message.

 
Subject: Re: PR category/gnats-id: original message subject

Messages which arrive with `Subject:' lines of this form are automatically appended to the Problem Report in the `>Audit-Trail:' field in the order received.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.2 Using send-pr from within Emacs

You can use an interactive send-pr interface from within GNU Emacs to fill out your Problem Report. We recommend that you familiarize yourself with Emacs before using this feature (see section `Introduction' in GNU Emacs).

Call send-pr with `M-x send-pr'.(1) send-pr responds with a Problem Report template preconfigured for the Support Site from which you received send-pr. (If you use send-pr locally, the default Support Site is probably your local site.)

You may also submit problem reports to different Support Sites from the default site. To use this feature, invoke send-pr with

 
C-u M-x send-pr

send-pr prompts you for the name of a site. site is an alias on your local machine which points to an alternate Support Site.

send-pr displays the template and prompts you in the minibuffer with the line:

 
>Category: other

Delete the default value `other' in the minibuffer and replace it with the keyword corresponding to your problem (the list of valid categories is in the topmost section of the PR template). For example, if the problem you wish to report has to do with the GNU C compiler, and your support organization accepts bugs submitted for this program under the category `gcc', delete `other' and then type `gcc[RET]'. send-pr replaces the line

 
>Category:       <name of the product (one line)>

in the template with

 
>Category:       gcc

and moves on to another field.

send-pr provides name completion in the minibuffer. For instance, you can also type `gc[TAB]', and send-pr attempts to complete the entry for you. Typing `g[TAB]' may not have the same effect if several possible entries begin with `g'. In that case send-pr cannot complete the entry because it cannot determine whether you mean `gcc' or, for example, `gdb', if both of those are possible categories. send-pr continues to prompt you for a valid entry until you enter one.

send-pr prompts you interactively to enter each field for which there is a range of specific choices. If you attempt to enter a value which is not in the range of acceptable entries, send-pr responds with `[No match]' and allows you to change the entry until it contains an acceptable value. This avoids unusable information (at least in these fields) and also avoids typographical errors which could cause problems later.

send-pr prompts you for the following fields:

 
>Category:
>Confidential: (default:  no)
>Severity:     (default:  serious)
>Priority:     (default:  medium)
>Class:        (default:  sw-bug)
>Release:
>Synopsis:     (this value is copied to Subject:)

After you complete these fields, send-pr places the cursor in the `>Description:' field and displays the message

 
To send the problem report use: C-c C-c

in the minibuffer. At this point, edit the file in the main buffer to reflect your specific problem, putting relevant information in the proper fields.

`send-pr' provides a few key bindings to make moving around in a template buffer more simple:

C-c C-f
M-x change-field
Changes the field under the cursor. edit-pr prompts you for a new value.

M-C-b
M-x gnats-backward-field
Moves the cursor to the beginning of the value of the current field.

M-C-f
M-x gnats-forward-field
Moves the cursor to the end of the value of the current field.

M-p
M-x gnats-previous-field
Moves the cursor back one field to the beginning of the value of the previous field.

M-n
M-x gnats-next-field
Moves the cursor forward one field to the beginning of the value of the next field.

send-pr takes over again when you type `C-c C-c' to send the message. send-pr reports any errors in a separate buffer, which remains in existence until you send the PR properly (or, of course, until you explicitly kill the buffer).

For detailed instructions on using Emacs, see section `Introduction' in GNU Emacs.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.3 Invoking send-pr from the shell

 
send-pr [ site ]
        [ -f problem-report | --file problem-report ]
        [ -t mail-address | --to mail-address ]
        [ --request-id ]
        [ -L | --list ] [ -P | --print ]
        [ -V | --version] [ -h | --help ]

site is an alias on your local machine which points to an address used by a Support Site. If this argument is not present, the default site is usually the site which you received send-pr from, or your local site if you use GNATS locally.

Invoking send-pr with no options calls the editor named in your environment variable EDITOR on a default PR template. If the environment variable PR_FORM is set, its value is used as a file name which contains a valid template. If PR_FORM points to a missing or unreadable file, or if the file is empty, send-pr generates an error message and opens the editor on a default template.

-f problem-report
--file problem-report
Specifies a file, problem-report, where a completed Problem Report already exists. send-pr sends the contents of the file without invoking an editor. If problem-report is `-', send-pr reads from standard input.

-t mail-address
--to mail-address
Sends the PR to mail-address. The default is preset when send-pr is configured. This option is not recommended; instead, use the argument site on the command line.

-c mail-address
--cc mail-address
Places mail-address in the Cc: header field of the message to be sent.

--request-id
Sends a request for a >Submitter-Id: to the Support Site.

-L
--list
Prints the list of valid >Category: values on standard output. No mail is sent.

-s severity
--severity severity
Sets the initial value of the >Severity: field to severity.

-P
--print
Displays the PR template. If the variable PR_FORM is set in your environment, the file it specifies is printed. If PR_FORM is not set, send-pr prints the standard blank form. If the file specified by PR_FORM doesn't exist, send-pr displays an error message. No mail is sent.

-V
--version
Displays the send-pr version number and a usage summary. No mail is sent.

-h
--help
Displays a usage summary for send-pr. No mail is sent.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.4 Helpful hints

There is no orthodox standard for submitting effective bug reports, though you might do well to consult the section on submitting bugs for

GNU gcc in section `Reporting Bugs' in Using and Porting GNU CC, by Richard Stallman. This section contains instructions on what kinds of information to include and what kinds of mistakes to avoid.

In general, common sense (assuming such an animal exists) dictates the kind of information that would be most helpful in tracking down and resolving problems in software.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 Editing existing Problem Reports

Use edit-pr to make changes to existing PRs in the database. edit-pr is both a shell script and a Lisp program for GNU Emacs. Both implementations are essentially identical, though the Emacs interface provides interactive prompting for some of the fields.

edit-pr first examines the PR you wish to edit and locks it if it is not already locked. This is to prevent you from editing a PR at the same time as another user. If the PR you wish to edit is already in the process of being edited, edit-pr tells you the name of the person who owns the lock.

You may edit any field in the database that you wish. We recommend that you avoid deleting any information in the TEXT and MULTITEXT fields (such as `>Description:' and `>How-To-Repeat:' (see section Problem Report format). We also recommend that you record the final solution to the problem in the `>Fix:' field for future reference.

If you change the `>Responsible:' field, edit-pr prompts you to supply a reason for the change. edit-pr then mails copies of the change message to the previous responsible party, and to the new responsible party. The change is then recorded in the `>Audit-Trail:' section of the PR as follows:

Responsible-Changed-<From>-<To>: The value change, supplied
automatically by edit-pr.

Responsible-Changed-By: Your name here, supplied
automatically by edit-pr.

Responsible-Changed-When: The current date, supplied
automatically by edit-pr.

Responsible-Changed-Why: Your reason for the change; you
are prompted for this.

If you change the `>State:' field, you are prompted to supply a reason for the change. Copies of the change message are then mailed to the responsible party, and to the original submitter of the Problem Report. The change is then recorded in the `Audit-Trail' section of the PR as follows:

State-Changed-<From>-<To>: The value change, supplied
automatically by edit-pr.

State-Changed-By: Your name here, supplied
automatically by edit-pr.

State-Changed-When: The current date, supplied
automatically by edit-pr.

State-Changed-Why: Your reason for the change; you are
prompted for this.

The PR is then resubmitted to the database, and the index is updated (see section The index file). For information on pr-edit, the main driver for edit-pr, see Internal utilities.

2.2.1 Using edit-pr from within Emacs  
2.2.2 Invoking edit-pr from the shell  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2.1 Using edit-pr from within Emacs

Call edit-pr from within Emacs with M-x edit-pr(2). When edit-pr prompts you for a PR identification number, type the number of the PR you wish to edit.

If the PR is locked, Emacs announces the login name of the person who has locked the file. If not, M-x edit-pr locks the PR, loads it into a buffer named `*edit-pr*', and places the cursor in the `>Number:' field. (Do not change this field.)

Edit the PR to reflect correct information. Resubmit the PR to the database using `C-c C-c' (see below).

The easiest way to edit a PR from Emacs is to use the special key bindings provided. These are:

C-c C-c
M-x gnats-submit-pr
Saves and resubmits the PR currently being edited. Do this when you finish editing the PR; if you simply kill the buffer, your changes are lost.

C-x C-s
M-x save-buffer
Saves the current buffer tp a file. You are prompted for a filename. This is not a special key binding, but at one point in the history of GNATS it was used to resubmit the PR (i.e., it was bound to `M-x gnats-submit-pr'). `C-x C-s' now simply saves a copy of the PR. This command does not resubmit the PR to the database. Use `C-c C-c' to resubmit the PR.

C-x k
M-x gnats:kill-buffer (use this only with Emacs 18)
M-x kill-buffer
Kills the current buffer (destroying all changes) and unlocks the current PR. Use this to back out of a change without affecting the database.

C-c C-u
M-x unlock-pr
Unlocks a PR that you have locked. Use this if you have a locked PR from a failed editing session. You are prompted for the gnats-id of a PR to unlock.

C-c C-q
M-x unlock-buffer
Removes the lock on the current PR, allowing others to edit it. The buffer remains active and non-writeable. To relock a PR, simply type `e' in the buffer containing the Problem Report.

C-c C-e
M-x edit-pr
Runs edit-pr in a new buffer.

C-c C-f
M-x change-field
Changes the field under the cursor. edit-pr prompts you for a new value. If you use

 
C-u C-c C-f  or
C-u M-x change-field

you are prompted for a field to change.

C-c C-a
M-x gnats-mail-reply
Sends mail to the originator of this PR, using the address in the `From:' field of the mail header. The `Subject', `To:', and `Cc:' fields are constructed from the Problem Report currently being edited. Edit the message, and use `C-c C-c' to send it.

C-c RET
C-c C-m
M-x gnats-mail-other-window
Splits the current window, and starts a mail message. The `Subject:' field is constructed from the Problem Report currently being edited. Edit the message, and use `C-c C-c' to send it.

C-c C-r
M-x gnats-responsible-change-from-to
Changes the `>Responsible:' field. edit-pr prompts you for the new responsible person, and for a message describing the reason for the change. When you type `C-c C-c' to resubmit the PR, the cursor is placed in a mail buffer containing a copy of the change. You can then edit this buffer and type `C-c C-c' again to send the mail.

C-c C-s
M-x gnats-state-change-from-to
Changes the `>State:' field. edit-pr prompts you for the new state, and for a message describing the reason for the change. When you type `C-c C-c' to resubmit the PR, the cursor is placed in a mail buffer containing a copy of the change. You can then edit this buffer and type `C-c C-c' again to send the mail.

C-c C-t
M-x category-change-from-to
Changes the `>Category:' field of the PR. edit-pr prompts you for the new category. edit-pr also prompts you with the question

 
Update the >Responsible field?

Type `y' to change the value of the `>Responsible:' field to the name of the party responsible for the new category. Type `n' to keep the current value of `>Responsible:'.

M-C-b
M-x gnats-backward-field
Moves the cursor to the beginning of the value of the current field.

M-C-f
M-x gnats-forward-field
Moves the cursor to the end of the value of the current field.

M-p
M-x gnats-previous-field
Moves the cursor back one field to the beginning of the value of the previous field.

M-n
M-x gnats-next-field
Moves the cursor forward one field to the beginning of the value of the next field.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2.2 Invoking edit-pr from the shell

The usage for the edit-pr shell script is:

 
edit-pr gnats-id [ -V | --version ] [ -h | --help ]

You must first determine which PR you want to edit. The options are:

-V or --version
Prints the version number for edit-pr.

-h or --help
Prints the usage for edit-pr.

edit-pr calls the editor specified in your environment variable EDITOR on a temporary copy of that PR. (If you don't have the variable EDITOR defined in your environment, the default editor vi is used.)

Edit the PR, changing any relevant fields or adding to existing information. When you exit the editor, edit-pr prompts you on standard input for a reason if you've changed either the `>Responsible:' field or the `>State:' field. edit-pr tracks the information you provide when changing either of these two fields, along with the change that occurred, your name, and the time of change in the `>Audit-Trail:' field.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3 Querying the database

Obtain information from the database by using the program query-pr. query-pr uses search parameters you provide to find matching Problem Reports in the database. You can invoke query-pr from the shell or from within Emacs. query-pr uses the same arguments whether it is invoked from the shell or from Emacs.

All arguments and options to query-pr are optional. If you do not specify a PR identification number and do not give any search parameters, query-pr displays the entire database. All arguments are considered identification numbers of Problem Reports to display. Any number of options can be given (though some make no sense when specified on the same command line); all are connected with a logical AND.

2.3.1 Invoking query-pr  
2.3.2 Example queries  
2.3.3 Reporting on groups of Problem Reports  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.1 Invoking query-pr

From the shell, simply type query-pr, followed by any search parameters you wish to exercise. From Emacs, type M-x query-pr. query-pr prompts you for search parameters in the minibuffer.

query-pr can also be accessed by electronic mail, if your version of GNATS is configured for this. To use this feature, simply send mail to the address `query-pr@your-site' with command line arguments or options in the `Subject:' line of the mail header. GNATS replies to your mail with the results of your query. The default settings for the query-pr mail server are

 
--restricted --state="open|analyzed|feedback|suspended"

To override the `--state' parameter, specify `--state=state' in the Subject: line of the mail header. You can not query on confidential Problem Reports by mail.

The usage for query-pr is:

 
query-pr [ gnats-id ]
         [ -c category | --category=category ]
         [ -s state | --state=state ]
         [ -r responsible | --responsible=responsible ]
         [ -S submitter | --submitter=submitter ]
         [ -C [ yes | no ] | --confidential=[ yes | no ] ]
         [ -e severity | --severity=severity ]
         [ -p priority | --priority=priority ]
         [ -O originator | --originator=originator ]
         [ -L class | --class=class ]
         [ -t text | --text=text ]
         [ -m text | --multitext=text ]
         [ -R | --restricted ]
         [ -F | --full ] [ -q | --summary ] [ -i | --sql ]
         [ -P | --print-path ]
         [ -d directory | --directory=directory ]
         [ -o outfile | --output=outfile ]
         [ -V | --version ] [ -h | --help ]

If you run query-pr from within Emacs, you can use

 
C-x `     or       M-x next-error

to scroll through Problem Reports one by one after the search is finished.

Search criteria

The following arguments and options specify search criteria. The lack of a criterion indicates that all values for the corresponding field are valid for the search. Regular expressions may be used as arguments to search criteria options; see Querying using regular expressions.

Using an argument to query-pr specifies the most stringent search criteria, that of a single PR.

gnats-id
The identification number of the PR you wish to view, as shown in the `>Number:' field. Any number of gnats-id arguments may be given.

-c category
--category=category
Search only for PRs with a `>Category:' value of category. For a list of valid categories, type `send-pr -L' from the shell.

-s state
--state=state
Search only for PRs with a `>State:' value of state. state must be one of: `open', `analyzed', `feedback', `closed', or `suspended'.

This field may be searched using regular expressions. See section Querying using regular expressions. Also see Example queries.

-r responsible
--responsible=responsible
Search only for PRs with a `>Responsible:' value of responsible.

-S submitter
--submitter=submitter
Search only for PRs with a `>Submitter:' value of submitter.

-C [yes | no]
--confidential=[yes | no]
Search only for PRs with a `>Confidential:' value of either yes or no. If this option is not given, all PRs are eligible for the search regardless of their confidentiality.

-e severity
--severity=severity
Search only for PRs with a `>Severity:' value of severity. severity must be one of: `critical', `serious', or `non-critical'.

-p priority
--priority=priority
Search only for PRs with a `>Priority:' value of priority. priority must be one of: `high', `medium', or `low'.

-O originator
--originator=originator
Search only for PRs with an `>Originator:' value of originator.

Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that is part of the index (see section The index file).

-L class
--class=class
Search only for PRs with a `>Class:' value of class. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that is part of the index (see section The index file).

-t text
--text=text
Search the TEXT fields in the database for the regular expression text. TEXT fields include the following (the `>' and `:' Problem Report fieldname delimiters have been removed for the sake of brevity and readability):

 
Submitter-Id   Originator     Synopsis
Category       Release        Responsible
Arrival-Date

See section Querying using regular expressions.

Queries using this option can be slow. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that is part of the index (see section The index file).

-m text
--multitext=text
Search the MULTITEXT fields in the database for the regular expression text. MULTITEXT fields include the following (again, the fieldname delimiters `>' and `:' have been omitted):

 
Organization   Environment    Description
How-To-Repeat  Fix            Audit-Trail
Unformatted

See section Querying using regular expressions.

Queries using this option can be very slow. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that is part of the index (see section The index file).

-R
--restricted
Omit from the search path PRs whose `>Confidential:' fields contain the value `yes'. This is equivalent to

 
query-pr --confidential=no

and also disallows the use of the options `--outfile=outfile' and `--directory=directory'. This option is used with the mail-query tool.

-x
--skip-closed
Omit closed PRs from the search path. This option is ignored if you also use `-s state' or `--state=state'.

Output format

Use the following options to select the format in which the Problem Report is printed. Use only one of these options for a given search. If you do not specify one of these options, a header(3) for the Problem Reports meeting the search criteria is printed.

-F
--full
Prints all fields in the Problem Report rather than just summary information.

-q
--summary
Print a short single-line summary of PR information, delimited by whitespace, including the following fields in order (the `>' and `:' Problem Report fieldname delimiters have been removed for the sake of brevity and readability):

 
Number         Responsible    Category
State          Severity       Priority
Submitter-Id   Synopsis

-i
--sql
Prints information on a single line with fields delimited by pipes (`|'), which can be uploaded into a relational database. When you use this option, query-pr outputs ENUMERATED fields numerically rather than textually; see Reporting on groups of Problem Reports.

`query-pr -i' outputs the following fields, in order (again, the fieldname delimiters `>' and `:' have been omitted):

 
Number         Category       Synopsis
Confidential   Severity       Priority
Responsible    State          Class
Submitter-Id   Arrival-Date   Originator
Release

When you use the `-i' option, `query-pr' outputs the ENUMERATED fields in the database, namely `>Severity:', `>Priority:', `>State:', and `>Class:', as numbers rather than text. See section Reporting on groups of Problem Reports, for details.

Other options

query-pr also accepts the following options:

-P
--print-path
Prints the path which query-pr used to find the current PR. A line of the form `directory/number:number' is printed before each PR. This option is automatically used from within Emacs to facilitate scrolling through groups of PRs with C-x `.

-d directory
--directory=directory
Changes the search directory to directory from GNATS_ROOT.

-o outfile
--output=outfile
Prints all output to outfile rather than to the standard output.

-V
--version
Prints the version number for query-pr.

-h
--help
Prints the usage for query-pr.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.2 Example queries

The following simple query:

 
query-pr --category=rats --responsible=fred --state=analyzed

yields all PRs in the database which contain the field values:

 
>Category:     rats         and
>Responsible:  fred         and
>State:        analyzed

The following query:

 
query-pr --state="o|a"

yields all PRs in the database whose `>State:' values match either `open' or `analyzed' (see section Querying using regular expressions. This search is useful as a daily report that lists all Problem Reports which require attention.

The report can be further altered using an alternate output format for query-pr; see Reporting on groups of Problem Reports. A more fine-grained report may be obtained by specifying more search parameters, e.g. narrowing the search down by `>Submitter:' or by `>Responsible:'.

The following query:

 
query-pr --text="The quick.*brown fox"

yields all PRs whose TEXT fields contain the text `The quick' followed by `brown fox' within the same field. See section Querying using regular expressions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.3 Reporting on groups of Problem Reports

There currently exists no separate reporting mechanism in GNATS from query-pr. However, the `-q' and `-i' options to query-pr allow for easy reporting.

For example, a report on the current open Problem Reports in the database can be obtained using awk with

 
query-pr -q | awk '{print $3 "/" $1 ": " $4}'

which yields a list of the form

 
category/gnats-id: state
etc...

For example:

 
sprockets/123: open
widgets/456: analyzed
etc...

The `-i' option to query-pr yields output delimited by pipes (`|'). This results in the following:

 
gnats-id|category|synopsis|confidential|\
severity|priority|responsible|state|class|\
submitter-id|arrival-date|originator|release

A report on Problem Reports in the database that are currently `open' or `analyzed' might resemble the following (the example is split into two lines in order to fit onto the page; it is intended to be typed on one command line):

 
query-pr -i -s "o|a" | \
  awk -F\| '{print $1 "  " $2 "  " $8 "  " $3}'

which yields

 
gnats-id  category  state  responsible synopsis
etc...

For example:

 
123  sprockets  1  fred    The sprockets program gives bad output
456  widgets    2  barney  The foo widget doesn't work with 'bar'
789  widgets    1  wilma   The 'baz' widget is broken

When you use the `-i' option, `query-pr' outputs the ENUMERATED fields in the database, namely `>Severity:', `>Priority:', `>State:', and `>Class:', as numbers rather than text. In the example above, a `>State:' value of `1' means `open', `2' means `analyzed', and so forth. ENUMERATED fields are output according to the following paradigm:

 
    >Severity:                   >Priority:
critical        1             high            1
serious         2             medium          2 
non-critical    3             low             3

     >State:                      >Class:
open            1             sw-bug          1
analyzed        2             doc-bug         2
suspended       3             support         3
feedback        4             change-request  4
closed          5             mistaken        5
                              duplicate       6

This makes sorting on these values easy, when combined with sort. It is left as an exercise for the reader to figure out how to do this.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4 Viewing individual Problem Reports

Use view-pr from within Emacs to view individual Problem Reports. Invoke view-pr with

 
M-x view-pr

You are prompted to enter a Problem Report identification number (gnats-id). You can also invoke view-pr with

 
C-u gnats-id M-x view-pr

view-pr allows you to view gnats-id. This is identical to using

 
C-u gnats-id M-x query-pr

except that you may choose to edit the PR at any time by pressing `e'.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.