[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 | 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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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’.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.3 The Problem Report template | ||
2.2.2 Using send-pr from within Emacs | Using send-pr from within Emacs | |
2.2.1 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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
send-pr
from the shellsend-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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
send-pr
from within EmacsYou 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 | ||
2.3.2 Following up via direct email |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
edit-pr
from the shellThe 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
query-pr
outputPrinting formats for PRs are in one of three forms:
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.
A single field name may appear here. Only the contents of this field will be displayed.
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' |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 | 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. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
View the current Problem Report (gnats-query-view-pr
),
Viewing Problem Reports.
Edit the current Problem Report (gnats-query-edit-pr
),
Editing Problem Reports.
Update the Problem Report list (gnats-query-reread
). The last
performed query is executed again and the buffer is filled with the
new results.
Perform new query (query-pr
).
Send new Problem Report (send-pr
), Submitting new Problem Reports.
Change the current database (gnats-change-database
), Changing the database.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
Default value of the ‘Organization’ field used in new Problem Reports.
Default value of the ‘Submitter-Id’ field used in new Problem Reports.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
Unlock the whole GNATS database. This function is useful in
situations similar to when unlock-pr
is used.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All the user variables can be customized in the customization group
gnats
, (emacs)Easy customization section ‘Easy customization’ in GNU Emacs.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.