Keeping Track

Managing Messages With GNATS

The GNU Problem Report Management System

Version 3.113

January 1996

Jeffrey M. Osier
Brendan Kehoe
Cygnus Support

Table of Contents

1 Introducing GNATS

Any support organization realizes that a large amount of data flows back and forth between the maintainers and the users of their products. This data often takes the form of problem reports and communication via electronic mail. GNATS addresses the problem of organizing this communication by defining a database made up of archived and indexed electronic mail messages.

GNATS was designed as a tool for software maintainers. It consists of several utilities which, when used in concert, formulate and administer a database of Problem Reports grouped by site-defined problem categories. It allows a support organization to keep track of problems (hence the term Problem Report) in an organized fashion. Essentially, GNATS acts as an active archive for field-separated textual data submitted through electronic mail.

1.1 The database paradigm

It is in your best interest as the maintainer of a body of work to organize the feedback you receive on that work, and to make it easy for users of your work to report problems and suggestions.

GNATS makes this easy by automatically filing incoming problem reports into appropriate places, by notifying responsible parties of the existence of the problem and (optionally) sending an acknowledgement to the submitter that the report was received, and by making these Problem Reports accessible to queries and easily editable. GNATS is a database specialized for a specific task.

GNATS was designed for use at a Support Site that handles a high level of problem-related traffic though electronic mail. It maintains Problem Reports in the form of text files with defined fields (see section 1.4 Problem Report format). The location of the database, as well as the categories it accepts as valid, the maintainers for whom it provides service, and the submitters from whom it accepts Problem Reports, are all definable by the Support Site. See section 3 GNATS Administration.

Each PR is a separate file within a main repository (see section B Where GNATS lives). Editing access to the database is regulated to maintain consistency, but anyone with electronic mail access may submit Problem Reports. To make queries on the database faster, an index is kept automatically (see section 3.3.1 The index file).

We provide several software tools so that users may submit new Problem Reports, edit existing Problem Reports, and query the database.

send-pr can also be packaged by itself and distributed to anyone you wish to receive Problem Reports from; see section 3.4.4 Configuring send-pr for the outside world.

At the Support Site, a GNATS administrator is charged with the duty of maintaining GNATS. These duties are discussed in detail in section 3 GNATS Administration, and generally include configuring GNATS for the Support Site, editing PRs that GNATS cannot process, pruning log files, setting up new problem categories, backing up the database, and distributing send-pr so that others may submit Problem Reports.

Responsibility for a given Problem Report depends on the category of the problem. Optionally, an automated reminder can be sent to the responsible person if a problem report is neglected for a requisite time period. See section 3.2 Changing your local configuration.

GNATS does not have the ability to decipher random text. If there is no default category set, any problem reports which arrive in a format GNATS does not recognize are placed in a separate directory pending investigation by the GNATS administrator (see section 3 GNATS Administration).

Once a problem is recorded in the database, work can begin toward a solution. A problem's initial state is open (see section 1.3 States of Problem Reports). An acknowledgement is sent to the originator of the bug report (if that feature of GNATS is activated). GNATS forwards copies of the report to the party responsible for that problem category and to the person responsible for problems arriving from that Submitter Site.

When a problem has been identified, the maintainer can change its state to analyzed, and then to feedback when a solution is found. Each time the state of a PR changes, the submitter of the problem report is notified of the reason for the change. If the party responsible for the PR changes, the previous responsible party and the new responsible party receive notice of the change. The change and reason are also recorded in the `>Audit-Trail:' field of the Problem Report. (See section 2.7 Editing existing Problem Reports. For information on the `>Audit-Trail:' field, see section 1.4 Problem Report format.)

When the originator of the Problem Report confirms that the solution works, the maintainer can change the state to closed. If the PR cannot be closed, the maintainer can change its state to suspended as a last resort. (For a more detailed description of these states, see section 1.3 States of Problem Reports.)

1.2 Flowchart of GNATS activities

This informal flowchart shows the relationships of the GNATS tools to each other and to the files with which they interoperate.

1.3 States of Problem Reports

Each PR goes through a defined series of states between origination and closure. The originator of a PR receives notification automatically of any state changes.

Unless your site has customized states (see see section 3.2.6 The states file), GNATS uses these states:

open
The initial state of a Problem Report. This means the PR has been filed and the responsible person(s) notified.
analyzed
The responsible person has analyzed the problem. The analysis should contain a preliminary evaluation of the problem and an estimate of the amount of time and resources necessary to solve the problem. It should also suggest possible workarounds.
feedback
The problem has been solved, and the originator has been given a patch or other fix. The PR remains in this state until the originator acknowledges that the solution works.
closed
A Problem Report is closed ("the bug stops here") only when any changes have been integrated, documented, and tested, and the submitter has confirmed the solution.
suspended
Work on the problem has been postponed. This happens if a timely solution is not possible or is not cost-effective at the present time. The PR continues to exist, though a solution is not being actively sought. If the problem cannot be solved at all, it should be closed rather than suspended.

1.4 Problem Report format

The format of a PR is designed to reflect the nature of GNATS as a database. Information is arranged into fields, and kept in individual records (Problem Reports).

A Problem Report contains two different types of fields: Mail Header fields, which are used by the mail handler for delivery, and Problem Report fields, which contain information relevant to the Problem Report and its submitter. A Problem Report is essentially a specially formatted electronic mail message.

Problem Report fields are denoted by a keyword which begins with `>' and ends with `:', as in `>Confidential:'. Fields belong to one of three data types:

ENUMERATED
One of a specific set of values, which vary according to the field. The value for each keyword must be on the same line as the keyword. These values are not configurable (yet). The following fields are ENUMERATED format; see the descriptions of fields below for explanations of each field in detail: 
>Confidential:   >Severity:       >Priority:
>Class:          >State:          >Number:
TEXT
One single line of text which must begin and end on the same line (i.e., before a newline) as the keyword. See the descriptions of fields below for explanations of each field in detail. The following fields are TEXT format: 
>Submitter-Id:   >Originator:     >Synopsis:
>Category:       >Release:        >Responsible:
>Arrival-Date:
MULTITEXT
Text of any length may occur in this field. MULTITEXT may span multiple lines and may also include blank lines. A MULTITEXT field ends only when another keyword appears. See the descriptions of fields below for explanations of each field in detail. The following fields are MULTITEXT format: 
>Organization:   >Environment:    >Description:
>How-To-Repeat:  >Fix:            >Audit-Trail:
>Unformatted:

1.4.1 Example Problem Report

The following is an example Problem Report. Mail headers are at the top, followed by GNATS fields, which begin with `>' and end with `:'. The `Subject:' line in the mail header and the `>Synopsis:' field are usually duplicates of each other. 

Message-Id:  message-id
Date:        date
From:        address
Reply-To:    address
To:          bug-address
Subject:     subject

>Number:       gnats-id
>Category:     category
>Synopsis:     synopsis
>Confidential: yes or no
>Severity:     critical, serious, or non-critical
>Priority:     high, medium or low
>Responsible:  responsible
>State:        open, analyzed, suspended, feedback, or closed
>Class:        sw-bug, doc-bug, change-request, support, 
duplicate, or mistaken
>Submitter-Id: submitter-id
>Arrival-Date: date
>Originator:   name
>Organization: organization
>Release:      release
>Environment:
   environment
>Description:
   description
>How-To-Repeat:
   how-to-repeat
>Fix:
   fix
>Audit-Trail:
appended-messages...
State-Changed-From-To: from-to
State-Changed-When: date
State-Changed-Why:
   reason
Responsible-Changed-From-To: from-to
Responsible-Changed-When: date
Responsible-Changed-Why:
   reason
>Unformatted:
   miscellaneous

1.4.2 Mail header fields

A Problem Report may contain any mail header field described in the Internet standard RFC-822. However, only the fields which identify the sender and the subject are required by send-pr:

To:
The preconfigured mail address for the Support Site where the PR is to be sent, automatically supplied by send-pr.
Subject:
A terse description of the problem. This field normally contains the same information as the `>Synopsis:' field.
From:
Usually supplied automatically by the originator's mailer; should contain the originator's electronic mail address.
Reply-To:
A return address to which electronic replies can be sent; in most cases, the same address as the From: field.

One of the configurable options for GNATS is whether or not to retain `Received-By:' headers, which often consume a lot of space and are not often used. See section 3.2 Changing your local configuration.

1.4.3 Problem Report fields

1.4.4 Field descriptions

The following fields are present whenever a PR is submitted via the program send-pr. GNATS adds additional fields when the PR arrives at the Support Site; explanations of them follow this list.

>Submitter-Id:
(TEXT) A unique identification code assigned by the Support Site. It is used to identify all Problem Reports coming from a particular site. (Submitters without a value for this field can invoke send-pr with the `--request-id' option to apply for one from the support organization. Problem Reports from those not affiliated with the support organization should use the default value of `net' for this field.)
>Originator:
(TEXT) Originator's real name. The default is the value of the originator's environment variable NAME.
>Organization:
(MULTITEXT) The originator's organization. The default value is set with the variable DEFAULT_ORGANIZATION in the `config' file (see section 3.2.2 The config file).
>Confidential:
(ENUMERATED) Use of this field depends on the originator's relationship with the support organization; contractual agreements often have provisions for preserving confidentiality. Conversely, a lack of a contract often means that any data provided will not be considered confidential. Submitters should be advised to contact the support organization directly if this is an issue. If the originator's relationship to the support organization provides for confidentiality, then if the value of this field is `yes' the support organization treats the PR as confidential; any code samples provided are not made publicly available (e.g., in regression test suites). The default value is `yes'.
>Synopsis:
(TEXT) One-line summary of the problem. send-pr copies this information to the `Subject:' line when you submit a Problem Report.
>Severity:
(ENUMERATED) The severity of the problem. Accepted values include:
critical
The product, component or concept is completely non-operational or some essential functionality is missing. No workaround is known.
serious
The product, component or concept is not working properly or significant functionality is missing. Problems that would otherwise be considered `critical' are rated `serious' when a workaround is known.
non-critical
The product, component or concept is working in general, but lacks features, has irritating behavior, does something wrong, or doesn't match its documentation.
The default value is `serious'.

>Priority:
(ENUMERATED) How soon the originator requires a solution. Accepted values include:
high
A solution is needed as soon as possible.
medium
The problem should be solved in the next release.
low
The problem should be solved in a future release.
The default value is `medium'.

