BUGS(1)
NAME
bugs - distributed defect tracking system user program
SYNOPSIS
bugs [-x] [-NAORDPVFS] [-e] [-s] [-u user] ... [[-p] project] ...
bugs [-x] -b [bbox]
bugs [-x] -c
bugs [-x] -i id ...
DESCRIPTION
This is an interactive program used to create, manipulate,
and view bug reports. Manipulation of bugs consists of
changing bug fields and moving bugs from state to state, for
example, moving a bug from the open to resolved state.
If bugs is invoked with none of the above options, the
workspace will initially contain all unresolved (New,
Assigned, and Open) defects for all available projects.
The program's command syntax is intended to resemble that of
Mail(1), notes(1), and ex(1), so that users of those
programs can learn to use this one more easily.
As in Mail(1), the user deals with a workspace of individual
bug reports, each associated with a small integer displayed
at the front of the index line that summarizes the bug. A
workspace of bug reports may be "written" to a file, which
means that their defect ids (file names) are recorded so
that that group of bugs can be recalled later.
Each bug record may include one or more enclosures. An
enclosure is a file containing related free-format text,
such as a source file or details on how to reproduce the
bug. Each enclosure can be given its own title.
Options
When bugs is invoked the workspace initially contains those
bugs which match the characteristics selected by the command
line options. These options are:
-A Include bug reports that are Assigned to an engineer,
but not yet open.
-D Include bug reports that are classified as Duplicates
of other bug reports.
-F Include bug reports that have been Forwarded to a
project on a remote machine and the local machine does
not own or subscribe to that project. (Bugs forwarded
to projects that this machine owns or subscribes to
are available in their actual state in the new
project.)
-N Include Newly arrived bug reports.
-O Include bug reports that have been Opened by the
engineer.
-P Include bug reports that have been temporarily
Postponed.
-R Include Resolved bug reports.
-S Include bug reports that have been Submitted from this
machine to a project owned on a remote machine, but
that have not arrived on the remote machine yet.
(Bugs submitted to projects that this machine owns are
immediately placed in the New state rather than the
Submitted state.)
-V Include bug reports whose fix has been Verified.
-e Include only bug reports that are assigned to (or if
-s is specified, were submitted by) the user now
invoking bugs.
-s Include bug reports that were Submitted from this
machine. If any -u or -e options are present, bugs
qualify if they were submitted by the specified
user(s), instead of qualifying if they are assigned to
the user(s).
-u user
Include only bug reports that are assigned to (or if
-s is specified, were submitted by) the named user.
More than one user can be specified with multiple -u
options; in this case, only bug reports that are the
responsibility of one of the users are included.
The default with no -u options is to include all bug
reports matching the status selected by the above
options.
If the -s option is also specified, the criteria used
to select bug reports to be included is the submitter
of the defect, instead of the assigned engineer.
[-p] project
Include only bug reports that are the responsibility
of the named project. The default is for all
available projects to be considered. More than one
project can be specified; in this case, only bug
reports that are the responsibility of one of the
projects are included.
Shell-style patterns are supported for project names.
For example, the command
bugs -N lang* comp*
would browse all of the New bugs in all projects whose
names begin with lang or comp. If such an expression
is entered from the shell, the pattern characters must
be escaped or quoted. Thus, the above example could be
entered as:
$ bugs -N lang\* 'comp*'
Each project must reside on the local machine or the
local machine must be subscribing to the named project.
The -p flag before the project name is optional; it is
allowed for consistency with the other utilities.
-b This option specifies that the set of bug reports to
be used is contained in the named file bbox, which was
presumably created by saving a previously developed
workspace (see Workspace Manipulation Commands,
below), or by saving the output of findbug(1). If
bbox is omitted, the list is read from file bbox.
Only the -x option can be used in conjunction with
this form of invocation.
-c This option specifies that a new bug report is to be
created. This causes the program to start with an
empty workspace, and execute the "c" command (see
below) to create the new bug in the workspace. Only
the -x option can be used in conjunction with this
form of invocation.
-i This option specifies that the bug report(s) whose ids
are listed on the command line are to be used. Only
the -x option can be used in conjunction with this
form of invocation.
The following additional options may be used alone,
together, or with any of the above options:
-v If only one bug is in the workspace upon startup, this
option causes bugs(1) to display the base page of the
bug instead of the index (since there is really no
need to select one).
-x Security mode. Do not permit shell escapes, saving of
enclosures, or use of any of the workspace
manipulation commands to deal with bugbox files. This
can be useful in "captive shell scripts" that are
intended to be used by users with restricted
privileges.
Modes
Unless -v is specified, bugs starts out by displaying a
screenful of index lines, one for each bug in the workspace.
When you see these index lines, bugs is said to be in index
mode. Down the left-side of the screen are some line
numbers. To view a particular defect, enter its line number
and hit return. Or, move the little > arrow (using j and k
to move up and down) to an index line of interest and hit
<return>.
When you enter a line number or otherwise select an index
line, bugs displays a screen showing the full contents of
the bug record. When you see a screen like this, bugs is
said to be in viewing mode. By hitting the <space bar>, you
can view the enclosures.
Some commands do different things depending on the mode, but
they are all intended to be intuitive based on what you are
currently looking at.
You can enter ? at any prompt to see the list of commands
and precisely what they will do in the current mode.
For the purpose of discussion, the interactive commands of
bugs can be divided into various categories.
Defect Viewing Commands
num<cr> Display index line of bug number num, where
num is the small integer shown at the
beginning of the index line describing the
bug. If num is empty, select current line.
j, ^N Move to next bug.
k, ^P Move to previous bug.
<space> Display next screenful (of enclosures, of
next bug, of index lines).
^F, + Display next screenful of index lines.
^B, - Display previous screenful of index lines.
p Redisplay base page of current bug report.
/expr Search forward for a bug whose index line
contains a field matching the regular
expression expr. See ed(1) for the format
and meaning of regular expressions.
n, /<cr> Search forward for another bug matching the
same regular expression.
s Save a copy of current enclosure in a file.
i Display index lines (from viewing mode,
switch to index mode).
Defect Manipulation Commands
S Submit a new bug.
[num] A Assign (or reassign) selected bug to an
engineer.
[num] O Open (or reopen) selected bug.
[num] R Resolve selected bug.
[num] D Classify selected bug as a duplicate of
another.
[num] P Postpone the resolution of selected bug.
[num] V Affirm that the resolution of the selected
bug has been verified.
[num] F Forward (change project of) selected bug.
a Attach an enclosure to the bug being viewed.
v start up the cm integration (check in and
check out).
t Change the title of the enclosure being
viewed.
m Modify the fields of the bug being viewed (or
if currently viewing an enclosure, modify the
enclosure).
s Save a copy of current enclosure in a file.
d Delete the enclosure being viewed (if any),
or
delete the current index line from the
workspace.
c Clone (submit a copy of) the bug being viewed
(the project and other fields can then be
modified).
v Access the Configuration management interface
for files related to the current defect.
u Update the database. Commit changes to bugs
in the current session.
q Quit, warn if workspace was modified and not
written.
x Exit, quit and discard changes and new bugs
(warning if there are any).
Workspace Manipulation Commands
w [bbox] Write identifiers of bugs currently in workspace
to bbox.
e [bbox] Edit (replace workspace with) bugs identified by
the file bbox.
r bbox Merge bugs from named bbox with workspace.
f [bbox] Give a new name bbox to workspace.
^G Print current workspace name.
q, ^D Quit, warn if workspace was modified and not
written.
x Exit, discard changes and new bugs (warning
if there are any).
Changes to modified defects can be undone by using the m
command, or by exiting without saving the changes with the x
command.
Successful S or r commands mark the workspace "modified".
Successful w and e commands clear the "modified" marking.
Miscellaneous Commands
! [cmd ...] Run an interactive shell, or run the UNIX cmd
if present.
? Print a help summary for this mode.
Modifying Fields and State Transitions
While you are using any of the uppercase letter (state
transition) commands, or the m (modify bug fields) commands,
you will be prompted for several input values. Often there
will be a default value for the field (usually the current
value) offered, which you can accept by just hitting return.
Or, if you don't like the offered value, you can back over
it with your ERASE character (often ^H or DEL), or wipe out
entirely with your line KILL character (often ^U or ^X).
For fields whose values are restricted to one of a certain
list of multiple choices, you can just type a prefix of one
of the values and bugs will try to complete it for you
automatically.
If you make a typing mistake, and hit return, all is not
lost. You can use the escape character (ESC) to go back to
previously entered fields at any time during these commands.
If you ever decide while getting ready to answer a question
that you really don't want to do what you're doing at all,
type your interrupt character (often ^C or DEL). The
operation will abort, and bugs will tell you what happened.
As always with ClearDDTS, you can hit ? at any time, and the
question being asked or field being entered will be
explained in detail.
Conventions and Defaults
Bug numbers (indicated above as num) are positive integers
that select bugs from the workspace. If omitted, the
current bug (the one whose index line was last displayed, or
the bug indicated on the screen by the > sign) is usually
assumed.
If an optional bbox file argument is omitted, the current
name of the workspace is assumed. If there is no current
name, the name bbox is assumed.
Environment Variables
The following environment variables are used by bugs:
EDITOR The name of the editor to use when creating or
modifying enclosures. A temporary file name is
appended to the value of this variable and the
resulting command line is executed by /bin/sh.
Any command line that would result in the creation
of the named file is suitable. Thus, editing can
be made very simple with a setting such as:
EDITOR="clear; echo 'Enter text'; cat >"
If this variable is not defined, a value of vi is
assumed.
SHELL The name of the shell to use for shell escapes in
the ! command. If this variable is not defined,
/bin/sh is assumed.
SEE ALSO
findbug(1), dumpbug(1), sortbug(1)
ClearDDTS User's Guide