2. The GNATS User Tools

This chapter describes the user tools distributed with GNATS. The GNATS administrative and internal tools tools are described in GNATS Administration. The user tools provide facilities for initial submission, querying and editing of Problem Reports:

send-pr

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

query-pr

Used to query the GNATS database (see section Querying the database).

edit-pr

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

2.1 Environment variables and GNATS tools
2.2 Submitting Problem Reports
2.3 Editing existing Problem Reports
2.4 Querying the database
2.5 The Emacs interface to GNATS		The Emacs interface

2.1 Environment variables and GNATS tools

All the GNATS user tools honor the GNATSDB environment variable which is used to determine which database to use. For a local database, it contains the name of the database to access.

For network access via gnatsd, it contains a colon-separated list of strings that describe the remote database in the form

server:port:databasename:username:password

Any of the fields may be omitted except for server, but at least one colon must appear; otherwise, the value is assumed to be the name of a local database.

If GNATSDB is not set and no command-line options are used to specify the database, it is assumed that the database is local and that its name is `default'.

2.2 Submitting Problem Reports

Use send-pr to submit Problem Reports to the database. send-pr is a shell script which composes a template for submitters to complete.

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

2.2.1 Creating new Problem Reports
2.2.2 Using send-pr from within Emacs		Using send-pr from within Emacs
2.2.3 Invoking send-pr from the shell		Invoking send-pr from the shell
2.2.4 Submitting a Problem Report via direct e-mail
2.2.5 Helpful hints

2.2.1 Creating new Problem Reports

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

A template consists of three sections:

Comments

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

Mail Header

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

GNATS fields

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

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

You may submit problem reports to different Support Sites from the default site by specifying the alternate site when you invoke send-pr. See section 2.2.3 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 4.0-beta1

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 Helpful hints, for suggestions as to what kinds of information to include.

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

>Submitter-Id: your submitter-id >Originator: your name here >Organization: your organization >Confidential:<[ yes | no ] (one line)> >Synopsis: <synopsis of the problem (one line)> >Severity: <[non-critical | serious | critical](one line)> >Priority: <[ low | medium | high ] (one line)> >Category: <name of the product (one line)> >Class: <[sw-bug | doc-bug | change-request | support]> >Release: <release number (one line)> >Environment: <machine, os, target, libraries (multiple lines)> >Description: <precise description of the problem (multiple lines)> >How-To-Repeat: <code/input/activities to reproduce (multiple lines)> >Fix: <how to correct or work around the problem, if known (multiple lines)>

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

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

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.2.2 Using send-pr from within Emacs

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

Call send-pr with `M-x send-pr'.(1) send-pr responds with a Problem Report template preconfigured for the Support Site to which you are going to send the report.

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. The Emacs interface to GNATS is described in a separate section, See section 2.5 The Emacs interface to GNATS.

2.2.3 Invoking send-pr from the shell

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

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

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

-f problem-report

--file problem-report

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

-t mail-address

--to mail-address

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

-c mail-address

--cc mail-address

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

--request-id

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

-L

--list

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

-s severity

--severity severity

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

-P

--print

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

-V

--version

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

-h

--help

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

2.2.4 Submitting a Problem Report via direct e-mail

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

• Include anything you would want to know if you were looking at the report from the other end. There's no need to include every minute detail about your environment, although anything that might be different from someone else's environment should be included (your path, for instance).

• Narratives are often useful, given a certain degree of restraint. If a person responsible for a bug can see that A was executed, and then B and then C, knowing that sequence of events might trigger the realization of an intermediate step that was missing, or an extra step that might have changed the environment enough to cause a visible problem. Again, restraint is always in order ("I set the build running, went to get a cup of coffee (Columbian, cream but no sugar), talked to Sheila on the phone, and then THIS happened...") but be sure to include anything relevant.

• Richard Stallman writes, "The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!" This holds true across all problem reporting systems, for computer software or social injustice or motorcycle maintenance. It is especially important in the software field due to the major differences seemingly insignificant changes can make (a changed variable, a missing semicolon, etc.).

• Submit only one problem with each Problem Report. If you have multiple problems, use multiple PRs. This aids in tracking each problem and also in analyzing the problems associated with a given program.

