4.4.1 The categories file

The categories file contains a list of problem categories, specific to the database, which gnats tracks. This file also matches responsible people with these categories. You must edit this file initially, creating valid categories. In most installations, gnats is configured to create directories on disk for valid categories automatically as needed (see Overall database configuration). If gnats isn't set up to do this, you need to run mkcat to create the corresponding subdirectories of the database directory. For instructions on running mkcat, see Adding a problem category.

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

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

     category:description:responsible:notify

category

A unique category name, made up of text characters. This name cannot contain spaces or any of the following characters:

          ! $ & * ( ) { } [ ] ` ' " ; : < > ~
     

Ideally, category names should not contain commas or begin with periods. Each line has a corresponding subdirectory in the database directory.

description

A terse textual description of the category.

responsible

The name tag of the party responsible for this category of problems, as listed in the responsible file (see The responsible file).

notify

One or more other parties which should be notified when a Problem Report with this category arrives, such as a project manager, other members of the same project, other interested parties, or even log files. These should be separated with commas.

A good strategy for configuring this file is to have a different category for each product your organization supports or wishes to track information for.

     rock:ROCK program:me:myboss,fred
     stone:STONE utils:barney:fred
     iron:IRON firewall:me:firewall-log

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

Problem Reports with a category of rock are sent to the local mail address (or alias) me, and also sent to the addresses myboss and fred. PRs with a category of stone are sent to the local addresses barney and fred only, while PRs with the category iron are sent only to me, and are also filed in firewall-log (in this case, a mail alias should be set up, see Setting up mail aliases.

If you want to separate PRs in each problem category into specific subsets, say documentation and software bugs, using the classes file is recommended. See The classes file.

Only one category must be present for gnats to function:

     pending:Non-categorized PRs:gnats-admin:

The pending directory is created automatically when you run mkdb to initialize a new database. (see Configuring and compiling the software).