Grub is a minimalist command-line tool intended to let solo programmers track issues and plans for their project. It maintains a single, human readable text file for each item, and keeps them in a folder that sits happily in your project directory, where they can be integrated cleanly into any revision control system.
◇◆◇◆◇◆◇◆◇◆◇◆◇◆◇◆◇◆◇
As one of the 3-Easy tools I’ve developed to support my ADHD work habits, Grub aims to be 1) easy to install, 2) easy to use, and 3) easy to understand. This makes it ideal for anyone who jumps from project to project and has a tendency to forget the operating principles and command sequences of more complicated tools.
File Contents
The design of grub is simple. Each file is a human-readable text file that contains:
-
title: a short statement of the issue
-
description: (optional) a more complete explanation of the situation
-
tags: a list of keyword flags to categorize the task
-
logs: a series of timestamped text entries reporting plans, ideas, and steps you’ve taken pertaining to this task
Basic Commands
grub init . Creates the grub folder in the current directory.
grub new -m "a problem to fix" Adds a new issue to the grub folder.
grub list [-t sometag] Shows a list of titles for all grub records. If the optional portion is given, the list will be limited to items that have the tag sometag.
grub log grubid Opens your default editor and let’s you type in a log entry that will be added to the indicated grub record. If your entry is short, you can use -m "Some quick note." to bypass the editor and add that string as the log entry directly. (See the section below for more about grubids.)
GrubIDs
Each issue file is stored in the grub folder and is named with a unique hash value that’s generated when the file is first created. Since the title of the issue is just a field inside that file, you can change the title later without harm. For example if you find a better way to summarize the issue, or need to divide it into two distinct issues.
When entering a command that targets a specific issue, you only need to provide a unique prefix of the id, so the grub list command includes the shortest unique prefix as part of the listing.
Tags
All state and classification management is done by applying, removing, or altering the tags in the grub files.
The core engine is terminology agnostic. You can use open/closed, active/inactive, reported/fixed, or whatever terminology you prefer for defining the states. You could even use longer state sequences if that’s how you like to roll, such as: open/confirmed/fixed/tested/closed. It’s all a matter of which tags you assign.
Out of the Box Aliases
In order to make grub useable out of the box, it comes preconfigured to use open/closed as the status values, and bug/feature/marketing as the three major domain categories.
For example grub lso is an alias to grub list -t open and will list all open tasks, while grub lsob will narrow that down and only list the open bugs. Similarly grub newb will create a new bug item, while grub newf will open a record for a new feature.
But this is all done entirely within grub’s command alias system, so you can customize it by changing the aliases defined in ~/.grubrc, which is grub’s global config file, located in your home directory.