• It never hurts to do a little research to find out if the bug you've found has already been reported. Most software releases contain lists of known bugs in the Release Notes which come with the software; see your system administrator if you don't have a copy of these.

• The more closely a PR adheres to the standard format, the less interaction is required by a database administrator to route the information to the proper place. Keep in mind that anything that requires human interaction also requires time that might be better spent in actually fixing the problem. It is therefore in everyone's best interest that the information contained in a PR be as correct as possible (in both format and content) at the time of submission.

2.3 Editing existing Problem Reports

Use edit-pr to make changes to existing PRs in the database. This tool can be invoked both from a shell prompt or from within GNU Emacs using `M-x edit-pr'.

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 non-readonly fields in the database. We recommend that you avoid deleting any information in the TEXT and MULTITEXT fields (such as `>Description:' and `>How-To-Repeat:' (see section Problem Report format). We also recommend that you record the final solution to the problem in the `>Fix:' field for future reference.

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

If you change a field that requires a reason for the change, such as the `>Responsible:' or `>State:' fields in the default configuration, edit-pr prompts you to supply a reason for the change. A message is then appended to the `>Audit-Trail:' section of the PR with the changed values and the change reason.

Depending on how the database is configured, editing various fields in the PR may also cause mail to be sent concerning these changes. In the default configuration, any fields that generate `>Audit-Trail:' entries will also cause a copy of the new `>Audit-Trail:' message to be sent.

2.3.1 Invoking edit-pr from the shell

2.3.1 Invoking edit-pr from the shell

The usage for edit-pr is:

edit-pr [ -V | --version ] [ -h | --help ] [-d database | --database database] PR Number

Network-mode-only options:

[--host host | -H host] [--port port] [--user user | -v user] [--passwd passwd | -w passwd]

The options have the following meaning:

-h, --help

Prints a brief usage message for edit-pr.

-V, --version

Prints the version number for edit-pr.

-d, --database

Specifies the database containing the PR to be edited; if no database is specified, the database named `default' is assumed. This option overrides the database specified in the GNATSDB environment variable.

--host host, -H host

Specifies the hostname of the gnatsd server to communicate with. This overrides the value in the GNATSDB environment variable.

--port port

Specifies the port number of the gnatsd server to communicate with. This overrides the value in the GNATSDB environment variable.

--user user, -v user

Specifies the username to login with when connecting to the gnatsd server. This overrides the value in the GNATSDB environment variable.

--passwd passwd, -w passwd

Specifies the password to login with when connecting to the gnatsd server. This overrides the value in the GNATSDB environment variable.

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 have changed a field that requires specifying a reason for the change.

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

PRs may be selected via the use of the --expr option, directly by number, or by the use of the (now deprecated) field-specific query operators.

By default, query options are connected with a logical AND. For example,

query-pr --category=foo --responsible=bar

only prints PRs which have a Category field of `foo' and a Responsible field of `bar'.

The --or option may be used to connect query options with a logical OR. For example,

query-pr --category=baz --or --responsible=blee

prints PRs which have either a Category field of `baz' or a Responsible field of `blee'.

It should be emphasized, however, that the use of these field-specific options is strongly discouraged, since they exist only for compatibility with older versions of GNATS and are likely to be deleted in the next release. The expressions specified by the --expr option are much more flexible (see below).

2.4.1 Invoking query-pr
2.4.2 Formatting query-pr output
2.4.3 Query expressions
2.4.4 Example queries

2.4.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 [--debug | -D] [--help | -h] [--version | -V] [--output file | -o file] [--list-databases] [--list-fields] [--list-input-fields] [--responsible-address address] [--field-type type] [--field-description description] [--valid-values values] [--format format | -f format] [--full | -F] [--summary | -q] [--database database | -d database] [--and | -&] [--or | -|] [--expr expr] [PR Number]

Non-network-mode options:

[--print-sh-vars] [--print-directory-for-database]

Network-mode-only options:

[--host host | -H host] [--port port] [--user user | -v user] [--passwd passwd | -w passwd]

Deprecated Options:

