2. The GNATS User Tools

This chapter describes the user tools distributed with GNATS. The GNATS administrative and internal 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

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’ (see section Submitting Problem Reports from Emacs.)

2.2.1 Invoking send-pr from the shell

send-pr [ -b | --batch ]
        [ -d database | --database database ]
        [ -f file | --file file ]
        [ -p | --print ] [ --request-id ]
        [ -s severity | --severity severity ]
        [ -V | --version ] [ -h | --help ]

Invoking send-pr with no options assumes that you want to submit to the local GNATS database named default and calls the editor named in your environment variable EDITOR on a PR template for this database.

-b

--batch

Suppresses printing of most of the messages send-pr usually prints while running.

-d database, --database database

Specifies the database to which the PR is to be submitted; if no database is specified, the local database named default is assumed. This option overrides the database specified in the GNATSDB environment variable. database can also be set to a remote database by using the format for GNATSDB described in Environment variables and GNATS tools.

-f problem-report

--file problem-report

Specifies a file, problem-report, where a completed Problem Report or a PR template exists. send-pr verifies that the contents of the file constitute a valid PR and asks you if you want to edit it or send it directly. If the PR text is invalid you will be told what is wrong and be given the option to edit it. If problem-report is ‘-’, send-pr reads from standard input.

-p

--print

Displays the PR template for the specified database, or if the -d or --database options aren’t specified, print the template for the local default database. No PR is submitted.

--request-id

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

-s severity

--severity severity

Sets the initial value of the Severity field to severity.

-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.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 (emacs)Introduction section ‘Introduction’ in GNU Emacs).

Call send-pr with ‘M-x send-pr’.(1) send-pr responds with a preconfigured Problem Report template. The Emacs interface is described in more detail in a separate section, See section The Emacs interface to GNATS.

2.2.3 The Problem Report template

Invoking send-pr presents a PR template with a number of fields already filled in with default values for the database you are submitting to. 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
• Mail Header
• GNATS fields

The Comments section at the top of the template contains basic instructions for completing the Problem Report, as well as a list of valid entries for the Category field. One (and only one) of these values should be placed in the Category field further down in the Problem Report.

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:

The comments lines 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.)

The Mail Header section of the template contains a standard mail header constructed by send-pr. send-pr can be set up to submit PRs by e-mail or by speaking directly to the GNATS server, but since this header is part of the standard format of Problem Reports, send-pr includes it even when it is set up to speak directly to the server.

To: PR submission address
Subject: complete this field
From: your-login@your-site
Reply-To: your-login@your-site
X-send-pr-version: send-pr 4.2.0

send-pr automatically completes all the mail header fields except the Subject line with default values. (See section Problem Report format.)

The GNATS fields below the mail header form the bulk of a GNATS Problem Report.

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.

The mechanisms send-pr uses to fill in default values is as follows: Your preconfigured Submitter-Id is taken from the local ‘send-pr.conf’ configuration file. 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. If these variables aren’t set in you environment, send-pr uses the values set in the local ‘send-pr.conf’ configuration file, if that exists. If not, these values are left blank in the template. 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.

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 validates the contents and if it looks OK either submits it directly to the GNATS server or submits it by mail to the address named in the To field in the mail header.

If your PR contains one or more invalid field values, 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.

2.2.4 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 PR submission e-mail address of the support site (This address should be published by the support site.)

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 of the e-mail message.

Submitter ID

GNATS will try to derive the Submitter field from the address in the From header of the e-mail.

Description

All of the text in the body of the e-mail message is put into the Description field.

Other fields, such as Category, Version, Severity, etc. are set to default values as defined by the GNATS administrator.

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 (gcc)Bugs 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. Note that heavily customized installations of GNATS may have differently named fields, and sites using such installations should provide their own set of routines and instructions regarding how PRs should be treated throughout their life span.

After the PR has been edited, it 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 field 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.

