Name

bif - distributed bug tracking tool

Version

0.1.5_8 (yyyy-mm-dd)

Synopsis

  bif COMMAND [ARGS...] [OPTIONS...]

Description

Bif is a distributed topic tracker with a command-line interface. It tracks bugs, tasks and issues in a local database, and exchanges updates with remote "hub" databases.

This document is the beginning of the bif reference material. If you are new to bif you will probably find one of the following a more helpful starting point:

bif-doc-about: Why bif exists and how to install it or get support or contribute.
bif-doc-faq: A list of common questions and answers.
bif-doc-intro: A tutorial-style introduction to bif.
bif-doc-toc: The table of contents for all bif documentation.

The above are also valid commands; you can run bif doc intro for example to read the tutorial. Likewise, bif doc command name displays the bif-command-name reference document.

General Concepts

The bif command is both a local project management application and a network client that communicates with a server process. The following terminology definitions are intended to provide some insight into how bif manipulates and exchanges information.

Repository: A bif repository is a configuration file and an SQLite database inside a .bif/ directory. The database contains the change history, current values and relationships of a set of nodes. All bif commands find the current working repository by searching upwards through the file-system for such a directory. The terms repository and database are often used interchangeably.
Node: At a low level every "thing" in a bif repository (e.g. a bug or an issue or a project) is a node. They are arranged in tree structures and have paths similar to UNIX filesystems. Nodes can always be identified by an integer "ID" which is unique to the local repository. They also have a hexadecimal ":UUID" which is globally unique.
Change: Every user action in a bif repository is recorded as a "change." A change usually consists of a comment and one or more deltas to nodes. A change has an integer ".ID" unique to the local repository as well as a globally unique hexadecimal ".:UUID".
Topic: Topic is is a catch-all term for a task, issue, bug, feature, etc. and consist of a discussion plus meta data (e.g. status). Topics can be associated with multiple projects in which case they have multiple IDs and multiple status values.
Project: A project is like a topic that comes with the extra functionality of grouping tasks and issues together. Multiple projects can be managed within a repository, and sub-projects can be defined hierarchically. Projects are usually identified by their node path.
Org: There exists sometimes the need to distinguish between the organisation running a project and the project itself. For this reason bif provides a special "org" project type to hold projects and hub locations together. Some care should be taken when naming orgs (or a top-level project that may become an org) to ensure they are globally unique, or at least unique amongst all the other projects they may interact with.
Hub: A bif hub is a remote repository established for the purpose of exchanging updates. A hub's location (URL) usually has the form ssh://org.name@host.location. A hub is represented in the local repository as a sub-project of an org and its path is typically org.name/host.location.

Command Structure

The most common top-level user commands are as follows:

clone        import topics from a hub
doc          display bif documentation
init         initialize a new repository
list         list topics in the repository
log          view comments and status history
move         move or rename a topic or project
new          create a new topic
show         display a topic's current status
sync         exchange changes with hubs
update       comment on or modify a topic
work         start or stop working a topic

In addition to the above commands a couple of useful aliases are created by default:

ls              list topics --status open --project-status run
lsi             list identities
lsp             list projects define plan run
lss             list topics --status stalled --project-status run

Aliases are read from the users config file (usually located in the $HOME/.config/bif directory).

There are more commands for development and infrequent administration purposes which can be seen with bif --help or found in the table of contents bif-doc-toc.

Principles of Operation

The first thing a bif user must do is the one-time activity of creating a "self" identity in the user repository.

$ bif init self

A normal (working) repository can then be created with bif-init.

$ bif init

Projects and topics can be locally defined using bif-new commands.

$ bif new project x Project-X

Collaborative organisations (and their projects) are imported from a hub using bif-clone.

$ bif clone organisation@bif.hub.host

Items in the database can be listed (bif-list), viewed (bif-show) and modified (bif-update) independently of any other repository. Topics can be moved (bif-move) to other projects or "shared" with them using bif-push.

$ bif list
$ bif update x --message "an update"

The bif-log command displays the history of respository and topic actions and has options for summarizing activity by increasing levels of aggregation.

Updates are exchanged with the relevant hubs by the bif-sync command. The program that responds to bif requests on the hub is called bifax and is usually accessed over an SSH tunnel. The bif-push command (in addition to sharing topics) allows administrators to copy an organisation node to a hub (kind of like a reverse clone).

The bif-work command allows the user to record time spent on a project or topic, which can be reviewed with bif-show-work.

$ bif work x 10:00 11:30 --message "did stuff"
$ bif show work

Global Options

The following options are common to all commands:

--debug, -D: Directs debugging and error messages to stdout and turns on the pager (unless --no-pager option is used).
--help, -h: Print a full usage message to stderr and exit. Some arguments and options are only shown when this option is used; a normal usage/error message may keep some rarely used options hidden.
--help-tree: Print the bif command hierarchy to stderr and exit. This is the easiest way to see what all of the bif commands are. You can also call this on subcommands to reduce the list:
--no-pager: Do not pipe normal output to a pager.
--user-repo: Run commands against the user repository instead of the current repository.
--version, -V: Print the bif version number (and commit hash) and exit. If used twice then a complete version string is printed using bif-show-version.

A boolean option can be negated by prefixing it with "no-" as in "--no-debug".

Command Interaction

Input: Some arguments and options not supplied on the command line are prompted for. An editor based on the $EDITOR or $VISUAL environment variables may also be invoked for certain types of input.
Output: Normal output is printed to stdout or sometimes paged with a $PAGER when stdout is connected to a terminal. Error messages are sent to stderr except when --debug is in use.
Connectivity: The only commands that (may) involve network communication are bif-clone, bif-push, and bif-sync. Everything else is a local action.
Exit Status: An exit value of zero indicates success.

Node Identification

Given the following nodes in the respository:

ID      Type        Path                 UUID
--      ----        ----                 ----
1       org         my.org               775da00c
2       project     my.org/build         0eaa2495
3       task        my.org/build/3       a922ec59
4       project     my.org/build/admin   8f4118aa
5       project     my.org/release       e5fd7da7
6       issue       my.org/release/6     cc87ea8b
7       project     my.org/release/admin 17257b3c

we can make the following observations with regards how they are identified:

INTEGER uniquely identifies the matching node ID.
:HEXIDECIMAL (colon + [0-9a-f]+) identifies a node by its UUID when the match is long enough to be unique.
The name "my.org" uniquely identifies the org with ID 1
The name "build" uniquely identifies the project with ID 2
The name "admin" does not uniquely distinguish "my.org/build/admin" from "my.org/release/admin".
However the name "release/admin" does uniquely identify the project with ID 7.

Note that you should not give projects integer names.

Change Identification

Similarly to nodes, given the following changes in the repository:

ID      Type        Command              UUID
--      ----        ------------------   ----
1       change      new org ...          c114be2a
2       change      new project ...      4866b4a9
3       change      new task ...         a82d149b
4       change      new issue ...        a8afeb33
5       change      update issue ...     7d912a0c