>Category:
(TEXT) The name of the product, component or concept where the problem lies. The values for this field are defined by the Support Site. See section 3.2.3 The categories file, for details.
>Class:
(ENUMERATED) The class of a problem can be one of the following:
sw-bug
A general product problem. (`sw' stands for "software".)
doc-bug
A problem with the documentation.
change-request
A request for a change in behavior, etc.
support
A support problem or question.
duplicate (pr-number)
Duplicate PR. pr-number should be the number of the original PR.
mistaken
No problem, user error or misunderstanding. This value is valid only at the Support Site.
The default is `sw-bug'.

>Release:
(TEXT) Release or version number of the product, component or concept.
>Environment:
(MULTITEXT) Description of the environment where the problem occured: machine architecture, operating system, host and target types, libraries, pathnames, etc.
>Description:
(MULTITEXT) Precise description of the problem.
>How-To-Repeat:
(MULTITEXT) Example code, input, or activities to reproduce the problem. The support organization uses example code both to reproduce the problem and to test whether the problem is fixed. Include all preconditions, inputs, outputs, conditions after the problem, and symptoms. Any additional important information should be included. Include all the details that would be necessary for someone else to recreate the problem reported, however obvious. Sometimes seemingly arbitrary or obvious information can point the way toward a solution. See also section 2.6 Helpful hints.
>Fix:
(MULTITEXT) A description of a solution to the problem, or a patch which solves the problem. (This field is most often filled in at the Support Site; we provide it to the submitter in case she has solved the problem.)

GNATS adds the following fields when the PR arrives at the Support Site:

>Number:
(ENUMERATED) The incremental identification number for this PR. This is included in the automated reply to the submitter (if that feature of GNATS is activated; see section 3.2 Changing your local configuration). It is also included in the copy of the PR that is sent to the maintainer. The `>Number:' field is often paired with the `>Category:' field as 
category/number
in subsequent email messages. This is for historical reasons, as well as because Problem Reports are stored in subdirectories which are named by category.
>State:
(ENUMERATED) The current state of the PR. Accepted values are:
open
The PR has been filed and the responsible person notified.
analyzed
The responsible person has analyzed the problem.
feedback
The problem has been solved, and the originator has been given a patch or other fix.
closed
The changes have been integrated, documented, and tested, and the originator has confirmed that the solution works.
suspended
Work on the problem has been postponed.
The initial state of a PR is `open'. See section 1.3 States of Problem Reports.
>Responsible:
(TEXT) The person responsible for this category. GNATS retrieves this information from the `categories' file (see section 3.2.3 The categories file).
>Arrival-Date:
(TEXT) The time that this PR was received by GNATS. The date is provided automatically by GNATS.
>Audit-Trail:
(MULTITEXT) Tracks related electronic mail as well as changes in the `>State:' and `>Responsible:' fields with the sub-fields:
State-Changed-<From>-<To>: oldstate>-<newstate
The old and new `>State:' field values.
Responsible-Changed-<From>-<To>: oldresp>-<newresp
The old and new `>Responsible:' field values.
State-Changed-By: name
Responsible-Changed-By: name
The name of the maintainer who effected the change.
State-Changed-When: timestamp
Responsible-Changed-When: timestamp
The time the change was made.
State-Changed-Why: reason...
Responsible-Changed-Why: reason...
The reason for the change.
The `>Audit-Trail:' field also contains any mail messages received by GNATS related to this PR, in the order received.
>Unformatted: (MULTITEXT) Any random text found outside the fields in the original Problem Report.

2 Invoking the GNATS tools

The following programs comprise GNATS:

2.0.1 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 2.1 Submitting Problem Reports).
query-pr
Used by software maintainers to query the GNATS database (see section 2.8 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 2.7 Editing existing Problem Reports).
view-pr
Used by software maintainers to view individual Problem Reports using Emacs (see section 2.9 Viewing individual Problem Reports).

2.0.2 Administrative Utilities

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

mkcat
Creates new categories (see section 3.4.1 Adding a problem category).
rmcat
Removes existing categories (see section 3.4.2 Removing a problem category).
gen-index
Generates an up-to-date copy of the index used by query-pr and edit-pr (see section 3.3.1 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 3.4.3 Regenerating the index).
mkdist
Creates a distribution of the program send-pr for offsite submitters of PRs (see section 3.4.4 Configuring send-pr for the outside world).

2.0.3 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 section 3.5 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 2.7 Editing existing Problem Reports).
pr-addr
Used by edit-pr to retrieve correct addresses from the `responsible' file.

See section B Where GNATS lives.

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 3.4.4 Configuring send-pr for the outside world, for information on distributing a version of send-pr customized with your site's configuration.

@lowersections

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

2.2 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 1.4 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 1.4 Problem Report format. Also see section 2.6 Helpful hints.)

The default template contains your preconfigured `>Submitter-Id:'. send-pr attempts to determine values for the `>Originator:' and `>Organization:' fields (see section 1.4 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. See section 2.4 Invoking send-pr from the shell. 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.113

where support-site is an alias on your local machine 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 2.6 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 1.4 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.

2.3 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.

2.4 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.

2.5 Submitting a Problem Report via direct e-mail

In addition to using send-pr, there is another way to submit a problem report. You can simply send an e-mail message to the support site.

To do this, look at the address in the `To:' field of the send-pr template. When you send unformatted e-mail to this address, GNATS processes the message as a new problem report, filling in as many fields from defaults as it can:

Synopsis
The `>Synopsis' field is filled in by the `Subject:' header.
Submitter ID
GNATS will try to derive the `>Submitter' field from the address in the `From:' header.
Description
All of the text in the body of the e-mail message is put into the `>Description' field. Each line of the text is indented by one space, indicating that it is "quoted text" from the sender.

Other fields, such as category, version, severity, etc. are set to default values (if the GNATS administrator has set them).

2.6 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.

@raisesections

2.7 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 1.4 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 3.3.1 The index file). For information on pr-edit, the main driver for edit-pr, see section 3.5 Internal utilities.

2.7.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 to a file. You are prompted for a file name. 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-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 gnats: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:'.
C-c C-y
M-x gnats:severity-change-from-to
Changes the `>Severity:' field. edit-pr prompts you for the new severity, 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-p
M-x gnats:priority-change-from-to
Changes the `>Priority:' field. edit-pr prompts you for the new priority, 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-f
M-x gnats: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.
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.

2.7.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.

2.8 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.8.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 ]
         [ -y synopsis | --synopsis=synopsis ]
         [ -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 ]
         [ -A release | --release=release ]
         [ -o outfile | --outfile=outfile ]
         [ -O originator | --originator=originator ]
         [ -L class | --class=class ]
         [ -b date | --arrived-before=date ]
         [ -a date | --arrived-after=date ]
         [ -B date | --modified-before=date ]
         [ -M date | --modified-after=date ]
         [ -z date | --closed-before=date ]
         [ -Z date | --closed-after=date ]
         [ -t text | --text=text ]
         [ -m text | --multitext=text ]
         [ -R | --restricted ] [-x | --skip-closed ]
         [ -F | --full ] [ -q | --summary ] [ -i | --sql ]
         [ -P | --print-path ]
         [ -d directory | --directory=directory ]
         [ -G | --list-config ]
         [ -j | --list-categories ]
         [ -k | --list-responsible ]
         [ -l | --list-submitters ]
         [ -J | --list-classes ]
         [ -T | --list-states ]
         [ -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.

2.8.2 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 section E 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.
-y synopsis
--synopsis=synopsis
Search the >SYNOPSIS: fields in the database for the regular expression synopsis.
-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 E Querying using regular expressions. Also see section 2.8.5 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.
-A release
--release=release
Search the >RELEASE: fields in the database for the regular expression release.
-L class
--class=class
Search only for PRs with a `>Class:' value of class.
-b date
--arrived-before=date
Search only for PRs which arrived before date. These are PRs with an `>Arrival-Date:' value greater than date. Dates can be of several formats, such as `12-Oct-1997', `10/12/97', `19971012', yesterday, "10 days ago", etc.
-a date
--arrived-after=date
Search only for PRs which arrived after date. These are PRs with an `>Arrival-Date:' value less than date.
-B date
--modified-before=date
Search only for PRs which were last modified before date. These are PRs with a `>Last-Modified:' value less than date. PRs which have not been modified (where the `>Last-Modified:' field is blank), are not listed.
-M date
--modified-after date
Search only for PRs which were last modified after date. These are PRs with a `>Last-Modified:' value greater than date. PRs which have not been modified (where the `>Last-Modified:' field is blank), are not listed.
-z date
--closed-before=date
Search only for PRs which were closed before date. These are PRs with a `>Closed-Date:' value less than date. PRs which have not been closed (where the `>Closed-Date:' field is blank), are not listed.
-Z date
--closed-after date
Search only for PRs which were last closed after date. These are PRs with a `>Closed-Date:' value greater than date. PRs which have not been closed (where the `>Closed-Date:' field is blank), are not listed.
-k class
--class=class
Search only for PRs with a `>Class:' value of class. class must be one of: `sw-bug', `doc-bug', `change-request', `support', `duplicate', or `mistaken'.
-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   Last-Modified  Closed-Date
See section E Querying using regular expressions.
-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    Release-Note
See section E Querying using regular expressions. Queries using this option can be very slow. This is the only option that does not reference the index, so queries using it finish much faster if you also use another search criterion that is part of the index (see section 3.3.1 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'.

2.8.3 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. `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        Last-Modified  Closed-Date
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 2.8.6 Reporting on groups of Problem Reports, for details.
-I
--sql2
Prints information identical to the `-i' option, except leading and trailing blanks are squished out of the print for each field.

2.8.4 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.

2.8.5 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 E 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 section 2.8.6 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 E Querying using regular expressions.

2.8.6 Reporting on groups of Problem Reports

Currently, query-pr is the only reporting mechanism in GNATS. 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|\
last-modified|closed-date

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 translations: 

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

     >State:                      >Class:
(unknown)       0             sw-bug          1
open            1             doc-bug         2
analyzed        2             support         3
suspended       3             change-request  4
feedback        4             mistaken        5
closed          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.

Note that the mapping of states to numbers could be different at your site, if the GNATS administrator has changed the list of possible states (see see section 3.2.6 The states file). The state "0" simply means GNATS does not recognize this PR's state. This situation can arise when a PR is assigned a state which is later removed from the list of possible states -- the PR retains the state, but GNATS no longer knows what that state means.

2.9 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'.

3 GNATS Administration

In daily usage, GNATS is self-maintaining. However, there are various administrative duties which need to be performed periodically:

emptying the pending directory
If a Problem Report arrives with a `>Category:' value that is unrecognized by the `categories' file, or if that field is missing, GNATS places the PR in the `pending' directory (see section B Where GNATS lives). GNATS has no way of knowing which subdirectory the PR should be filed under. GNATS sends a notice to the gnats-admin and to the party responsible for that submitter (as listed in the `submitters' file) when this occurs. To file these PRs, simply use edit-pr to repair the problematic fields in each file in the `pending' directory. Be sure to change the `>Category:' field of the PR from `pending' to an appropriate category. In many cases the culprit is simply a typographical error, although it may be necessary sometimes to contact the submitter of the PR to decipher her or his intentions. Should you run out of disk space, there may be an empty PR in the `pending' directory. In that case, look in the file `GNATS_ROOT/gnats-adm/bug.log', which should still contain the full message that was submitted.
adding new categories
To add a new category, simply insert a new line in the `categories' file and then run the program mkcat. Note: this causes all category lists for send-pr (except the one on the local machine) to become outdated. Copy the new list on to every machine on your network that has send-pr installed, and make sure you advise remote submitters that the category list has changed. See section 3.4.1 Adding a problem category. Also section 3.2.3 The categories file.
removing categories
To remove a category, you need to make sure the relevant subdirectory is empty (in other words, make sure no PRs exist for the category you wish to remove). You can then remove the category listing from the `categories' file, and invoke 
rmcat category...
to remove category (any number of categories may be specified on the command line to rmcat, so long as they abide by the above constraints). Note: this causes all category lists for send-pr (except the one on the local machine) to become outdated. Copy the new list on to every machine on your network that has send-pr installed, and make sure you advise remote submitters that the category list has changed. See section 3.4.2 Removing a problem category. Also section 3.2.3 The categories file.
adding and removing maintainers
Edit the `responsible' file to add a new maintainer or to remove an existing maintainer. See section 3.2.4 The responsible file.
building a distribution of send-pr
You can build a distribution of send-pr which contains valid information for your site by invoking the command mkdist. See section 3.4.4 Configuring send-pr for the outside world. You can then distribute your customized send-pr to your customers, friends, relatives, etc., so that they can submit Problem Reports to your database.
building a new index
If your index becomes corrupted, or if you wish to generate a new one for some reason, use the program gen-index (see section 3.4.3 Regenerating the index).
pruning log files
Log files often grow to unfathomable proportions. As with gardening, it is best to prune these as they grow, lest they take over your disk and leave you with no room to gather more Problem Reports. If you keep log files, be sure to keep an eye on them. (See section 3.8 Setting up mail aliases.)
BACKING UP YOUR DATA
Any database is only useful if its data remains uncorrupted and safe. Performing periodic backups ensures that problems like disk crashes and data corruption are reversible.

See section B Where GNATS lives.

3.1 Managing GNATS over a network

If you have installed the GNATS user tools on machines around your local network, there are a few things you need to remember.

mkcat and rmcat do not update the categories list for other machines on your network which have send-pr installed, unless those machines share prefix with the host machine). To update these lists, copy the send-pr categories list to each of the other hosts. This categories list is `prefix/share/gnats/site', where site is the name tag for your local site, as specified in the `config' file as `GNATS_SITE' (see section 3.2.2 The config file).

