bts

bts - developers' command line interface to the BTS

This is a command line interface to the bug tracking system, intended mainly for use by developers. It lets the \s-1BTS\s0 be manipulated using simple commands that can be run at the prompt or in a script, does various sanity checks on the input, and constructs and sends a mail to the \s-1BTS\s0 control address for you.

In general, the command line interface is the same as what you would write in a mail to control@bugs.debian.org, just prefixed with “bts”. For example:

% bts severity 69042 normal % bts merge 69042 43233 % bts retitle 69042 blah blah

A few additional commands have been added for your convenience, and this program is less strict about what constitutes a valid bug number. For example, “severity Bug#85942 normal” is understood, as is “severity #85942 normal”. (Of course, your shell may regard “#” as a comment character though, so you may need to quote it!)

Also, for your convenience, this program allows you to abbreviate commands to the shortest unique substring (similar to how cvs lets you abbreviate commands). So it understands things like “bts cl 85942”.

It is also possible to include a comment in the mail sent to the \s-1BTS\s0. If your shell does not strip out the comment in a command like “bts severity 30321 normal #inflated severity”, then this program is smart enough to figure out where the comment is, and include it in the email. Note that most shells do strip out such comments before they get to the program, unless the comment is quoted. (Something like “bts severity #85942 normal” will not be treated as a comment!)

In most cases, adding a comment will cause the generated mail to be CCed to the bug report, in addition to control@bugs.debian.org.

You can specify multiple commands by separating them with a single dot, rather like update-rc.d; a single comma may also be used; all the commands will then be sent in a single mail. For example (quoting where necessary so that bts sees the comment):

% bts severity 95672 normal , merge 95672 95673 \#they\'re the same!

The abbreviation “it” may be used to refer to the last mentioned bug number, so you could write:

% bts severity 95672 wishlist, retitle it "bts: please add a --foo option"

Please use this program responsibly, and do take our users into consideration.

bts examines the devscripts configuration files as described below. Command line options override the configuration file settings, though.

"-o, Make bts use cached bugs for the 'show' and 'bugs' commands, if a cache is available for the requested data. See the cache command, below for information on setting up a cache.

"--online, Opposite of --offline; overrides any configuration file directive to work offline.

"--cache, Should we attempt to cache new versions of \s-1BTS\s0 pages when performing show/bugs commands? Default is to cache.

"--cache-mode={min|mbox|full}" When running a bts cache command, should we only mirror the basic bug (min), or should we also mirror the mbox version (mbox), or should we mirror the whole thing, including the mbox and the boring attachments to the \s-1BTS\s0 bug pages and the acknowledgement emails (full)? Default is min.

"--cache-delay=seconds" Time in seconds to delay between each download, to avoid hammering the \s-1BTS\s0 web server. Default is 5 seconds.

"--mbox" Open a mail reader to read the mbox corresponding to a given bug number for show and bugs commands.

"--mailreader=READER" Specify the command to read the mbox. Must contain a “%s” string (unquoted!), which will be replaced by the name of the mbox file. The command will be split on white space and will not be passed to a shell. Default is 'mutt -f CW%s'. (Also, %% will be substituted by a single % if this is needed.)

"--cc-addr=CC_EMAIL_ADDRESS" Send carbon copies to a list of users. \s-1CC_EMAIL_ADDRESS\s0 should be a comma-separated list of emails.

"--sendmail=SENDMAILCMD" Specify the sendmail command. The command will be split on white space and will not be passed to a shell. Default is '/usr/sbin/sendmail'. The -t option will be automatically added if the command is /usr/sbin/sendmail or /usr/sbin/exim*. For other mailers, if they require a -t option, this must be included in the \s-1SENDMAILCMD\s0, for example: --sendmail=“/usr/sbin/mymailer -t”

"--smtp-host=SMTPHOST" Specify an \s-1SMTP\s0 host. If given, bts will send mail by talking directly to this \s-1SMTP\s0 host rather than by invoking a sendmail command. Note that when sending directly via an \s-1SMTP\s0 host, specifying addresses in --cc-addr that the \s-1SMTP\s0 host will not relay will cause the \s-1SMTP\s0 host to reject the entire mail.

"-f, Download a bug report again, even if it does not appear to have changed since the last cache command. Useful if a --cache-mode=full is requested for the first time (otherwise unchanged bug reports will not be downloaded again, even if the boring bits have not been downloaded).