[--list-categories | -j] [--list-states | -T] [--list-responsible | -k] [--list-submitters | -l] [--category category | -c category] [--synopsis synopsis | -y synopsis] [--confidential confidential | -C confidential] [--multitext multitext | -m multitext] [--originator originator | -O originator] [--release release | -A release] [--class class | -L class] [--cases cases | -E cases] [--quarter quarter | -Q quarter] [--keywords keywords | -K keywords] [--priority priority | -p priority] [--responsible responsible | -r responsible] [--restricted | -R] [--severity severity | -e severity] [--skip-closed | -x] [--sql | -i] [--sql2 | -I] [--state state | -s state] [--submitter submitter | -S submitter] [--text text | -t text] [--required-before date | -u date] [--required-after date | -U date] [--arrived-before date | -b date] [--arrived-after date | -a date] [--modified-before date | -B date] [--modified-after date | -M date] [--closed-before date | -z date] [--closed-after date | -Z date]

The options have the following meaning:

--help, -h

Prints a help message.

--version, -V

Displays the program version to stdout.

--output file, -o file

The results of the query will be placed in this file.

--database database, -d database

Specifies the database to be used for the query. If no database is specified, the database named default is assumed. (This option overrides the database specified in the GNATSDB environment variable; see 2.1 Environment variables and GNATS tools for more information.)

--list-categories, -j

Lists the available PR categories for the selected database.

--list-states, -T

Lists the valid PR states for PRs in this database.

--list-responsible, -k

Lists the users that appear in the database's responsible list.

--list-submitters, -l

Lists the valid submitters for this database.

The previous --list-* options are deprecated and may be removed in future releases of GNATS; their functionality can be replaced with

query-pr --valid-values field

where field is one of `Category', `Class', `Responsible', `Submitter-Id', or `State'.

--list-databases

Lists the known databases.

--list-fields

Lists the entire set of field names for PRs in the selected database.

--list-input-fields

Lists the fields that should be provided when creating a new PR for the currently-specified database. The fields are listed in an order that would make sense when used in a template or form.

--field-type field

Returns the data type contained in PR field field. The current set of data types includes `text', `multitext', `enum', `multienum', `integer', `date', and `text-with-regex-qualifier'.

--field-description field

Returns a human-readable description of the intended purpose of field.

--valid-values field

For fields of type `enum', a list of valid values (one per line) is returned. Otherwise, a regular expression is returned that describes the legal values in field.

--responsible-address name

The mail address of name is returned; name is assumed to be a name either appearing in the database's responsible list, or is otherwise a user on the system.

--print-sh-vars