Mail received at the PR submission email address and recognized by GNATS as relating to an existing PR is also appended to the ‘Audit-Trail’ field, see Following up via direct email.

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, --database 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.3.2 Following up via direct email

If you have some additional information for a PR and for some reason do not want to (or cannot) edit the PR directly, you may append the information to the Audit-Trail field by mailing it to the PR submission address.

In order for GNATS to be able to recognize the mail as pertaining to an existing PR (as opposed to a new PR, see Submitting a Problem Report via direct e-mail), the Subject mail header field must contain a reference to the PR. GNATS matches the Subject header against the regular expression

\<(PR[ \t#/]?|[-[:alnum:]+.]+/)[0-9]+

to determine whether such a reference is present. Any text may precede or follow the reference in the Subject header. If more than one reference is present, the first is used and the rest ignored.

A PR reference matching the regular expression above has two parts. The second is the PR number (one or more digits). The first is either the capital letters ’PR’ optionally followed by a separator character (blank, tab, hash mark or forward slash) or the category name followed by a forward slash. Following are some examples which match the regular expression:

PR 123 PR4567 PR#890 gnats/4711

The PR number and the category (if present) are checked for existence, and if the outcome is positive, the mail is appended to the Audit-Trail field of the PR. Note that the PR need not belong to the category because PRs may move between categories.

Outgoing emails sent by GNATS itself may be configured to have a Subject header field that refers to the PR in question:

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

This makes it extremely easy to follow up on a PR by replying to such an email, see The dbconfig file and the sample, default dbconfig file installed by mkdb.

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

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 name] [--field-type field]
         [--field-description field]
         [--field-flags field]
         [--adm-field field] [--adm-subfield subfield]
         [--adm-key key]
         [--valid-values field]
         [--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]
         [--print-server-addr]

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 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’, ‘enumerated-in-file’, ‘multi-enumerated-in-file’, ‘date’ and ‘integer’.

--field-description field

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

--field-flags field

Returns the flags set for the field in the ‘dbconfig’ file associated with the database, such as textsearch and readonly. See section Individual field configuration.

--adm-field field

Used together with the --adm-key option, this returns a record from the administrative file (if any) associated with the field. For more material on administrative files, see Enumerated field administrative files.

--adm-subfield subfield

Used together with the --adm-field and --adm-key options, this returns the contents of a particular subfield from the record specified by --adm-field and --adm-key. Subfields are treated in Enumerated field administrative files.

--adm-key key

Used together with --adm-field to select a record from the administrative file associated with the field specified by --adm-field. See Enumerated field administrative files.

--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-server-addr

Prints the information about a remote server database in the format suitable for the GNATSDB environment variable. This option works only in the network mode.

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

An example formatted query looks as follows (note that the whole format specification should be quoted):

query-pr --format '"%s, %s" Synopsis State'

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 (emacs)Top section ‘Top’ in GNU Emacs. For installation instructions of the GNATS Emacs mode, see Installing the utilities.

Please note the Emacs interface was completely rewritten between GNATS 3 and GNATS 4. It now uses gnatsd, 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, GNATS support.

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, (emacs)Misc File Ops 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, 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, 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, (emacs)Misc File Ops 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), Viewing Problem Reports.

e

Edit the current Problem Report (gnats-query-edit-pr), 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), Submitting new Problem Reports.

D

Change the current database (gnats-change-database), 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, 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, 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, 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 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, Viewing Problem Reports, or the query result buffer, 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, 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, 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, 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, (emacs)Font Lock 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, 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, 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, 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.

M-x unlock-database

Unlock the whole GNATS database. This function is useful in situations similar to when unlock-pr is used.

M-x gnats-show-connection

Show the connection buffer associated with the current buffer. You can view the Emacs communication with GNATSD in it. This is useful when something strange happens during the communication with the server, e.g. when sending a Problem Report with C-c C-c from a Problem Report editing buffer.

2.5.9 Customization

All the user variables can be customized in the customization group gnats, (emacs)Easy customization section ‘Easy customization’ in GNU Emacs.

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.