"--no-force-refresh" Suppress any configuration file --force-refresh option.

"--only-new" Download only new bugs when caching. Don't check for updates in bugs we already have.

"--include-resolved" When caching bug reports, include those that are marked as resolved. This is the default behaviour.

"--no-include-resolved" Reverse the behaviour of the previous option. That is, do not cache bugs that are marked as resolved.

"-q, When running bts cache, only display information about newly cached pages, not messages saying already cached. If this option is specified twice, only output error messages (to stderr).

"--no-conf, Do not read any configuration files. This can only be used as the first option given on the command-line.

For full details about the commands, see the \s-1BTS\s0 documentation. <http://www.debian.org/Bugs/server-control>

"show

"show

"show

"show

This is a synonym for bts bugs.

"bugs

"bugs

"bugs

"bugs

Display the page listing the requested bugs in a web browser using sensible-browser(1). Options may be specified after the “bugs” command in addition to or instead of options at the start of the command line: recognised options at his point are: -o/--offline/--online, --mbox, --mailreader and --[no-]cache. These are described earlier in this manpage. If either the -o or --offline option is used, or there is already an up-to-date copy in the local cache, the cached version will be used. The meanings of the possible arguments are as follows:

"(none)" If nothing is specified, bts bugs will display your bugs, assuming that either \s-1DEBEMAIL\s0 or \s-1EMAIL\s0 (examined in that order) is set to the appropriate email address.

"<bug Display bug number <bug number>.

"<package>" Display the bugs for the package <package>.

"src:<package>" Display the bugs for the source package <package>.

"<maintainer>" Display the bugs for the maintainer email address <maintainer>.

"from:<submitter>" Display the bugs for the submitter email address <submitter>.

"tag:<tag>" Display the bugs which are tagged with <tag>.

"usertag:<tag>" Display the bugs which are tagged with usertag <tag>. See the \s-1BTS\s0 documentation for more information on usertags. This will require the use of a users=<email> option.

":" Details of the bug tracking system itself, along with a bug-request page with more options than this script, can be found on http://bugs.debian.org/. This page itself will be opened if the command 'bts bugs :' is used.

"release-critical, Display the front page of the release-critical pages on the \s-1BTS\s0. This is a synonym for http://bugs.debian.org/release-critical/index.html. It is also possible to say release-critical/debian/main.html and the like. \s-1RC\s0 is a synonym for release-critical/other/all.html.

"select Uses the \s-1SOAP\s0 interface to output a list of bugs which match the given selection requirements. The following keys are allowed, and may be given multiple times.

"package" Binary package name.

"source" Source package name.

"maintainer" E-mail address of the maintainer.

"submitter" E-mail address of the submitter.

"severity" Bug severity.

"status" Status of the bug.

"tag" Tags applied to the bug. If users is specified, may include usertags in addition to the standard tags.

"owner" Bug's owner.

"bugs" List of bugs to search within.

"users" Users to use when looking up usertags.

"archive" Whether to search archived bugs or normal bugs; defaults to 0 (i.e. only search normal bugs). As a special case, if archive is 'both', both archived and unarchived bugs are returned.

"clone The clone control command allows you to duplicate a bug report. It is useful in the case where a single report actually indicates that multiple distinct bugs have occurred. “New IDs” are negative numbers, separated by spaces, which may be used in subsequent control commands to refer to the newly duplicated bugs. A new report is generated for each new \s-1ID\s0.

"reopen Reopen a bug, with optional submitter.

"archive Archive a bug that has previously been archived but is currently not. The bug must fulfil all of the requirements for archiving with the exception of those that are time-based.

"unarchive Unarchive a bug that is currently archived.

"retitle Change the title of the bug.

"submitter Change the submitter address of a bug or a number of bugs, with `!' meaning `use the address on the current email as the new submitter address'.

"reassign Reassign a bug or a number of bugs to a different package. The version field is optional; see the explanation at <http://www.debian.org/Bugs/server-control>.

"found Indicate that a bug was found to exist in a particular package version.

"notfound Remove the record that bug was encountered in the given version of the package to which it is assigned.

"fixed Indicate that a bug was fixed in a particular package version, without affecting the bug's open/closed status.