It is also important to note that only your local send-pr has access to this new information; any copies of send-pr which you have distributed to outside submitters now have outdated category lists. You must either contact your submitters and instruct them to update their copy of the categories list, which they installed in `prefix/share/gnats/support-site' from the distribution you provided, or you must build another distribution of send-pr with this new information and redistribute it.

If you need to use GNATS utilities, like query-pr and edit-pr, on other systems besides the one where GNATS itself resides, see section 3.10 Installing the user tools.

3.2 Changing your local configuration

See section B Where GNATS lives.

Your local configuration is determined by the following data files in the directory `GNATS_ROOT/gnats-adm'. It can be altered at any time by editing the pertinent file.

config
Variables which control certain behavior. See section 3.2.2 The config file. Behaviors you can change here include
categories
The list of categories that GNATS accepts as valid for the `>Category:' field, and the maintainers responsible for each category. Update this file whenever you have a new category, or whenever a category is no longer valid. You must also update this file whenever responsiblility for a category changes, or if a maintainer is no longer valid. See section 3.2.3 The categories file. Also see section 3.4.1 Adding a problem category, and section 3.4.2 Removing a problem category.
responsible
The list of maintainers. Update this file whenever you have a new maintainer, or whenever a maintainer is no longer valid. See section 3.2.4 The responsible file.
submitters
The list of Submitter Sites from whom GNATS accepts Problem Reports. This file is mandatory, although the feature it provides is not; see section 3.2.5 The submitters file.
addresses
Mappings between submitter IDs and submitters' e-mail addresses. Use of this file is optional. If you get Problem reports where the `>Submitter' field is not filled in, GNATS will use entries in this file to try to derive the submitter ID from the e-mail headers.

3.2.1 Default behavior

The default behavior for GNATS is as follows:

3.2.2 The config file

Much of the behavior GNATS exhibits depends on the values of fields in the file `GNATS_ROOT/gnats-adm/config'. The `config' file contains a list of variables (using Bourne-shell syntax) which control the following behavior. These values can be changed at any time; the new values take effect for all subsequent iterations of the tools.

GNATS_ADDR="address"
The address where your site receives Problem Reports. This address is aliased in the file `/etc/aliases' so that it directs incoming mail into queue-pr (see section 3.7 Installing the utilities). The default is `bugs' (a local address).
GNATS_ADMIN="address"
The address of the GNATS administrator. Normally this is set to `gnats-admin', which is an alias in `/etc/aliases' that points toward the person responsible for administrating GNATS. See section 3.7 Installing the utilities. The default is `gnats-admin' (a local address).
GNATS_SITE="site"
The nametag for your Support Site (your organization, company, group, etc.). This nametag should also appear in the `submitters' file, so that users at your site can submit Problem Reports locally. site is also used as the name of the file containing a valid category list for your site. This file is installed locally as `prefix/share/gnats/site'. Warning: if you change this variable after GNATS is installed, you must also change the name of this file, as well as the name of the alias for your local submitters (see section 3.8 Setting up mail aliases). The default is the second-to-last field in your domain name. For example, if your domain name is `unleaded.truckstop.org', your default site is `truckstop'.
SUBMITTER="submitter-id"
The nametag for your local Submitter Site (this value appears as the default value for `>Submitter-Id' when you run send-pr). Even though you are a Support Site, if you submit Problem Reports to your own organization you become a Submitter Site. The value submitter-id is the default value for the `>Submitter-Id:' field that your maintainers see when they submit Problem Reports locally. The default is the value of `GNATS_SITE'.
DEFAULT_RELEASE="release"
The default release for your site (this value appears as the default value for `>Release:' when you run send-pr). The default is `unknown-1.0'.
DEFAULT_ORGANIZATION="text"
The default value for the `>Organization:' field (this value appears as the default when you run send-pr). The default is the value of `GNATS_SITE'.
NOTIFY=boolean
Determines whether or not to remind maintainers if a requisite time period has passed before they change the state of a Problem Report to `analyzed'. This feature uses the program at-pr; see section 3.5.3 Timely reminders. This requisite time is determined for each submitter individually; see section 3.2.5 The submitters file. The time is measured in business hours, which by default are 8:00am to 5:00pm, Monday through Friday. Business hours can be redefined by changing the variables BDAY_START, BDAY_END, BWEEK_START, and BWEEK_END in the `config' file (see below). If boolean is `1', this feature is active. If boolean is `0', the feature is turned off. The default value for `NOTIFY' is `1'.
ACKNOWLEDGE=boolean
Determines whether or not to send an automatic acknowledgement to the originator of a problem report when the GNATS first receives the PR. If boolean is `1', this feature is active. If boolean is `0', the feature is turned off. The default for `ACKNOWLEDGE' is `1'. The acknowledgment is of the form: 
To: your-address
From: gnats
Subject: Re: category/gnats-id:Synopsis
In-Reply-To: Your message of date

Thank you very much for your problem report.
It has the internal identification: category/gnats-id
The individual assigned to look at your bug is:
     responsible

Category:     category of the PR
Responsible:  responsible
Synopsis:     Synopsis from submitted PR
Arrival-Date: arrival date
DEFAULT_SUBMITTER="submitter-id"
The value GNATS assigns to PRs which come in with missing or unknown values for the `>Submitter-Id:' field. This value must also appear in the `submitters' file; see section 3.2.5 The submitters file. To disable the feature of GNATS which tracks the `>Submitter-Id:', simply alter the `submitters' file to only contain the submitter-id value which appears in DEFAULT_SUBMITTER, and and instruct your submitters to ignore the field. The default value for `DEFAULT_SUBMITTER' is `unknown'.
KEEP_RECEIVED_HEADERS=boolean
Determines whether or not GNATS should retain the `Received:' mail headers from incoming mail. These headers often take up a lot of space, and they are seldom used. If boolean is `1', this feature is active. If boolean is `0', the feature is turned off. The default value for `KEEP_RECEIVED_HEADERS' is `1'.
DEBUG_MODE=boolean
Determines whether or not GNATS is operating in a mode for debugging. When boolean is `1', GNATS fowards all mail to the GNATS administrator, gnats-admin.
BDAY_START=integer
BDAY_END=integer
BWEEK_START=integer
BWEEK_END=integer
The definition of business hours. These values are only used if NOTIFY is set to `1' in the `config' file (see above). By default, business hours are 8:00am to 5:00pm Monday through Friday, local time.
BDAY_START=integer
Defines the hour of the day when business hours begin. integer values must fall between `0' (midnight) and `23' (11:00pm). The default is `8' (8:00am).
BDAY_END=integer
Defines the hour of the day when business hours end. integer values must fall between `0' (midnight) and `23' (11:00pm). The default is `17' (5:00pm).
BWEEK_START=integer
Defines the beginning day of the business week. integer values must fall between `0' (Sunday) and `6' (Saturday). The default is `1' (Monday).
BWEEK_END=integer
Defines the ending day of the business week. integer values must fall between `0' (Sunday) and `6' (Saturday). The default is `5' (Friday).
DEFINE_CATEGORY="category"
Defines the category where problem reports are placed when they come in without a category. The category you choose must be listed in the categories file. This line does not appear in the config file when you install GNATS, so you must add it to the config file if you want to set a default category. If there is no default category listed, problem reports will be put into the "pending" category.

3.2.3 The categories file

The `categories' file contains a list of problem categories, specific to your site, which GNATS tracks. This file also matches responsible people with these categories. You must edit this file initially, creating valid categories and then running mkcat to create the corresponding subdirectories of GNATS_ROOT and update the valid categories list for send-pr. For instructions on running mkcat, see section 3.4.1 Adding a problem category.

To create a new category, log in as GNATS, add a line to this file, and run mkcat. Lines beginning with `#' are ignored.

