A bare-bones command-line bug tracking system for personal or small projects which require little formality.


Add this line to your application’s Gemfile:

  gem 'beastie'

And then execute:

  $ bundle

Or install it yourself as:

  $ gem install beastie


Beastie is a bug tracking system at its bare essentials.

Main commands:

beastie new
asks information about an issue and generate a YAML file in the current directory.
beastie nedit
enter a new issue using the default editor (nedit = new and edit; see edit for the specificaiton of the editor)
beastie list
reads all YAML files in the current directory and generate a list of all the issues.
beastie show N
shows issue N, where N is the identifier shown by the beastie list command.
beastie edit N
edits issue N. The commands invokes the editor set in the shell EDITOR variable or use emacsclient if EDITOR is unset.
beastie help
unleashes the real power of beastie.

Managing Different Projects

By default beastie uses the current directory when executing a command. While this makes gives a lot of freedom in choosing one’s standards, it also require a lot of discipline (you always need to make sure you are in the right directory) and can be inconvenient at times.

For this reason, from version 0.3, beastie supports the following two options to specify the directory to use when executing a command:

  • option -d (--directory) to specify the destination directory
  • option -p (--project) to use a specific project for a directory

Option -d. Use -d <dir> (or --directory <dir>) to specify the directory in which the command is executed.

For instance:

  beastie show -d ~/issues

will show all issues stored in the ~/issue directory.

Option -p. Use -p <name> (or --project <name>) to specify the name of a project and beastie will perform the operation on the directory associated to <name> in the ~/.beastie_projects file.

Entries in the .beastie_projects file look like:

  dir: <dir>
<another name>:
  dir: <another dir>

For instance, if .beastie_projects contains:

    dir: /Users/guest/beastie_issues


  $ beastie show -p beastie

will show all the issues stored in the /Users/guest/beastie_issues directory.

Use only one of -d or -p; if you do not, -d has precedence.


Beastie has support for filtering data, using the --where option. The option takes as argument an expression (written in Ruby), defining what issues have to be printed.

For instance:

  beastie list --where "status == 'open'"

will show only the open issues. More complex expressions can be defined, using Boolean operators:

  beastie list --where "status == 'open' and priority >= 4"

will show open issues with priority greater or equal to 4.

Notice that the expression passes as argument to --where is evaluated in Ruby, so any Ruby expression will work.

Since, after the initial excitement, typing --where "status == 'open'" becomes quite boring, the following shortcuts are available:

  • --status STATUS, to select by status
  • --type TYPE, to select by type

the options are put in and. So, for instance:

beastie —status open —type bug —where “priority > 3”

will select the open issues, with type bug and priority greater than 3.

Remarks and Warnings

Beastie generates human-readable filenames, following the convention Jekyll has for blog posts. Selecting issues using filenames, however, is a bit clumsy and to simplify operations beastie assigns a number to each issue, which can be used to reference them. The number can be seen with the list command and depends upon the order in which issues are listed in the directory. Thus the same issue might be assigned a different id over time, if the order in which files are read changes (e.g., if a new back-dated issue is added by hand).

Beastie does not have a specific workflow for bug statutes.

Beastie does not perform syntax checks when reading data. This can be changed by specifying appropriate input functions in the ISSUE_FIELDS variable (lib/beastie/issue.rb).

Beastie asks various information about a bug. Change the ISSUE_FIELDS variable, if you are not happy with the default fieldset.

Sorting its on the way (but not yet implemented). Use the power of Unix for that. For instance:

  beastie list | grep -v "^ID" | sort -n -k 4

Similar solutions

There are different command-line bug tracking systems. The ones I came across with before re-inventing the wheel include: ditz, bugs everywhere, ticgit-Ng, bugzyrb, git-issues, later.

So… why did I re-invent the wheel?

  1. for fun
  2. human-readable filenames, so that I can manage issues without using beastie, if I want
  3. a “programmable” fieldset (see lib/beastie/issue.rb)
  4. keeping the solution simple (280 lines of ruby code, according to sloccount)

Use beastie! According to sloccount, you will be using, for free, a software which costed $4,490 to produce! (This is less than the cost of v 0.3, which was estimated at $8,000. Jekyll mercenary, in fact, lowered the number of lines of code and the costs estimated with COCOMO.)


Adolfo Villafiorita




1. Fork it 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am ‘Add some feature’`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create new Pull Request