"notfixed Remove the record that a bug was fixed in the given version of the package to which it is assigned. This is equivalent to the sequence of commands “found <bug> <version>”, “notfound <bug> <version>”.

"block Note that a bug is blocked from being fixed by a set of other bugs.

"unblock Note that a bug is no longer blocked from being fixed by a set of other bugs.

"merge Merge a set of bugs together.

"forcemerge Forcibly merge a set of bugs together.

"unmerge Unmerge a bug.

"tag

"tags

Set or unset a tag on a bug. The tag may either be the exact tag name or it may be abbreviated to any unique tag substring. (So using “fixed” will set the tag “fixed”, not “fixed-upstream”, for example, but “fix” would not be acceptable.) Multiple tags may be specified as well. The two commands (tag and tags) are identical. At least one tag must be specified, unless the '=' flag is used, where the command bts tags <bug> = will remove all tags from the specified bug.

"user Specify a user email address before using the usertags command.

"usertag

"usertags

Set or unset a user tag on a bug. The tag must be the exact tag name wanted; there are no defaults or checking of tag names. Multiple tags may be specified as well. The two commands (usertag and usertags) are identical. At least one tag must be specified, unless the '=' flag is used, where the command bts usertags <bug> = will remove all user tags from the specified bug.

"claim Record that you have claimed a bug (e.g. for a bug squashing party). If no claim is specified, the environment variable \s-1DEBEMAIL\s0 or \s-1EMAIL\s0 (checked in that order) is used.

"unclaim Remove the record that you have claimed a bug. If no claim is specified, the environment variable \s-1DEBEMAIL\s0 or \s-1EMAIL\s0 (checked in that order) is used.

"severity Change the severity of a bug. Available severities are: wishlist, minor, normal, important, serious, grave, critical. The severity may be abbreviated to any unique substring.

"forwarded Mark the bug as forwarded to the given email address.

"notforwarded Mark a bug as not forwarded.

"package The following commands will only apply to bugs against the listed packages; this acts as a safety mechanism for the \s-1BTS\s0. If no packages are listed, this check is turned off again.

"owner Change the “owner” address of a bug, with `!' meaning `use the address on the current email as the new owner address'. The owner of a bug accepts responsibility for dealing with it. Note that the “owner” of a bug does not automatically receive all of the email corresponding to it; use “subscribe” to achieve that.

"noowner Mark a bug as having no “owner”.

"subscribe Subscribe the given email address to the specified bug report. If no email address is specified, the environment variable \s-1DEBEMAIL\s0 or \s-1EMAIL\s0 (in that order) is used. If those are not set, or `!' is given as email address, your default address will be used. After executing this command, you will be sent a subscription confirmation to which you have to reply. When subscribed to a bug report, you receive all relevant emails and notifications. Use the unsubscribe command to unsubscribe.

"unsubscribe Unsubscribe the given email address from the specified bug report. As with subscribe above, if no email address is specified, the environment variables \s-1DEBEMAIL\s0 or \s-1EMAIL\s0 (in that order) is used. If those are not set, or `!' is given as email address, your default address will be used. After executing this command, you will be sent an unsubscription confirmation to which you have to reply. Use the subscribe command to, well, subscribe.

"reportspam The reportspam command allows you to report a bug report as containing spam. It saves one from having to go to the bug web page to do so.

"spamreport spamreport is a synonym for reportspam.

"cache

"cache