A line in the `categories' file consists of four fields delimited by colons, as follows: 

category:description:responsible:notify

category
A unique category name, made up of text characters. This name cannot contain spaces or any of the following characters: 
! $ & * ( ) { } [ ] ` ' " ; : < > ~
Ideally, category names should not contain commas or begin with periods. Each line has a corresponding subdirectory in the main GNATS directory (GNATS_ROOT).
description
A terse textual description of the category.
responsible
The name tag of the party responsible for this category of problems, as listed in the `responsible' file (see section 3.2.4 The responsible file).
notify
One or more other parties which should be notified when a Problem Report with this category arrives, such as a project manager, other members of the same project, other interested parties, or even log files. These should be separated with commas.

A good strategy for configuring this file is to have a different category for each product your organization supports or wishes to track information for, or perhaps with sub-categories within each category. For instance, if you wish to track documentation problems in a variety of areas, you could have entries such as 

doc:General Doc Questions:myboss:me,barney
doc-rock:Doc for ROCK program:me:myboss
doc-stone:Docs for STONE utils:barney:fred
doc-local:in-house documentation:me:doc-local-log

In the above example, the nametags `myboss', `me', `fred', and `barney' must be defined in the `responsible' file (see section 3.2.4 The responsible file).

Problem Reports with a category of `doc' are sent to the local mail address (or alias) `myboss', and also sent to the addresses `me' and `barney'. PRs with a category of `doc-rock' are sent to the local addresses `me' and `myboss' only, while PRs with the category `doc-stone' are sent to `fred' as well as to `barney'. PRs with a category of `doc-local' are sent only to `me', and are also filed in doc-local-log (in this case, an alias should be set up in `/etc/aliases' to reflect a location for the log file, such as `doc-local-log: /users/me/local-log').

Whenever you add a new category, be sure to run mkcat to create a subdirectory for it and update the local categories list.

Only one category must be present for GNATS to function: 

pending:Category for faulty PRs: gnats-admin:

The `pending' directory is created automatically when you run `make install' (see section 3.6 Configuring and compiling the software).

3.2.4 The responsible file

This file contains a list of the responsible parties. Lines beginning with `#' are ignored. Each entry contains three fields, separated by colons: 

responsible:full-name:mail-address

responsible
A name-tag description of the party in question, such as her or his user name, or the name of the group. This name is listed in the PR in the `>Responsible:' field.
full-name
The full name of the party ("Charlotte Bronte"; "Compiler Group").
mail-address
The full, valid mail address of the party. This field is only necessary if the responsible party has no local mail address or alias.

A sample `responsible' listing might be: 

ren:Ren Hoek:
stimpy:Stimpson J. Cat:stimpy@lederhosen.org

Here, ren is a local user. stimpy is remote, so his full address must be specified.

The following entry must be present for GNATS to function: 

gnats-admin: GNATS administrator:

(gnats-admin is a mail alias, so for this purpose gnats-admin is a local address.)

3.2.5 The submitters file

This is a database of sites which submit bugs to your support site. It contains six fields delineated by colons. Lines beginning with `#' will be ignored.

Entries are of the format: 

submitter-id:name:type:resp-time:contact:notify

submitter-id
A unique identifier for a specific site or other entity who submits Problem Reports.
name
A textual description of this entity.
type
Optional description for the type of relationship this submitter to your support site. This could indicate a contract type, a level of expertise, etc., or it can remain blank.
resp-time
Optional quoted response time, in business hours. GNATS is capable of reminding responsible parties when Problem Reports marked with a `>Severity' value of `critical', or those with a `>Severity' of `serious' and a `>Priority' value of `high', are neglected for a certain period. This argument defines that response period for each submitter-id. Business hours are defined by default as 8:00am to 5:00pm, Monday through Friday. For example, three business days would be equal to 24 business hours. This function is active if the NOTIFY field is defined as `1' in the `config' file (see section 3.2 Changing your local configuration). If NOTIFY is `0', this field is ignored. For information on at-pr, the program which sends out this reminder, see section 3.5.3 Timely reminders.
contact
The name tag of the main contact at the Support Site for this submitter. This contact should be in the `responsible' file (see section 3.2.4 The responsible file). Incoming bugs from submitter are sent to this contact. Optionally, this field can be left blank.
notify
Any other parties who should receive copies of Problem Reports sent in by submitter. They need not be listed in the `responsible' file.

A few example entries in the `submitters' file: 

univ-hell: University of Hades:eternal:3:beelzebub:lucifer
tta: Telephones and Telegraphs of America:support:720:dave:

In this example, when a PR comes in from the University of Hades (who has an eternal contract), it should have `univ-hell' in its `Submitter-Id' field. This Problem Report goes to beelzebub (who should be in the `responsible' file), and if it is not analyzed within three business hours a reminder message is sent. lucifer also receives a copy of the bug, and a copy of the reminder message as well (if it is sent). When Telephones and Telegraphs of America utilizes their support contract and submits a bug, a copy is sent only to dave, who has 720 business hours to return an analysis before a reminder is sent.

To disable the feature of GNATS which tracks the `>Submitter-Id:', simply alter the `submitters' file to only contain the submitter-id value which appears as the `DEFAULT_SUBMITTER' value in the `config' file (see section 3.2.2 The config file), and instruct your submitters to ignore the field.

3.2.6 The states file

This file lists the possible states for Problem Reports. Each line consists of a state, followed optionally by colon and a one-line description of what the state means. Lines beginning with `#' will be ignored. 

state: optional descriptive text

State names can contain any alphanumeric character, "-" (hyphen), "_" (underscore), or "." (period), but no other characters. The state name ends with a newline, or else with a colon followed by optional descriptive text. The descriptive text, if present, can contain any character except newline, which marks the end of the description. Empty or all-whitespace descriptions are allowed (though it's hard to imagine why one would want such a thing). Even though GNATS does not currently use this descriptive text, other external tools may, so you probably still want to include it.

The first state listed will be the state automatically assigned to Problem Reports when they arrive; by default this is named "open". The last state listed is the end state for Problem Reports -- one should usually assume that a PR in this state is not being actively worked on; by default this state is named "closed".

It is probably best to leave "open" as the first state and "closed" as the last, otherwise some external tools looking for those two states by name may be fooled.

If the `states' file cannot be read, or contains formatting errors, GNATS uses the states described in section 1.3 States of Problem Reports.

3.2.7 The addresses file

This file contains mappings between submitter IDs and corresponding e-mail addresses.

When a PR comes in without a submitter ID (if someone sends umformatted e-mail to the "bugs" address), GNATS will try to derive the submitter ID from the address in the "From:" header. The entries in this file consist of two fields, separated by a colon: 

submitter-id:address-fragment

submitter-id
A valid submitter ID
address-fragment
Part of all of the e-mail address to be matched

Here is an example of an addresses file: 

# Addresses for Yoyodine Inc
yoyodine:yoyodine.com
yoyodine:yoyodine.co.uk
# Addresses for Foobar Inc.
foobar1:sales.foobar.com
foobar2:admin.foobar.com
foobar3:clark@research.foobar.com

GNATS checks each line in the addresses file, comparing address-fragment to the end of the "From:" header, until it finds a match. If no match is found, GNATS uses the default submitter ID.

You can only have one address fragment per line, but you can have more than one line for a given submitter ID. An address fragment can be a domain (i.e. yoyodine.com), a machine location (admin.foobar.com), or a full e-mail address (clark@research.foobar.com).

GNATS can match addresses in three e-mail formats:

From: name@address.com
The address by itself without a full name, not enclosed in brackets
From: Real Person <name@address.com>
A full name (optional, with or without quotation marks), followed by the address enclosed in angle brackets
From: name@address.com (Real Person)
An address, followed by a name or comment in parentheses

If GNATS sees other e-mail address formats, it uses the default submitter ID. Future version of this feature will account for other valid e-mail address formats.

3.3 Administrative data files

The following files are located in `GNATS_ROOT/gnats-adm', where GNATS_ROOT is the resident directory of GNATS. These files are maintained by GNATS; you should never touch them.

3.3.1 The index file

The index is used to accelerate searches on the database by query-pr and edit-pr. This file is not created until the first PR comes in. It is then kept up to date by GNATS; you should never touch this file.

Searches on subjects contained in the index are much faster than searches which depend on data not in the index. The index contains single-line entries for all PR fields except for the multitext fields such as Description, How-To-Repeat, etc. Fields are separated by bars (`|') except for `>Category:' and `>Number:', which are separated by a slash (`/').

To see an example index, run gen-index without any options (see section 3.4.3 Regenerating the index).

3.3.2 The current file

This file contains the last serial number assigned to an incoming PR. It is used internally by GNATS; you need never touch this file.

3.4 Administrative utilities

These tools are used by the GNATS administrator as part of the periodic maintenance and configuration of GNATS. See section 3 GNATS Administration.

3.4.1 Adding a problem category

To add new categories to the database:

  1. Add a line to the `categories' file under `GNATS_ROOT/gnats-adm' for each new category. See section 3.2.3 The categories file.
  2. Run mkcat. mkcat creates a directory under GNATS_ROOT for any new categories which appear in the `categories' file. mkcat also recreates the list of valid categories for both your locally installed send-pr and for the send-pr distribution template in `prefix/share/gnats/dist' (see section B Where GNATS lives.

Note: mkcat does not update the categories list for other machines on your network which have send-pr installed (unless the two machines share the directory prefix). See section 3.1 Managing GNATS over a network.

It is also important to note that only your local send-pr has access to this new information; any copies of send-pr which you have distributed to outside submitters now have outdated category lists. You must either contact your submitters and instruct them to update their copy of the categories list, which they installed in `prefix/share/gnats/support-site' (Note: the value for prefix may be different from yours) from the distribution you provided, or you must build another distribution of send-pr with this new information and redistribute it (see section 3.4.4 Configuring send-pr for the outside world).

3.4.2 Removing a problem category

To remove a category from the database:

  1. Remove the Problem Reports from the subdirectories corresponding to the categories you wish to remove, or assign the PRs to new categories. All PRs for a given category reside in `GNATS_ROOT/category'. Make sure you do this for each category you wish to remove.
  2. Run rmcat using 
    rmcat category [ category... ]
    where category is the category you wish to remove. You can specify as many categories as you wish as long as each category has no PRs associated with it. rmcat removes the directory under GNATS_ROOT where the Problem Reports for that category had been stored. rmcat also deletes the category from the list of valid categories for both your locally installed send-pr and for the send-pr distribution template in `prefix/share/gnats/dist' (see section B Where GNATS lives).

Note: rmcat does not update the categories list for other machines on your network which have send-pr installed. See section 3.1 Managing GNATS over a network.

It is also important to note that only your local send-pr has access to this new information; any copies of send-pr which you have distributed to outside submitters now have outdated category lists. You must either contact your submitters and instruct them to update their copy of the categories list, which they installed in `prefix/share/gnats/support-site' (Note: the value for prefix may be different from yours) from the distribution you provided, or you must build another distribution of send-pr with this new information and redistribute it (see section 3.4.4 Configuring send-pr for the outside world).

3.4.3 Regenerating the index

If your `index' file becomes corrupted, or if you need a copy of the current index for some reason, use 

gen-index [ -n | --numeric ]
          [ -d directory | --directory=directory ]
	  [ -c filename | --catfile=filename ]
          [ -o filename | --outfile=filename ]
          [ -h | --help] [ -V | --version ]

With no options, gen-index generates an index that is ordered the same as the order of the categories as they appear in the `categories' file, and prints it to standard output. The options are:

-n
--numeric
Sorts index entries numerically.
-d directory
--directory=directory
Uses directory as the directory containing the database, by default GNATS_ROOT (see section B Where GNATS lives).
-o filename
--outfile=filename
Places output in filename rather than sending it to standard output.
-c filename
--catfile=filename
Point to filename, the file listing the valid categories.
-h
--help
Prints the usage for gen-index.
-V
--version
Prints the version number for gen-index.

3.4.4 Configuring send-pr for the outside world

Now that GNATS is up and running on your system, you probably want to distribute send-pr to all your friends, relatives, enemies, etc. so they can more easily submit bugs to your organization. To do this, create a new directory dist-directory to hold the distribution. Then run the program 

mkdist --release=release dist-directory

This populates dist-directory with a full distribution of the program send-pr, including a `Makefile' and all the send-pr documentation. You can then simply package up this directory and send it to your bug report submitters. For example, when logged in as gnats you can do the following: 

mkdir new-dist
mkdist --release=tools-1.2 new-dist 
tar cvf send-pr.tar new-dist

This creates a file called `send-pr.tar' which contains a full distribution of send-pr customized for your site, with a default release number of `tools-1.2'. You can then place this onto a disk or tape and send it to your submitters, or instruct your submitters to download it using ftp.

If you only have one submitter, you can set the Submitter ID in the send-pr script by specifying the `--submitter' option to mkdist. If you do this, the submitter will not have to run install-sid.

3.5 Internal utilities

These tools are used internally by GNATS. You should never need to run these by hand; however, a complete understanding may help you locate problems with the GNATS tools or with your local implementation.

3.5.1 Handling incoming traffic

The program queue-pr handles traffic coming into GNATS. queue-pr queues incoming Problem Reports in the directory `GNATS_ROOT/gnats-queue', and then periodically (via cron) passes them on to file-pr to be filed in the GNATS database. See section A Installing GNATS.

The usage for queue-pr is as follows: 

queue-pr [ -q | --queue ] [ -r | --run ]
         [ -f filename | --file=filename ]
         [ -d directory | --directory=directory ]

One of `-q' or `-r' (or their longer-named counterparts) must be present upon each call to queue-pr. These options provide different functions, as described below.

-q
--queue
Accepts standard input as an incoming mail message, placing this message in an incrementally numbered file in the `gnats-queue' directory under GNATS_ROOT (see section B Where GNATS lives).
-r
--run
Redirects files in the `gnats-queue' directory into the program file-pr one by one.
-f filename
--file=filename
Used with `-q' (or `--queue'), accepts the file denoted by filename as input rather than reading from standard input.
-d directory
--directory=directory
Resets the default directory value, which is by default `GNATS_ROOT/gnats-queue'. When `-d directory' is used in conjunction with the `-q' (or `--queue') option, queue-pr files incoming messages into directory rather than the `gnats-queue' directory. When `-d directory' is used in conjunction with the `-r' (or `--run') option, queue-pr redirects into file-pr files from directory rather than from the `gnats-queue' directory.

3.5.2 Processing incoming traffic

queue-pr hands off queued Problem Reports to file-pr one at a time. file-pr checks each Problem Report for correct information in its fields (particularly a correct `>Category:'), assigns it an identification number, and files it in the database under the appropriate category.

If the `>Category:' field does not contain a valid category value (i.e., matching a line in the categories file; see section 3.2.3 The categories file), the PR is assigned to the default category, as set in the config file. If there is no default category defined, the PR is given a `>Category:' value of `pending' and is placed in the `pending' directory. The GNATS administrator is notified of the unplaceable PR.

file-pr assigns the Problem Report an identification number, files it in the GNATS database (under the default, if the `>Category:' field contains an invalid category), and sends acknowledgements to appropriate parties. The person responsible for that category of problem (see section 3.2.3 The categories file) and the person responsible for the submitter site where the PR originated (see section 3.2.5 The submitters file) receive a copy of the PR in its entirety. Optionally, the originator of the PR receives an acknowledgement that the PR arrived and was filed (see section 3.2 Changing your local configuration).

The usage for file-pr is as follows: 

file-pr [ -f filename | --file=filename ]
        [ -d directory | --directory=directoryb ]
	[ -D | --debug ] [ -h | --help ] [ -V | --version ]

file-pr requires no options in order to operate, and takes input from standard input (normally, the output of `queue-pr -r') unless otherwise specified. The options include:

-f filename
--filename=filename
Uses filename as input rather than standard input.
-d directory
--directory=directory
Performs refiling operations in directory rather than in GNATS_ROOT.
-D
--debug
Give debugging output while file-pr is running.
-h
--help
Prints the usage for file-pr.
-V
--version
Prints the version number for file-pr.

3.5.3 Timely reminders

at-pr creates a queued job using at which, after an allotted response time is past, checks the PR to see if its state has changed from `open'.

The `submitters' file contains the response time for each >Submitter-Id: (see section 3.2.5 The submitters file). The time is determined in business hours, which are defined by default as 8:00am to 5:00pm Monday through Friday, local time. These hours are defined in the `config' file (see section 3.2.2 The config file).

If the PR is still open after the requisite time period has passed, at-pr sends a reminder to the GNATS administrator, to the maintainer responsible for that submitter, and to the maintainer responsible for the PR with the following message: 

To: submitter-contact responsible gnats-admin
Subject: PR gnats-id not analyzed in #hours hours

PR gnats-id was not analyzed within the acknowledgment period
of #hours business hours.  The pertinent information is:

 Submitter-Id: submitter
 Originator: full name of the submitter
 Synopsis: synopsis
 Person responsible for the PR: responsible

--
The GNU Problem Report Management System (GNATS)

3.5.4 The edit-pr driver

pr-edit does the background work for edit-pr, including error-checking and refiling newly edited Problem Reports and handling file locks. It can be called interactively, though it has no useable editing interface.

The usage for pr-edit is: 

pr-edit [ -l maintainer --lock=maintainer ]
        [ -u | --unlock ] [ -c | --check ] [ -F ]
        [ -L | --lockdb ] [ -U | --unlockdb ]
        [ -f filename | --filename=filename ]
        [ -d directory | --directory=directory ]
        [ -h | --help ] [ -V | --version ]
        [ gnats-id ]

A lock is placed on a Problem Report while the PR is being edited. The lock is simply a file in the same directory as the PR, with the name `gnats-id.lock', which contains the name of the maintainer who created the lock. maintainer then "owns" the lock, and must remove it before the PR can be locked again, even by the same maintainer(4). If a PR is already locked when you attempt to edit it, pr-edit prints an error message giving the name of the maintainer who is currently editing the PR.

If you do not specify gnats-id, pr-edit reads from standard input. You must specify gnats-id for the functions which affect PR locks, `--lock=maintainer' and `--unlock'.

-l maintainer
--lock=maintainer
Locks Problem Report gnats-id, failing (and returning an error message) if gnats-id is already locked, or if gnats-id does not exist. pr-edit requires that you specify gnats-id when using this option.
-u
--unlock
Unlocks Problem Report gnats-id. pr-edit requires that you specify gnats-id when using this option. You must own a file lock to remove it.
-L
--lockdb
Locks the GNATS database as a whole. This will prevent any modification to any part of the system while it's locked.
-U
--unlockdb
Unlocks the GNATS database as a whole, allowing modification of its files.
-c
--check
Checks the Problem Report in gnats-id (or standard input, if gnats-id is not present) for correct information in its ENUMERATED fields. pr-edit complains about any bogus information in the Problem Report.
-F
Forces the PR to be submitted to the database, even if there is no current index entry for it (i.e., even if the PR did not exist in the database previously). Warning: using this option may corrupt your index. If you use it, be sure you know what you are doing.
-f filename
--filename=filename
Reads filename rather than standard input.
-d directory
--directory=directory
Resets the operating directory (GNATS_ROOT).
-h
--help
Prints the usage for pr-edit.
-V
--version
Prints the version number for pr-edit.

3.5.5 Address retrieval

pr-addr returns an electronic mail address when given a valid nametag, as it appears in the `responsible' file (see section 3.2.4 The responsible file). If nametag is not valid, pr-addr will tell the user that it could not find the requested address.

Usage is simply: 

pr-addr name

A Installing GNATS

See section B Where GNATS lives.

There are several steps you need to follow to fully configure and install GNATS on your system. You need root access in order to create a new account for gnats and to install the GNATS utilities. You may need root access on some systems in order to set up mail aliases and to allow this new account access to cron and at.

If you are updating an older version of GNATS rather than installing from scratch, see section 3.11 Upgrading from older versions.

In order to build GNATS, you will need to have GNU m4 installed; most systems ship with a version of m4 that is not able to work with the `config.m4' file.

To build GNATS, you must:

3.6 Configuring and compiling the software

  1. First, unpack your distribution. We provide source code in a tar file which was compressed using gzip. The code can be extracted into a directory unpackdir using 
    cd unpackdir
tar zxvf gnats-3.113.tar.z
    The sources reside in a directory called `gnats-3.113' when unpacked. We call this the top level of the source directory, or srcdir. The sources for the GNATS tools are in the subdirectory `gnats-3.113/gnats/*'. Lists of files included in the distribution are in each directory in the file `MANIFEST'.
  2. You may wish to alter the installation directory for the Emacs lisp files. If your Emacs lisp library is not in `prefix/share/emacs/site-lisp', edit the files 
    srcdir/gnats/Makefile.in   and
srcdir/send-pr/Makefile.in
    Change the variable `lispdir' from `$(datadir)/emacs/site-lisp' to the directory containing your Emacs lisp library. For information on prefix, see section 3.12 prefix.
  3. Run configure. You can nearly always run configure with the command 
    ./configure --with-full-gnats
    and the "Right Thing" happens: The full usage for configure is: 
    configure [ --with-full-gnats ]
          [ --prefix=prefix ]
          [ --exec-prefix=exec-prefix ]
          [ --with-gnats-root=GNATS_ROOT ]
          [ --with-gnats-server=hostname ]
          [ --with-gnats-service=service-name ]
          [ --with-gnats-user=username ]
          [ --with-gnats-port=port-number ]
          [ --verbose ]
    --with-full-gnats
    All programs are to be built; this includes the user utilities, the administrative utilities, and the internal utilities. Use this when configuring the utilities for the machine where GNATS is to run. Omit it when building only the user utilities for other machines on your network; see section 3.10 Installing the user tools.
    --prefix=prefix
    All host-independent programs and files are to be installed under prefix. (Host-dependent programs and files are also installed in prefix by default.) The default for prefix is `/usr/local'. See section B Where GNATS lives.
    --exec-prefix=exec-prefix
    All host-dependent programs and files are to be installed under exec-prefix. The default for exec-prefix is prefix. See section B Where GNATS lives.
    --with-gnats-root=GNATS_ROOT
    The database and its data files are to be installed into GNATS_ROOT. The default for GNATS_ROOT is `prefix/share/gnats/gnats-db'. See section B Where GNATS lives.
    --with-gnats-server=hostname
    Set hostname to be the GNATS network server.
    --with-gnats-service=service-name
    Set service-name to be the GNATS network service.
    --with-gnats-user=username
    Set username to be the user name for GNATS from the passwd file.
    --with-gnats-port=port-number
    Set the server port to be port-number if the service doesn't register.
    --verbose
    Give verbose output while configure runs.
    See section `Using configure' in Cygnus configure. You can build GNATS in a different directory (objdir) from the source code by calling the configure program from the new directory, as in 
    mkdir objdir
cd objdir
srcdir/configure ...
    By default, make compiles the programs in the same directory as the sources (srcdir). Emacs lisp files are byte-compiled if make can find Emacs on your local system.
  4. Run 
    make all info
    from the directory where configure created a `Makefile' (this is objdir if you used it, otherwise srcdir.) These targets indicate:
    all
    Compile all programs
    info
    Create `info' files using makeinfo.

3.7 Installing the utilities

The following steps are necessary for a complete installation. You may need root access for these.

  1. Create an account for a user named gnats. This user must have an entry in the file `/etc/passwd'. The home directory for this account should be the same directory you specified for GNATS_ROOT. Also, the default PATH for this user should contain `exec-prefix/bin' and `exec-prefix/libexec/gnats'.
  2. Install the utilities by invoking 
    make install install-info
    These targets indicate:
    install
    Installs all programs into their configured locations (see section B Where GNATS lives).
    install-info
    Installs `info' files into their configured locations (see section B Where GNATS lives).
    After you have installed GNATS, you can remove the object files with 
    make clean
  3. Place the following lines in the file `default.el' in your Emacs lisp library, or instruct your local responsible parties to place the lines in their `.emacs': 
    (autoload 'edit-pr "gnats" 
   "Command to edit a problem report." t)
(autoload 'view-pr "gnats"
   "Command to view a problem report." t)
(autoload 'unlock-pr "gnats"
   "Unlock a problem report." t)
(autoload 'query-pr "gnats"
   "Command to query information about problem reports." t)
(autoload 'send-pr-mode "send-pr"
   "Major mode for sending problem reports." t)
(autoload 'send-pr "send-pr"
   "Command to create and send a problem report." t)
    Emacs lisp files are byte-compiled if make can find Emacs on your local system.
  4. Allow the new user gnats access to cron and at. To do this, add the name gnats to the files `cron.allow' and `at.allow', which normally reside in the directory `/var/spool/cron'. If these files do not exist, make sure gnats does not appear in either of the files `cron.deny' and `at.deny' (in the same directory). For the following steps, log in as gnats.
  5. Create a crontab entry that periodically runs the program queue-pr with the `--run' option. For example, to run `queue-pr --run' every ten minutes, create a file called `.mycron' in the home directory of the user gnats which contains the line: 
    0,10,20,30,40,50 * * * * exec-prefix/libexec/gnats/queue-pr --run
    (Specify the full path name for queue-pr.) Then run 
    crontab .mycron
    See the man pages for cron and crontab for details on using cron.

3.8 Setting up mail aliases

The following mail aliases must be placed in the file `/etc/aliases' on the same machine where the GNATS tools are installed. You may need root access to add these aliases.

3.9 Installing the daemon

By default, the daemon and clients are set to use port 1529. Add the line 

support		1529/tcp			# GNATS

to your `/etc/services' file. If you want a different port, or a different service name or port, configure GNATS with 

--with-gnats-service=servicename
--with-gnats-port=portnumber

In your `inetd.conf' file, add the line 

support	stream	tcp	nowait	gnats	/usr/local/lib/gnats/gnatsd gnatsd

adjusting the path accordingly. To make inetd start spawning the GNATS daemon when connected on that port, send it a hangup signal (HUP).

By default, the server for the GNATS daemon is assumed to be one with the name of `gnats'. If you'd like something else, use 

--with-gnats-server=hostname

In the `gnats-adm' directory, you'll want to edit `gnatsd.conf'. It lists the hosts allowed to access your server and their default access level. Or, if you're using Kerberos, it shows the sites that don't require Kerberos authentication. The format is reserved for future revision; only the first two fields are actually used: 

site.com:view:

The third field might in the future be used for things like controlling what categories, submitter-id'd PRs, etc., can be accessed from that site. In the file that logs syslog messages (`/var/adm/messages', for example) you'll find the notification of denied access.

3.10 Installing the user tools

When you install the GNATS utilities, the user tools are installed by default on the host machine. If your machine is part of a network, however, you may wish to install the user tools on each machine in the network so that responsible parties on those machines can submit new Problem Reports, query the database, and edit existing PRs. To do this, follow these steps on each new host. You may need root access on each machine.

  1. Make sure that the directory where GNATS resides is mounted to each system that will need access to it, so GNATS_ROOT will be the same for each host. (You can do this with symbolic links as well.)
  2. Either mount the disk which contains your source directory, or make a copy of the GNATS source code tree in a separate directory on each system you wish to build on.
  3. Run configure, without specifying `--with-full-gnats', and using the same argument (if any) for the option 
    --with-gnats-root=GNATS_ROOT
    that you specified when building the GNATS utilites (see section 3.6 Configuring and compiling the software). You may use different values for the other options to configure. Again, do not use `--with-full-gnats' at this point, as that creates all the GNATS programs. Without this option, configure only instructs the resulting `Makefile' to create the user utilities. You may need root access on each host for the following steps.
  4. Create an account for a user named GNATS on the new host. This user must have an entry in the file `/etc/passwd'. The user ID for gnats must be the same as on the main GNATS host.
  5. Run 
    make all info install install-info
    This builds and installs the gnats user tools query-pr, edit-pr, and send-pr on the new host, and installs them in `exec-prefix/bin' on the new host (Note: the value for exec-prefix on the new host may be different from the value you used when building the GNATS utilities; see section 3.13 exec-prefix). The programs pr-edit and pr-addr are installed into `exec-prefix/libexec/gnats'. info files are created as well, and are installed into `prefix/info'. The Elisp files `gnats.el' and `send-pr.el' (and possibly `gnats.elc' if make was able to compile them using Emacs) are installed into `prefix/share/emacs/site-lisp' unless you change the `lispdir' variable in `Makefile.in' (see section 3.6 Configuring and compiling the software).
  6. Add the following lines to the file `default.el' in the Emacs lisp repository on the new host, or instruct your responsible parties who use these hosts to add them to their `.emacs' files: 
    (autoload 'edit-pr "gnats"
   "Command to edit a problem report." t)
(autoload 'view-pr "gnats"
   "Command to view a problem report." t)
(autoload 'unlock-pr "gnats"
   "Unlock a problem report." t)
(autoload 'query-pr "gnats"
   "Command to query information about problem reports." t)
(autoload 'send-pr-mode "send-pr"
   "Major mode for sending problem reports." t)
(autoload 'send-pr "send-pr"
   "Command to create and send a problem report." t)
  7. Copy the file `prefix/share/gnats/site' from the original host to the new host (which may have a different value for prefix). This is the list of valid categories that send-pr uses (see section B Where GNATS lives). site is your local site, the value of `GNATS_SITE' in the `config' file (see section 3.2.2 The config file).

3.11 Upgrading from older versions

If you are upgrading from a previous release of GNATS, you probably do not want to delete your current configuration files or your current database. The new GNATS can be installed around the older version.

You need to:

B Where GNATS lives

We use a few conventions when referring to the installation structure GNATS uses. These values are adjustable when you build and install GNATS (see section A Installing GNATS).

3.12 prefix

prefix corresponds to the variable `prefix' for configure, which passes it on to the `Makefile' it creates. prefix sets the root installation directory for host-independent files as follows:

configuration and database files
`prefix/share'
man pages
`prefix/man'
info documents
`prefix/info'
include files
`prefix/include'
etc...

The default value for prefix is `/usr/local', which can be changed on the command line to configure using 

configure --prefix=prefix ...

See section 3.6 Configuring and compiling the software.

3.13 exec-prefix

exec-prefix corresponds to the variable `exec_prefix' for configure, which passes it on to the `Makefile' it creates. exec-prefix sets the root installation for host-dependent files as follows:

binary tools
`exec-prefix/bin'
binary support utilities
`exec-prefix/libexec/gnats'
compiled libraries
`exec-prefix/lib'
etc...

Since most installations are not intended to be distributed around a network, the default value for exec-prefix is the value of `prefix', i.e., `/usr/local'. However, using exec-prefix saves space when you are installing a package on several different platforms for which many files are identical; rather than duplicate them for each host, these files can be shared in a common repository, and you can use symbolic links on each host to find the host-dependent files. It is not necessary to use this paradigm when building the GNATS tools. See section 3.6 Configuring and compiling the software.

Use exec-prefix in conjunction with prefix to share host-independent files, like libraries and info documents. For example: 

   for each host:
configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-host
make all install ...

Using this paradigm, all host-dependent binary files are installed into `/usr/gnu/H-host/bin', while files which do not depend on the host type for which they were configured are installed into `/usr/gnu'.

You can then use a different symbolic link for `/usr/gnu' on each host (`/usr' is usually specific to a particular machine; it is always specific to a particular architecture). 

  on host-1:
ln -s /usr/gnu/H-host-1 /usr/gnu
  on host-2:
ln -s /usr/gnu/H-host-2 /usr/gnu

To the end user, then, placing `/usr/gnu/bin' in her or his PATH simply works transparently for each host type.

You can change exec-prefix on the command line to configure using 

configure --exec-prefix=exec-prefix ...

We recommend that you consult section `Using configure' in Cygnus configure, before attempting this. Again, it is not necessary to use this paradigm when building the GNATS tools.

3.14 GNATS_ROOT

The location of the database and the administrative data files, by default `prefix/share/gnats/gnats-db'. You can change this value on the command line to configure using 

configure --with-gnats-root=GNATS_ROOT

Administrative data files reside in `GNATS_ROOT/gnats-adm'. These include `categories', `submitters', `responsible', `states', and `config', as well as two files generated and maintained by GNATS, `index' and `current'. See section 3.2 Changing your local configuration, and section 3.3 Administrative data files.

3.15 Default installation locations

prefix
defaults to `/usr/local'; change using configure (see section 3.6 Configuring and compiling the software).
exec-prefix
defaults to prefix; change using configure (see section 3.6 Configuring and compiling the software).
GNATS_ROOT
defaults to `prefix/share/gnats/gnats-db'; change using configure (see section 3.6 Configuring and compiling the software).

GNATS installs tools, utilities, and files into the following locations.

exec-prefix/bin
send-pr
See section 2.1 Submitting Problem Reports.
edit-pr
See section 2.7 Editing existing Problem Reports.
query-pr
See section 2.8 Querying the database.
nquery-pr
See section 2.8 Querying the database.
exec-prefix/libexec/gnats
mkcat
See section 3.4.1 Adding a problem category.
rmcat
See section 3.4.2 Removing a problem category.
mkdist
See section 3.4.4 Configuring send-pr for the outside world.
gen-index
See section 3.4.3 Regenerating the index.
queue-pr
See section 3.5.1 Handling incoming traffic.
file-pr
See section 3.5.2 Processing incoming traffic.
at-pr
See section 3.5.3 Timely reminders.
pr-edit
See section 3.5.4 The edit-pr driver.
pr-addr
See section 3.5.5 Address retrieval.
exec-prefix/lib/libiberty.a
The GNU libiberty library.
prefix/share/gnats/dist
A packageable distribution of send-pr.
See section 3.4.4 Configuring send-pr for the outside world.
prefix/share/gnats
site
The local list of valid categories, used by send-pr; site is the value of `GNATS_SITE' (see section 3.2.2 The config file).
prefix/share/emacs/site-lisp
gnats.el
gnats.elc
The Emacs versions of the programs query-pr, edit-pr, and view-pr. See section 2 Invoking the GNATS tools. To change this directory you must alter `Makefile.in'; see section 3.6 Configuring and compiling the software.
send-pr.el
The Emacs version of the program send-pr. See section 2.1 Submitting Problem Reports.
prefix/info
gnats.info
send-pr.info
The GNATS manuals, in a form readable by info (the GNU hypertext browser). See section `Reading GNU Online Documentation' in GNU Online Documentation.
prefix/man/man1
prefix/man/man8
man pages for all the GNATS tools and utilities.
See section 2 Invoking the GNATS tools.
GNATS_ROOT
gnats-adm
Administration and configuration data files. The files
config
categories
submitters
responsible
states
gnatsd.conf
index
(This file is created by GNATS.)
current
(This file is created by GNATS.)
exist here. See section 3.2 Changing your local configuration, and section 3.3 Administrative data files.
gnats-queue
Incoming Problem Reports are queued here until the next iteration of `queue-pr -r' (see section 3.5.1 Handling incoming traffic).
pending
If no default category is set, problem reports without a category are reassigned to the category `pending' and placed here pending intervention by the GNATS administrator. In this case, the submitter will not receive an automated reply. See section 3 GNATS Administration.
category
Each valid category has a corresponding subdirectory in the database. All Problem Reports associated with that category are kept in that subdirectory, along with lock files for PRs which are being edited.

C Multiple Databases on one host

GNATS can support multiple databases on one host. The options --directory= or -d are available to specify the GNATS database to access for the various tools See section 2 Invoking the GNATS tools.

The GNATS daemon can switch between databases by using the CHDB database command. This will cause the GNATS daemon to access the newly specified database. The daemon will verify that you have access to the requested database as determined by `gnatsd.conf'.

The database should be specified using a fully qualified path name. The file `/etc/gnats-db.conf' can be used to specify aliases for the fully qualified path names. These aliases can be used with the --directory= or -d option or as a database name for the daemon. The following is an example of a `/etc/gnats-db.conf' file. 

# list of GNATS databases and alaises
#
# Field 1 - fully qualified path to database
# Field 2 - a comma separated list of aliases
/usr/local/gnats/standard-db:normal,standard,regular
/usr/local/gnats/alternate-db:alt
/home/gnats/special-db:special

The `/etc/gnats-db.conf' file name is set in `db_conf.c' at compile time.

The GNATS daemon supports two other commands DBLS and DBLA to list the fully qualified databases and aliases, respectively.

D Controlling access to databases

GNATS supports granting various levels of access to the GNATS databases served by the network daemon, GNATSD.

GNATS access can be controlled at these levels: 

deny     - gnatsd closes the connection
none     - no further access until userid and password given
view     - query and view PRs with Confidential=no only
viewconf - query and view PRs with Confidential=yes
edit     - full edit  access
admin    - full admin access (not currently used)

There are three main features: 

- security by obscurity, defined in the next paragraph
- access level set by host name or IP address
- access level set by userid and password

gnatsd has parameters -r or --require-db. If so executed, nobody gets in unless they are able to ask for a database by alias name with the CHDB (change database) command. If you specify an incorrect database alias the connection is closed. Only the CHDB command is allowed, and you just get one try.

The second field of the `gnats-adm/gnatsd.conf' file is the access level for the user's host. The default is edit to be compatable with previous releases of gnats. If the user's hostname isn't in the `gnatsd.conf' file or its access level is deny, the connection is closed immediately.

Whenever a CHDB command is processed (or defaulted), the user's access level is set to the level for their host.

Even if a host is given the none access, an individual can still give the USER command to possibly gain a higher (but never lower) access than is set for their host. The gnatsd USER command takes two arguments: USER <userid> <passwd>.

An optional file `gnats-adm/gnatsd.access' specifies the user access rules. If it doesn't exist, or doesn't contain the user name given to gnatsd, then `/etc/gnatsd.access' is also checked. This filename is set in `config.c' at compile time.

If the access level is none after processing the userid and password, the connection is closed.

The `gnatsd.access' file is clear text, but it is installed to be owned by the GNATS user with file permission 600.

Wildcard characters are supported for the userid and password. A null string or "*" matches anything; "?" matches any one character.

A `gnatsd.access' file might look like this: 

# field 1: user
# field 2: passwd
# field 3: access   (valid entries: deny, none, view, viewconf, edit, admin)
# field 4: database (/etc/gnatsd.access only; ignored in gnatsd-adm)
rickm:ruckm:edit:*
pablo:pueblo:view:*
*:*:none

In this example, anybody other than rickm and pablo get denied access, assuming that the host access level is also none. You could set the catch-all rule at the end to be *:*:view to allow view access to anyone.

The fourth field is a comma-separated list of database aliases to match alias entries from the second field of the database file `/etc/gnats-db.conf'. Wildcard characters are supported. This field is only used in `/etc/gnatsd.access'. It's ignored in `gnatsd-adm/gnatsd.access' since this file is already database specific.

Every gnatsd command has a minimum access level attached to it. If your access level is too low for a command, you get this response: 

  LOCK 12 rickm
  520 You are not authorized to perform this operation (LOCK).

These commands, along with all of the query constraint setting commands (PRIO, SYNP, etc) are unrestricted: HELO, QUIT, AUTH, USER, CHDB and VDAT.

A user must have at least edit access for these commands: 

   LKDB                    lock the main GNATS database
   UNDB                    unlock the main GNATS database
   LOCK <PR> <user> <pid>  lock <PR> for <user> and optional <pid> and
                           return PR text
   UNLK <PR>               unlock <PR>
   EDIT <PR>               check in edited <PR>

All other commands require view access.

The DBLS and DBLA commands (list databases and aliases) require view access but still only list databases to which the user's host has at least none access. A user might have view access on one database and be able to list the other database names, but upon executing CHDB find that they have none access to the second database and not be able to execute anything other than another CHDB.

nedit-pr, npr-edit, nquery-pr and sub-type all have the command line args -v|--user and -w|--passwd. gnatsd only accepts database alias names for the -d|--directory arg from these commands (not full database pathnames). Local clients (query-pr, mkcat, etc) accept either.

E Querying using regular expressions

GNATS uses GNU regular expression syntax with these settings: 

RE_SYNTAX_POSIX_EXTENDED | RE_BK_PLUS_QM & RE_DOT_NEWLINE

This means that parentheses (`(' and `)') and pipe symbols (`|') do not need to be used with the escape symbol `\'. The tokens `+' and `?' do need the escape symbol, however.

Unfortunately, we do not have room in this manual for an adequate tutorial on regular expressions. The following is a basic summary of some regular expressions you might wish to use.

See section `Regular Expression Syntax' in Regex, for details on regular expression syntax. Also see section `Syntax of Regular Expressions' in GNU Emacs Manual, but beware that the syntax for regular expressions in Emacs is slightly different.

All search criteria options to query-pr rely on regular expression syntax to construct their search patterns. For example, 

query-pr --state=open

matches all PRs whose `>State:' values match with the regular expression `open'.

We can substitute the expression `o' for `open', according to GNU regular expression syntax. This matches all values of `>State:' which begin with the letter `o'. 

query-pr --state=o

is equivalent to 

query-pr --state=open

in this case, since the only value for `>State:' which matches the expression `o' is `open'. (Double quotes (") are used to protect the asterix (*) from the shell.) `--state=o' also matches `o', `oswald', and even `oooooo', but none of those values are valid states for a Problem Report.

Regular expression syntax considers a regexp token surrounded with parentheses, as in `(regexp)', to be a group. This means that `(ab)*' matches any number of contiguous instances of `ab', including zero. Matches include `', `ab', and `ababab'.

Regular expression syntax considers a regexp token surrounded with square brackets, as in `[regexp]', to be a list. This means that `Char[(ley)(lene)(broiled)' matches any of the words `Charley', `Charlene', or `Charbroiled' (case is significant; `charbroiled' is not matched).

Using groups and lists, we see that 

query-pr --category="gcc|gdb|gas"

is equivalent to 

query-pr --category="g(cc|db|as)"

and is also very similar to 

query-pr --category="g[cda]"

with the exception that this last search matches any values which begin with `gc', `gd', or `ga'.

The `.' character is known as a wildcard. `.' matches on any single character. `*' matches the previous character (except newlines), list, or group any number of times, including zero. Therefore, we can understand `.*' to mean "match zero or more instances of any character." For this reason, we never specify it at the end of a regular expression, as that would be redundant. The expression `o' matches any instance of the letter `o' (followed by anything) at the beginning of a line, while the expression `o.*' matches any instance of the letter `o' at the beginning of a line followed by any number (including zero) of any characters.

We can also use the expression operator `|' to signify a logical OR, such that 

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

matches all `open' or `analyzed' Problem Reports. (Double quotes (") are used to protect the pipe symbol (|) from the shell.)

By the same token,(5) using 

query-pr --state=".*a"

matches all values for `>State:' which contain an `a'. (These include `analyzed' and `feedback'.)

Another way to understand what wildcards do is to follow them on their search for matching text. By our syntax, `.*' matches any character any number of times, including zero. Therefore, `.*a' searches for any group of characters which end with `a', ignoring the rest of the field. `.*a' matches `analyzed' (stopping at the first `a') as well as `feedback'.

Note: When using `--text' or `--multitext', you do not have to specify the token `.*' at the beginning of text to match the entire field. For the technically minded, this is because `--text' and `--multitext' use `re_search' rather than `re_match'. `re_match' anchors the search at the beginning of the field, while `re_search' does not anchor the search.

For example, to search in the >Description: field for the text 

The defrobulator component returns a nil value.

we can use 

query-pr --multitext="defrobulator.*nil"

To also match newlines, we have to include the expression `(.|^M)' instead of just a dot (`.'). `(.|^M)' matches "any single character except a newline (`.') or (`|') any newline (`^M')." This means that to search for the text 

The defrobulator component enters the bifrabulator routine
and returns a nil value.

we must use 

query-pr --multitext="defrobulator(.|^M)*nil"

To generate the newline character `^M', type the following depending on your shell:

csh
`control-V control-M'
tcsh
`control-V control-J'
sh (or bash)
Use the RETURN key, as in 
(.|
)

Again, see section `Regular Expression Syntax' in Regex, for a much more complete discussion on regular expression syntax.

Index

-

  • --with-gnats-port
  • --with-gnats-server
  • --with-gnats-service
  • --with-gnats-user

    • >

  • >Arrival-Date:
  • >Audit-Trail:
  • >Category:
  • >Class:
  • >Confidential:
  • >Description:
  • >Environment:
  • >Fix:
  • >How-To-Repeat:
  • >Number:
  • >Organization:
  • >Originator:
  • >Priority:
  • >Release:
  • >Responsible:
  • >Severity:
  • >State:
  • >Submitter-Id:, >Submitter-Id:
  • >Synopsis:
  • >Unformatted:

    • a

  • ACKNOWLEDGE
  • adding a problem category, adding a problem category
  • adding and removing maintainers
  • address retrieval
  • addresses file, addresses file
  • admin files
  • administering GNATS
  • administrative utilities, administrative utilities
  • alias for incoming Problem Reports
  • alias for your site
  • aliases
  • analyzed state
  • appending PRs, appending PRs
  • Arrival-Date field
  • at
  • at-pr, at-pr
  • Audit-Trail field
  • autoload commands, autoload commands
  • automatic notification, automatic notification

    • b

  • BACK UP YOUR DATA
  • bad Problem Reports
  • bug alias
  • building a distribution of send-pr
  • building a new index
  • building GNATS
  • building in a different directory
  • business hours

    • c

  • categories file, categories file, categories file, categories file
  • Category field
  • change-request class
  • changing your local configuration
  • Class field
  • closed state
  • command line options
  • comment section in the PR template
  • compiling the software
  • completion in Emacs
  • Confidential field
  • confidentiality in PRs
  • config file, config file
  • configure, configure
  • configuring GNATS
  • configuring and compiling the software
  • configuring GNATS on a network
  • configuring send-pr for the outside world
  • creating an account for GNATS, creating an account for GNATS
  • critical severity problems
  • cron
  • crontab
  • current file

    • d

  • daemon
  • database paradigm
  • database rationale
  • database similarities
  • default behavior
  • default category
  • default installation locations, default installation locations
  • DEFAULT_ORGANIZATION
  • DEFAULT_RELEASE
  • DEFAULT_SUBMITTER
  • Description field
  • Direct e-mail
  • disabling submitter-id, disabling submitter-id
  • doc-bug class
  • driver for edit-pr
  • duplicate class
  • duties for gnats-admin

    • e

  • edit-pr
  • edit-pr driver
  • edit-pr from the shell
  • edit-pr in Emacs
  • effective problem reporting
  • Emacs
  • Emacs functions, Emacs functions
  • Emacs lisp file installation
  • emptying the pending directory
  • Enumerated data types
  • Environment field
  • errors
  • example Problem Report
  • example queries
  • exec-prefix, exec-prefix

    • f

  • feedback state
  • field format
  • fields
  • fields - list
  • file-pr
  • files used for GNATS administration
  • final state (closed)
  • Fix field
  • flowchart of GNATS activities
  • foreword
  • format
  • From: header

    • g

  • gen-index, gen-index
  • GNATS administrator
  • GNATS database fields
  • GNATS fields - list
  • GNATS management
  • gnats-admin alias
  • GNATS_ADDR
  • GNATS_ADMIN
  • GNATS_ROOT, GNATS_ROOT
  • GNATS_SITE

    • h

  • handling incoming traffic
  • helpful hints
  • high priority problems
  • How-To-Repeat field

    • i

  • incoming alias for Problem Reports
  • incoming PRs that GNATS cannot parse
  • index file, index file
  • information to submit
  • initial state (open)
  • installing GNATS
  • installing the utilities
  • interactive interface
  • internal utilities, internal utilities
  • Internet standard RFC-822
  • introduction to GNATS
  • invalid Problem Reports
  • invoking edit-pr
  • invoking mkdist
  • invoking query-pr
  • invoking send-pr
  • invoking send-pr from Emacs
  • invoking send-pr from the shell
  • invoking the GNATS tools

    • k

  • KEEP_RECEIVED_HEADERS
  • kinds of helpful information

    • l

  • life-cycle of a Problem Report
  • lisp file installation
  • listing valid categories
  • loading .el files, loading .el files
  • local configuration
  • locations
  • locks
  • low priority problems

    • m

  • mail alias for your site
  • mail aliases
  • mail header fields
  • mail header section
  • maintenance
  • make
  • managing GNATS
  • managing GNATS over a network
  • medium priority problems
  • mistaken class
  • mkcat, mkcat
  • mkdist
  • MultiText data types

    • n

  • name completion in Emacs
  • networked management
  • networks
  • new problem categories
  • non-critical severity problems
  • notification of overdue PRs
  • NOTIFY
  • Number field

    • o

  • objdir
  • open state
  • Organization field
  • Originator field
  • other mail, other mail
  • overview to GNATS

    • p

  • paradigm
  • pending directory
  • pending file
  • PR confidentiality
  • PR locks
  • pr-addr
  • pr-edit
  • prefix, prefix
  • Priority field
  • Problem Report data types
  • Problem Report format
  • Problem Report states
  • Problem Report template
  • processing incoming traffic
  • pruning log files

    • q

  • query-pr
  • query-pr by mail
  • querying invdividual problem reports
  • querying using regexps
  • queue-pr
  • queue-pr -q

    • r

  • rationale
  • Received-By: headers
  • regular expressions
  • related mail, related mail
  • Release field
  • reminder message
  • removing a problem category, removing a problem category
  • Reply-To: header
  • Report all the facts!
  • reporting
  • reporting problems with send-pr
  • Responsible field
  • responsible file, responsible file
  • Responsible-Changed-<From>-<To>: in >Audit-Trail:
  • Responsible-Changed-By: in >Audit-Trail:
  • Responsible-Changed-When: in >Audit-Trail:
  • Responsible-Changed-Why: in >Audit-Trail:
  • rmcat, rmcat

    • s

  • sample Problem Report
  • saving related mail, saving related mail
  • send-pr
  • send-pr fields, send-pr fields
  • send-pr within Emacs
  • serious severity problems
  • setting up GNATS
  • Severity field
  • shell invocation
  • site alias
  • so what does it do
  • State field
  • state---analyzed
  • state---closed
  • state---feedback
  • state---open
  • state---suspended
  • State-Changed-<From>-<To>: in >Audit-Trail:
  • State-Changed-By: in >Audit-Trail:
  • State-Changed-When: in >Audit-Trail:
  • State-Changed-Why: in >Audit-Trail:
  • states file
  • states of Problem Reports
  • Subject: header
  • SUBMITTER
  • Submitter-Id field, Submitter-Id field
  • submitters file, submitters file
  • Submitting a PR via e-mail
  • subsequent mail, subsequent mail
  • support class
  • support site
  • suspended state
  • sw-bug class
  • Synopsis field
  • syntax of regexps

    • t

  • template
  • template comment section
  • Text data types
  • the section on query-by-mail needs to be relocated
  • timely reminders
  • To: header
  • tool usage for software maintainers

    • u

  • Unformatted field
  • unpacking the distribution
  • unparseable incoming PRs
  • upgrading from older versions
  • usage for the GNATS tools
  • user utilities
  • Using and Porting GNU CC
  • using edit-pr
  • using GNATS over a network, using GNATS over a network
  • using mkdist
  • using query-pr
  • using send-pr
  • using send-pr from within Emacs

    • v

  • view-pr in Emacs
  • visual map of data flow

    • w

  • what is a PR
  • where GNATS lives
  • why GNATS
  • with-full-gnats
  • writing reports

    • Footnotes

    (1)

    If typing `M-x send-pr' doesn't work, see your system administrator for help loading send-pr into Emacs.

    (2)

    If typing `M-x edit-pr' doesn't work, see your system administrator for help loading edit-pr into Emacs.

    (3)

    A header includes the mail header fields as well as the following fields: `>Number:', `>Category:', `>Synopsis:', `>Confidential:', `>Severity:', `>Priority:', `>Responsible:', `>State:', `>Class:', `>Submitter-Id:', `>Originator:', `>Release:', `>Arrival-Date:', `>Last-Modified:' and `>Closed-Date:'. For suggestions on using alternate output formats in database reports, see section 2.8.6 Reporting on groups of Problem Reports.

    (4)

    This approach may seem heavy-handed, but it ensures that changes are not overwritten.

    (5)

    No pun intended.

    This document was generated on 2 April 2000 using the texi2html translator version 1.51a.