A set of `/bin/sh' variables is returned that describe the selected database. They include:

GNATSDB

The name of the currently-selected database.

GNATSDB_VALID

Set to 1 if the selected database is valid.

GNATSDBDIR

The directory where the database contents are stored.

DEBUG_MODE

Set to 1 if debug mode has been enabled for the database.

DEFAULTCATEGORY

The default category for PRs in the database.

DEFAULTSTATE

The default state for PRs in the database.

--print-directory-for-database

Returns the directory where the selected database is located.

--format format, -f format

Used to specify the format of the output PRs, See 2.4.2 Formatting query-pr output for a complete description.

--full, -F

When printing PRs, the entre PR is displayed. This is exactly equivalent to

query-pr --format full

--summary, -q

When printing PRs, a summary format is used. This is exactly equivalent to

query-pr --format summary

--debug, -D

Enables debugging output for network queries.

--host host, -H host

Specifies the hostname of the gnatsd server to communicate with. This overrides the value in the GNATSDB environment variable.

--port port

Specifies the port number of the gnatsd server to communicate with. This overrides the value in the GNATSDB environment variable.

--user user, -v user

Specifies the username to login with when connecting to the gnatsd server. This overrides the value in the GNATSDB environment variable.

--passwd passwd, -w passwd

Specifies the password to login with when connecting to the gnatsd server. This overrides the value in the GNATSDB environment variable.

--and, -&, --or, -|

These options are used when connecting multiple query operators together. They specify whether the previous and subsequent options are to be logically ANDed or logically ORed.

--expr expr

Specifies a query expression to use when searching for PRs. See section 2.4.3 Query expressions.

The remaining deprecated options are not described here, since their use is fairly obvious and their functionality is completely replaced by the use of the --expr option.

2.4.2 Formatting query-pr output

Printing formats for PRs are in one of three forms:

formatname

This is a named format which is described by the database (specifically, these formats are described in the `dbconfig' file associated with the database). The default configuration contains five such formats: `standard', `full', `summary', `sql', and `sql2'.

The first three are the ones most commonly used when performing queries. standard is the format used by default if no other format is specified.

Use of the latter two are discouraged; they are merely kept for historical purposes. Other named formats may have been added by the database administrator.

fieldname

A single field name may appear here. Only the contents of this field will be displayed.

"printf string" fieldname fieldname ...

This provides a very flexible mechanism for formatting PR output. (The formatting is identical to that provided by the named formats described by the database configuration, See section 4.3.5 Named query definitions. The printf string can contain the following % sequences:

%[positionalspecifiers]s: Prints the field as a string. The positional specifiers are similar to those of printf, as +, - and digit qualifiers can be used to force a particular alignment of the field contents.

%[positionalspecifiers]S: Similar to %s, except that the field contents are terminated at the first space character.

%[positionalspecifiers]d: Similar to %s, except that the field contents are written as a numeric value. For integer fields, the value is written as a number. For enumerated fields, the field is converted into a numeric equivalent (i.e. if the field can have two possible values, the result will be either 1 or 2). For date fields, the value is written as seconds since Jan 1, 1970.

%F: The field is written as it would appear within a PR, complete with field header.

%D: For date fields, the date is written in a standard GNATS format.

%Q: For date fields, the date is written in an arbitrary "SQL" format.

2.4.3 Query expressions

Query expressions are used to select specific PRs based on their field contents. The general form is

fieldname|"value" operator fieldname|"value" [booleanop ...]

value is a literal string or regular expression; it must be surrounded by double quotes, otherwise it is interpreted as a fieldname.

fieldname is the name of a field in the PR.

operator is one of:

=

The value of the left-hand side of the expression must exactly match the regular expression on the right-hand side of the expression. See section Querying using regular expressions.

~

Some portion of the left-hand side of the expression must match the regular expression on the right-hand side.

==

The value of the left-hand side must be equal to the value on the right-hand side of the expression.

The equality of two values depends on what type of data is stored in the field(s) being queried. For example, when querying a field containing integer values, literal strings are interpreted as integers. The query expression

Number == "0123"

is identical to

Number == "123"

as the leading zero is ignored. If the values were treated as strings instead of integers, then the two comparisons would return different results.

!=

The not-equal operator. Produces the opposite result of the == operator.

<,>

The left-hand side must have a value less than or greater than the right-hand side. Comparisons are done depending on the type of data being queried; in particular, integer fields and dates use a numeric comparison, and enumerated fields are ordered depending on the numeric equivalent of their enumerated values.

booleanop is either `|' (logical or), or `&' (logical and). The query expression

Category="baz" | Responsible="blee"

selects all PRs with a Category field of `baz' or a Responsible field of `blee'.

The not operator `!' may be used to negate a test:

! Category="foo"

searches for PRs where the category is not equal to the regular expression foo.

Parentheses may be used to force a particular interpretation of the expression:

!(Category="foo" & Submitter-Id="blaz")

skips PRs where the Category field is equal to `foo' and the Submitter-Id field is equal to `blaz'. Parentheses may be nested to any arbitrary depth.

Fieldnames can be specified in several ways. The simplest and most obvious is just a name:

Category="foo"

which checks the value of the category field for the value foo.

A fieldname qualifier may be prepended to the name of the field; a colon is used to separate the qualifier from the name. To refer directly to a builtin field name:

builtin:Number="123"

In this case, `Number' is interpreted as the builtin name of the field to check. (This is useful if the fields have been renamed. For further discussion of builtin field names, see The dbconfig file.

To scan all fields of a particular type, the fieldtype qualifier may be used:

fieldtype:Text="bar"

This searches all text fields for the regular expression `bar'.

Note that it is not required that the right-hand side of the expression be a literal string. To query all PRs where the PR has been modified since it was closed, the expression

Last-Modified != Closed-Date

will work; for each PR, it compares the value of its Last-Modified field against its Closed-Date field, and returns those PRs where the values differ. However, this query will also return all PRs with empty Last-Modified or Closed-Date fields. To further narrow the search:

Last-Modified != Closed-Date & Last-Modified != "" & Closed-Date != ""

