Cardigan

A simple command line project task tracking tool.

Rationale

  • command line tools are faster and cooler than any gui or web interface

  • it makes sense to store work items in your source repository

  • tab completion is awesome

Installation

gem install cardigan

Usage

cardigan

This will prompt for your name and email address (and store them in ~/.cardigan), create a folder called .cards in the current directory and enter a shell. The idea is that you will run this at the root of a git/hg/svn/whatever repository and manage the cards in the same way you manage your source code.

cardigan >

So what now?

Listing mode

You start in listing mode.

The commands available are (with the awesome power of tab completion):

  • quit or exit or ctrl-d - exit

  • list - shows all cards with an index

  • filter <filter> - sets the filter for cards - this is ruby code such as card.start_with?(‘a’)

  • claim <numbers> - sets the owner of the specified cards (by index from the list)

  • unclaim <numbers> - removes the owner from the specified cards (by index from the list)

  • create <name> - creates a card with the specified name

  • open <name> - creates or opens the card and enters edit mode

  • display <columns> - lists or changes the columns to be displayed by the list command

  • sort <columns> - lists or changes the columns to be used for sorting by the list command

  • destroy <numbers> - deletes the specified cards (by index from the list)

  • set <key> <numbers> - prompts for a field value and sets it on all specified cards (by index from the list)

  • workflow - enters workflow editing mode

  • count <grouping fields> - counts the number of cards for each combination of the grouping fields

  • total <numeric field> <grouping fields> - calculates the total of the specified numeric field for each combination of the grouping fields

  • export <filename> - writes all columns for current filtered cards to <filename>.csv

  • import <filename> - imports all cards from <filename>.csv - cards will be updated with a matching id, otherwise new cards will be created.

Editing mode

  • quit or exit or ctrl-d - exit

  • list - dumps the values of all card field values

  • set <key> - creates a new field and prompts for the new value

  • now <status> - changes the status of the card to the given status (the tab completion will be populated with the valid subsequent statuses from the current status)

Workflow mode

Workflow is pretty simple - it is just for convenience in specifiying the set of valid transitions for cards with a specific status.

The only purpose is to populate tab completion for the ‘now’ command in edit mode for a card.

  • quit or exit or ctrl-d - exit

  • list - dumps the current workflow (statuses with their valid subsequent statuses)

  • create <status> - creates a new status

  • add <status> <statuses> - add the specified statuses as valid transitions from status

  • remove <status> <statuses> - remove the specified statuses as valid transitions from status

Walkthroughs

In case this documentation makes no sense at all, a few usage scenarios can be found here: gist.github.com/331647

Future plans

Refer to the .cards for detailed story breakdown but automatic vcs interaction and generating pretty html reports/charts seem to be the most important missing features.