Generate or update a cache of bug reports for the given email address or package. By default it downloads all bugs belonging to the email address in the \s-1DEBEMAIL\s0 environment variable (or the \s-1EMAIL\s0 environment variable if \s-1DEBEMAIL\s0 is unset). This command may be repeated to cache bugs belonging to several people or packages. If multiple packages or addresses are supplied, bugs belonging to any of the arguments will be cached; those belonging to more than one of the arguments will only be downloaded once. The cached bugs are stored in ~/.devscripts_cache/bts/ You can use the cached bugs with the -o switch. For example: bts -o bugs bts -o show 12345 Also, bts will update the files in it in a piecemeal fashion as it downloads information from the \s-1BTS\s0 using the 'show' command. You might thus set up the cache, and update the whole thing once a week, while letting the automatic cache updates update the bugs you frequently refer to during the week. Some options affect the behaviour of the cache command. The first is the setting of --cache-mode, which controls how much bts downloads of the referenced links from the bug page, including boring bits such as the acknowledgement emails, emails to the control bot, and the mbox version of the bug report. It can take three values: min (the minimum), mbox (download the minimum plus the mbox version of the bug report) or full (the whole works). The second is --force-refresh or -f, which forces the download, even if the cached bug report is up-to-date. The --include-resolved option indicates whether bug reports marked as resolved should be downloaded during caching. Each of these is configurable from the configuration file, as described below. They may also be specified after the “cache” command as well as at the start of the command line. Finally, -q or --quiet will suppress messages about caches being up-to-date, and giving the option twice will suppress all cache messages (except for error messages). Beware of caching \s-1RC\s0, though: it will take a \s-1LONG\s0 time! (With 1000+ \s-1RC\s0 bugs and a delay of 5 seconds between bugs, you're looking at a minimum of 1.5 hours, and probably significantly more than that.)

"cleancache

"cleancache

Clean the cache for the specified package, maintainer, etc., as described above for the “bugs” command, or clean the entire cache if “\s-1ALL\s0” is specified. This is useful if you are going to have permanent network access or if the database has become corrupted for some reason. Note that for safety, this command does not default to the value of \s-1DEBEMAIL\s0 or \s-1EMAIL\s0.

"version" Display version and copyright information.

"help" Display a short summary of commands, suspiciously similar to parts of this man page.

"\s-1DEBEMAIL\s0" If this is set, the From: line in the email will be set to use this email address instead of your normal email address (as would be determined by mail).

"\s-1DEBFULLNAME\s0" If \s-1DEBEMAIL\s0 is set, \s-1DEBFULLNAME\s0 is examined to determine the full name to use; if this is not set, bts attempts to determine a name from your passwd entry.

"\s-1BROWSER\s0" If set, it specifies the browser to use for the 'show' and 'bugs' options. See the description above.

The two configuration files /etc/devscripts.conf and ~/.devscripts are sourced by a shell in that order to set configuration variables. Command line options can be used to override configuration file settings. Environment variable settings are ignored for this purpose. The currently recognised variables are:

"\s-1BTS_OFFLINE\s0" If this is set to yes, then it is the same as the --offline command line parameter being used. Only has an effect on the show and bugs commands. The default is no. See the description of the show command above for more information.

"\s-1BTS_CACHE\s0" If this is set to no, then it is the same as the --no-cache command line parameter being used. Only has an effect on the show and bug commands. The default is yes. Again, see the show command above for more information.

"BTS_CACHE_MODE={min,mbox,full}" How much of the \s-1BTS\s0 should we mirror when we are asked to cache something? Just the minimum, or also the mbox or the whole thing? The default is min, and it has the same meaning as the --cache-mode command line parameter. Only has an effect on the cache. See the cache command for more information.

"\s-1BTS_FORCE_REFRESH\s0" If this is set to yes, then it is the same as the --force-refresh command line parameter being used. Only has an effect on the cache command. The default is no. See the cache command for more information.

"\s-1BTS_MAIL_READER\s0" If this is set, specifies a mail reader to use instead of mutt. Same as the --mailreader command line option.

"\s-1BTS_SENDMAIL_COMMAND\s0" If this is set, specifies a sendmail command to use instead of /usr/sbin/sendmail. Same as the --sendmail command line option.

"\s-1BTS_ONLY_NEW\s0" Download only new bugs when caching. Don't check for updates in bugs we already have.

"\s-1BTS_SMTP_HOST\s0" If this is set, specifies an \s-1SMTP\s0 host to use for sending mail rather than using the sendmail command. Same as the --smtp-host command line option. Note that this option takes priority over \s-1BTS_SENDMAIL_COMMAND\s0 if both are set, unless the --sendmail option is used.

"\s-1BTS_INCLUDE_RESOLVED\s0" If this is set to no, then it is the same as the --no-include-resolved command line parameter being used. Only has an effect on the cache command. The default is yes. See the cache command for more information.

This program is Copyright (C) 2001-2003 by Joey Hess <joeyh@debian.org>. Many modifications have been made, Copyright (C) 2002-2005 Julian Gilbey <jdg@debian.org> and Copyright (C) 2007 Josh Triplett <josh@freedesktop.org>. It is licensed under the terms of the \s-1GPL\s0, either version 2 of the License, or (at your option) any later version.