In general, comparing fields of two different types (an integer field against a date field, for example) will probably not do what you want.

Also, a field specifier may be followed by the name of a subfield in braces:

State[type] != "closed"

or even

builtin:State[type] != "closed"

Subfields are further discussed in The dbconfig file.

2.4.4 Example queries

The following simple query:

query-pr --expr 'Category~"rats" & State~"analyzed" & Responsible~"fred"'

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

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

The following query:

query-pr --expr 'State~"open|analyzed"'

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

The following query:

query-pr --expr 'fieldtype:Text="The quick.*brown fox"'

yields all PRs whose TEXT fields contain the text `The quick' followed by `brown fox' within the same field. See section Querying using regular expressions, which also contains further useful examples of query expressions.

2.5 The Emacs interface to GNATS

Emacs interface to GNATS provides basic access to GNATS databases, i.e. sending, editing, and querying Problem Reports. It also defines a simple major mode for editing `dbconfig' files.

This section provides an overview of using GNATS with Emacs. It does not describe the use of Emacs itself, for detailed instructions on using Emacs, see section `Top' in GNU Emacs. For installation instructions of the GNATS Emacs mode, see 3.2 Installing the utilities.

Please note the Emacs interface was completely rewritten between GNATS 3 and GNATS 4. It now uses gnatsd, B. The GNATS network server -- gnatsd, exclusively for its operations and uses modern Emacs features like faces. Its features are not complete though, you can send your suggestions and patches to the appropriate GNATS mailing list, E. GNATS support.

2.5.1 Viewing Problem Reports		Viewing PRs by their number.
2.5.2 Querying Problem Reports		Querying the database.
2.5.3 Submitting new Problem Reports		Submitting new PRs.
2.5.4 Editing Problem Reports		Editing PRs.
2.5.5 The Problem Report editing buffer		The editing buffer.
2.5.6 Changing the database		Changing the working database.
2.5.7 dbconfig mode		Major mode for dbconfig files.
2.5.8 Other commands		Miscellaneous commands.
2.5.9 Customization		Customizing the Emacs interface.

2.5.1 Viewing Problem Reports

To view a particular Problem Report, use the command M-x view-pr. It asks for a Problem Report number and displays that Problem Report.

The displayed buffer is put in the view mode, section `Misc File Ops' in GNU Emacs. If you decide to edit the displayed Problem Report, use the command e (gnats-view-edit-pr).

gnats-view-mode-hook

Hook run when gnats-view-mode is entered.

2.5.2 Querying Problem Reports

Querying the database is performed by the M-x query-pr command. The command prompts for the query expression, 2.4.3 Query expressions, and displays a buffer with the list of the matching Problem Reports.

The list of the Problem Reports is displayed in the `summary' query format, 2.4.2 Formatting query-pr output. Currently, the display format cannot be changed and it must output each Problem Report's number in the first column.

The Problem Report list buffer is put in the view mode, section `Misc File Ops' in GNU Emacs. You can use most of the standard view mode commands in it. Additionally, the following special commands are available:

v

RET

mouse-2

View the current Problem Report (gnats-query-view-pr), 2.5.1 Viewing Problem Reports.

e

Edit the current Problem Report (gnats-query-edit-pr), 2.5.4 Editing Problem Reports.

g

Update the Problem Report list (gnats-query-reread). The last performed query is executed again and the buffer is filled with the new results.

G

Perform new query (query-pr).

s

Send new Problem Report (send-pr), 2.5.3 Submitting new Problem Reports.

D

Change the current database (gnats-change-database), 2.5.6 Changing the database.

q

Bury buffer, the buffer is put at the end of the list of all buffers. This is useful for quick escape of the buffer, without killing it.

If the value of the variable gnats-query-reverse-listing is non-nil, the listing appears in the reversed order, i.e. with the Problem Reports of the highest number first, in the buffer.

Similarly to other GNATS Emacs modes, there is a hook available for the Problem Report list.

gnats-query-mode-hook

Hook run when gnats-query-mode is entered.

2.5.3 Submitting new Problem Reports

You can submit new Problem Reports with the command M-x send-pr. The command puts you to the problem editing buffer, 2.5.4 Editing Problem Reports. The buffer is prefilled with the initial report fields and their default values, if defined. You can use the usual Problem Report editing commands, 2.5.4 Editing Problem Reports. When you have filled in all the fields, you can send the Problem Report by presing C-c C-c.

If you run M-x send-pr with a prefix argument, it runs the gnats-change-database command before putting you to the editing buffer, 2.5.6 Changing the database.

You can set the following variables to get some fields pre-filled:

gnats-default-organization

Default value of the `Organization' field used in new Problem Reports.

