01) High-level Issue Representation
02) Command Line Interface
02.1) Initializing a Hive Database
02.2) Adding Issues
02.3) Viewing Issues
02.4) Editing Issues
02.5) Committing Changes
02.6) Managing Labels
03) Web Interface
04) Searching for Issues
05) Data Format Details
All of Hive's data are stored files inside of a directory called
the root of your repository (next to
.git). These files are
version-controlled alongside the other files in your repository.
Logically, each issue consists of several pieces of information:
hive probably does not require understanding how these things are
actually represented on disk, but if you're interested in that kind of thing,
the last section on this page describes the representation in a bit more
The main means of interacting with issues stored in
hive is via the command
line interface. Running
hive --help will show a list of possible commands,
some of which are described below.
You can set up the necessary database structure for
hive by running the
following command from within a Mercurial or Git repository:
$ hive init
-c flag will commit the new (empty) structure to the repository.
-c is set, you can specify a commit message with
-m MESSAGE; if you
don't specify such a message, a default message will be used.
You can create a new issue using the
$ hive new
or by its alias,
$ hive add
In either case, you will be prompted for a title, and then an editor will open,
which you can use to enter the body of the issue. Or, if you provide the
--stdin flag, the body will be read from stdin and no editor will be opened.
If you want to create an issue with an empty body, you will need to provide the
new command also takes a large number of optional arguments that can
modify the initial state of the issue, including:
--title TITLEto set the title without an interactive prompt
--label LABELto associate a label with the issue. This can be used arbitrarily many times to associated multiple labels, e.g.
hive add -l LABEL1 -l LABEL2 ...
-p PRIORITYsets the issue's priority (defaults to 0)
--assignee NAMEto assign the issue to someone. Like
-l, this can be used arbitrarily many times.
--target TARGETto set the issue's target
You can view a summary of existing issues with:
$ hive list
or, for short,
$ hive ls
By default, this command displays all issues; but it also accepts search terms
as arguments, for viewing a subset of issues (see the section on "Searching for
Issues" for more details of the kinds of search terms you can use).
Additionally, providing the
--all flag or specifying
status:any as a search
term will include closed issues in the listing.
You can view the details with the
show command, which takes an issue ID (or a
prefix thereof) as an argument:
$ hive show ID
This will show a summary of the issue, including the full text of its body and comments, if any.
Most of the parameters that can be set when creating an issue can also be modified ex post facto using a command:
hive label ISSUE_ID LABEL1 LABEL2 ...adds labels to the issue with the given ID. If the
-dflag is provided, this command removes the labels instead of adding them.
hive assign ISSUE_ID NAME1 NAME2 ...adds assignees to the issue. You can use the
--meflag to assign yourself instead of giving names. If
-dis provided, remove the given assignees instead of adding them.
hive priority ISSUE_ID PRIORITYsets the given issue's priority.
hive target ISSUE_ID TARGETsets the given issue's target.
Issues can be closed by running
hive close ISSUE_ID, and closed issues can be
hive open ISSUE_ID.
Eventually, after making local changes to your issues, you will want to commit
those changes (and, maybe, to push them to a remote server). Since
stores its issues in regular files, you are welcome to manage this process
hive also provides a
commit command, which does some
additional optimizations before committing.
$ hive commit
You can also provide a custom message with
-m MESSAGE; if you don't provide
one, a default message will be used.
Arbitrary labels can always be assigned to issues, but sometimes it is helpful
to change the "look and feel" of a particular label. To this end, the
edit-label command can be used to store information about a label, including
a description and the colors that should be used when displaying the label.
$ hive edit-label LABEL
This command will prompt for a description, as well as foreground and background colors in HTML hex format.
hive also includes a simple web interface for interacting with issues.
As of right now, the web interface is read-only (i.e., it cannot be used to
modify issues, only to view them). The plan is for the web interface
eventually to include support for editing issues, and also for interaction via
the web (so that users can submit issues without requiring a local installation
You can start a local server to serve the web interface by running
from a repository managed with
hive. Passing the
-b flag to
will launch a web browser pointed at the right place; or, you can manually
http://localhost:5000 after starting the server.
If you are planning on using this to host a public-facing issue tracker, you
can use NGINX as a reverse proxy. If the root URL of the
issue tracker is not
/, you can provide a base URL with
-u. This should
not include a trailing slash. For example, the Hive issue tracker at
https://hz.mit.edu/hive/bugs was launched with
hive web -u /hive/bugs.
The default view in the web interface, as well as the usual output of
ls, is a listing of all open issues. You can narrow the set of issues that
are displayed through searching.
In the command line interface, search terms should be given after
hive ls search_term search_term .... In the web interface, they
can be typed into the search bar.
In both cases, words separated by spaces are searched for separately, but
quotation marks can be used to search for longer terms. For example, searching
laser beam will search for issues that contain both the word "laser" and
the word "beam", but searching for
"laser beam" will search for issues that
contain the phrase "laser beam".
Certain prefixes affect the way a search proceeds. For example:
label:enhancementsearches for issues with the "enhancement" label
id:a2esearches for issues whose ID starts with "a2e"
priority:2searches for issues whose priority is equal to 2
priority>:2searches for issues with priority greater than 2
priority<:2searches for issues with priority less than 2
status:opensearches for open issues
status:closedsearches for closed issues
body:textsearches for the given text in the issue's body only
title:textsearches for the given text in the issue's title only
author:textsearches for the given text in the issue's author name only
Generally speaking, it should not be necessary to deal with
directly, but you never know. This section describes the structures
uses to represent issues and related information. Some of these design choices
were inspired by other distributed issue trackers, particularly Bugs
This section describes the data format version 1.
All of Hive's data are stored in a directory called
.hive-bt in the root of
your repository (next to
.git). Inside of this directory, you'll
find a file called
version containing information about the version of the
data format used in that directory. Other information about the issues is
stored in a few subdirectories, described below.
Information about labels is contained in a directory called
file in this directory corresponds to a single label. For example, a file
wontfix describes a label called
wontfix. Each of these files
contains a single JSON object with zero or more of the following keys:
descriptionshould map to a string containing a description of the tag. This description cannot contain any formatting; it will be interpreted verbatim as a description.
fgcolordescribe the colors that should be used to display the label. If they are not both specified, simple defaults will be used. Both the command-line interface and the web interface will use these colors.
Labels not present in this directory can still be assigned to issues, but the
interfaces will assume an empty description and use default colors for issues
not described in the
Valid label names can contain arbitrary characters, except for colons (
), backslashes (
\), forward slashes (
/), and periods (
which are not allowed in label names because of the ways labels are represented
and used internally. In particular, slashes are disallowed because they are
path separators; colons are disallowed because they are not part of valid
filenames on Windows; spaces are disallowed because of the way the web
interface applies styles to issues; and periods are disallowed as an easy way
to prevent the
.keep file in the
labels directory from being treated as a label.
Information about targets is contained in a directory called
file in this directory corresponds to a target, and contains a single JSON
object with zero or more of the following keys:
due_date should map to a string containing a date in
specifying when the target is due.
description should map to a string containing a description of the target.
active should map to a boolean indicating whether the target is still
As with labels, it is possible to assign issues to targets that are not present in this directory, or to have targets that do not specify all of the above keys. In those cases, default values will be assumed.
Valid target names follow the same rules as valid label names.
Information about the issues themselves is stored in a directory called
issues directory will contain multiple subdirectories, one for
each issue. Each issue is identified by a 64-character hex sequence; the first
32 characters are a digest of a UUID (version 4), and the last 32 characters
are the MD5 hash of the initial parameters.
Each issue's directory contains one or more files, each of which represents a series of one or more changes to the state of that issue. Each of these files' names consists of three fields: a logical timestamp, a UNIX timestamp, and an MD5 hash of the contents. Each file contains a JSON array, containing JSON objects representing each action in the series.
Most commands create files representing a single change to an issue, but these
files can later be combined together when committing issues to the repository,
in order to minimize the number of extra files
hive adds to the repository
Storing changes to issues (rather than storing the issue's current state) and
using these particular naming conventions affords a large degree of "merge
tolerance," in the sense that two people can work on issues separately but
still end up with a consistent internal state after a merge, with no manual
intervention. Merge conflicts on issues should be exceedingly rare; the hope
would be that they can only really occur if multiple people are manually
hive pack separately and committing the results.
One obvious downside of this representation is that operations on these
structures can be slow, since determining the current state of an issue
requires looping over all actions associated with the issue. To mitigate this
hive caches information about issues and refers to the cache when