bif - distributed bug tracking tool
bif COMMAND [ARGS...] [OPTIONS...]
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:
- Why bif exists and how to install it or get support or contribute.
- A list of common questions and answers.
- A tutorial-style introduction to bif.
- 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.
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.
- 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.
- 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.
- 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 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.
- 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.
- 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.
- A bif hub is a remote repository established for the purpose of exchanging updates. A hub's location (URL) usually has the form ssh://firstname.lastname@example.org. A hub is represented in the local repository as a sub-project of an org and its path is typically org.name/host.location.
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 email@example.com
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
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.
- 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:
$ bif push --help-tree
bif push ID DESTINATION [OPTIONS...]
bif push org PATH LOCATION [OPTIONS...]
bif push topic ID PATH... [OPTIONS...]
- Do not pipe normal output to a pager.
- 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".
- Some arguments and options not supplied on the command line are prompted for. An editor based on the
$VISUAL environment variables may also be invoked for certain types of input.
- 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.
- 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.
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.
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
we can make the following observations with regards how they are identified:
- .INTEGER (dot + [0-9]+) uniquely identifies the matching change ID.
- .:HEXIDECIMAL (dot + colon + [0-9a-f]+) identifies a change by its UUID when the match is long enough to be unique.
- User configuration file.
- User repository datatbase.
- Curent repository configuration file.
- Current repository database.
https://bifax.org/ for news and updates.
Mark Lawrence <firstname.lastname@example.org>
Copyright And License
Copyright 2013-2017 Mark Lawrence <email@example.com>
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.