gnats-default-submitter

Default value of the `Submitter-Id' field used in new Problem Reports.

2.5.4 Editing Problem Reports

To edit a particular Problem Report, use the command M-x edit-pr. It asks for a Problem Report number and puts the given Problem Report in the editing buffer. See section 2.5.5 The Problem Report editing buffer, for information how to edit the Problem Report in the buffer and how to submit your changes.

Note you can also start editing of a selected Problem Report directly from within the viewing buffer, 2.5.1 Viewing Problem Reports, or the query result buffer, 2.5.2 Querying Problem Reports.

2.5.5 The Problem Report editing buffer

When you invoke a Problem Report editing command, the Problem Report is put into a special editing buffer. The Problem Report is formatted similarly to the query-pr -F output, 2.4.2 Formatting query-pr output. Field identifiers are formatted as

>Field:

with the text of the field following the identifier on the same line for single-line fields or starting on the next line for multi-line fields.

The Problem Report editing mode tries to prevent you from violating the Problem Report format and the constraints put on the possible field values. Generally, you can use usual editing commands, some of them have a slightly modified behavior though. (If you encounter a very strange behavior somewhere, please report it as a bug, E. GNATS support.)

You can move between fields easily by pressing the TAB (gnats-next-field) or M-TAB (gnats-previous-field) keys.

The field tags are read-only and you cannot edit them nor delete them. If you want to "remove" a field, just make its value empty.

Editing a field value depends on the type of the edited field, 4.3.3 Field datatypes. For text fields, you can edit the value directly, assuming you preserve the rule about single-line and multi-line values mentioned above.

For enumerated fields, you cannot edit the value directly. You can choose it from the list of the allowed values, either from the menu popped up by pressing the middle mouse button or from within minibuffer by pressing any key on the field's value. If the pressed key matches any of the allowed field values, that value is put as the default value after the minibuffer prompt. You can also cycle through the allowed field values directly in the editing buffer using the SPACE key. Enumerated field values are marked by a special face to not confuse you; you must have enabled font lock mode to benefit from this feature, section `Font Lock' in GNU Emacs.

Some field values can be read-only, you cannot edit them at all.

Once you have edited the Problem Report as needed, you can send it to the server with the C-c C-c command (gnats-apply-or-submit). Successful submission is reported by a message and the buffer modification flag in mode line is cleared. Then you can either kill the buffer or continue with further modifications.

gnats-edit-mode-hook

Hook run when gnats-edit-mode is entered.

2.5.6 Changing the database

By default, the Emacs interface connects to the default database, 4.2 The databases file. If you want to connect to another database, use the command M-x gnats-change-database. It will ask you for the database name to use, server and port it can be accessed on, and your login name.

If you want to use the gnatsd command, B. The GNATS network server -- gnatsd, directly, without connecting to a remote server or the localhost connection port, provide your local file system full path to gnatsd as the server name. Port number does not matter in this case.

If the database requires a password to allow you the access to it, you are prompted for the password the first time you connect to the database. If you provide an invalid password, you cannot connect to the database anymore and you have to run the M-x gnats-change-database command again.

2.5.7 dbconfig mode

The Emacs interface defines a simple major mode gnats-dbconfig-mode for editing `dbconfig' files, 4.3 The dbconfig file. It defines basic mode attributes like character syntax and font lock keywords, it does not define any special commands now.

gnats-dbconfig-mode-hook

Hook run when gnats-dbconfig-mode is entered.

2.5.8 Other commands

M-x unlock-pr

Ask for a Problem Report number and unlock that Problem Report. This function is useful if connection to a GNATS server was interrupted during an editing operation and further modifications of the Problem Report are blocked by a stealth lock.

2.5.9 Customization

All the user variables can be customized in the customization group gnats, section `Easy customization' in GNU Emacs.