Querying the Issue Database

OK, we now have a bunch of issues. How do we know what state they’re in? A good way to get a summary is the todo command. In the command loop, this is run by default if you just press RETURN. Here’s the output for the issues we have so far:

Ditz: todo
Unassigned:
_ prog-2: Prototype prints the Wrong Thing (bug)
_  doc-1: Write some documentation
_ prog-1: Implement a hello-world program (feature)

This says that we have three issues, none of which are assigned to a release (more on those later). They’re printed in reverse order of modification (most recently modified first). The underscore at the start of each line is a status indicator flag; in this case it means the issue is unstarted.

Each issue can be in one of four states:

Flag	Meaning	Details
_	Unstarted	No work has yet begun on the issue.
>	In progress	Work has started on the issue.
=	Paused	Some work has been started, but now it is stopped.
x	Closed	The issue is closed.

Normally, closed issues are not shown by the todo command. But if you give the -a (for ‘all’) option, they are.

To look closer at a single issue, we use the show command. This displays all the detailed issue information, including a history of all the events which have occurred to the issue (and their comments). Here’s an example:

Ditz: show prog-1
Issue prog-1
------------
      Title: Implement a hello-world program
Description: Pretty lame, but one has to start somewhere.

       Type: feature
     Status: unstarted
    Creator: Dilbert <dilbert@cubicle.com>
        Age: 1 second
 References: 
  1. http://warez.com/hello-world-trojan.c
 Identifier: 813fae8376c79911b69b7ebfc87f25a2d4b0dad1

Event log:
- added reference 1 (dilbert, 1 second ago)
  > Prototype for the program.
- assigned to component prog from helloworld (dilbert, 1 second ago)
  > This is a programming issue.
- created (dilbert, 1 second ago)
  > I already have a prototype for this, off the Interweb.

The only thing needing explanation here is the long identifier. This is a SHA-1 message digest built from several of the issue attributes, and uniquely identifies the issue. Even if the issue name changes (which it might when issue components are changed), this remains constant.

As well as events in individual issues, you can get a recent-event history over all issues in the database. The shortlog command produces a one-line summary of each recent event:

Ditz: shortlog
    just now | prog-2 | dilbert | created
    just now |  doc-1 | dilbert | created
1 second ago | prog-1 | dilbert | added reference 1
1 second ago | prog-1 | dilbert | assigned to component prog from helloworld
1 second ago | prog-1 | dilbert | created

If you give a numeric argument, then that many events will be shown. (A value of zero will show all of them.) This value becomes the default for future commands. You can change the initial default in your Configuration File.

To get a more detailed summary of log entries, there is the log command:

Ditz: log
date   : Fri May 29 15:57:17 2020 (just now)
author : Dilbert <dilbert@cubicle.com>
issue  : [prog-2] Prototype prints the Wrong Thing

  created

date   : Fri May 29 15:57:17 2020 (just now)
author : Dilbert <dilbert@cubicle.com>
issue  : [doc-1] Write some documentation

  created

date   : Fri May 29 15:57:16 2020 (1 second ago)
author : Dilbert <dilbert@cubicle.com>
issue  : [prog-1] Implement a hello-world program

  added reference 1
  > Prototype for the program.

date   : Fri May 29 15:57:16 2020 (1 second ago)
author : Dilbert <dilbert@cubicle.com>
issue  : [prog-1] Implement a hello-world program

  assigned to component prog from helloworld
  > This is a programming issue.

date   : Fri May 29 15:57:16 2020 (1 second ago)
author : Dilbert <dilbert@cubicle.com>
issue  : [prog-1] Implement a hello-world program

  created
  > I already have a prototype for this, off the Interweb.

Again, a numeric argument will show that many events.

Finally, there’s also a list command which, with no arguments, will list all issues in the database. If given a regexp argument, it will list only those issues whose description or comments match. Here’s an example:

Ditz: list world
_ prog-2: Prototype prints the Wrong Thing (bug)
_ prog-1: Implement a hello-world program (feature)

New in version 0.9: List-all-issues command.