lentil issue tracker - user manual

When I start a new project I litter my code with:

-- TODO: does outPop work with b/w terminals? [ansi]

Dealing with these is easy at first (with some help from unix utilities), but it becomes more and more unwieldy as the project expands. Migrating takes time and effort and I like the convenience of having bug reports detailed near the offending functions.

lentil helps you with housekeeping, querying, exporting issues without having to modify a single line of code.


Installation

(if you don’t want to compile it yourself, binaries are available)

lentil is written in Haskell, which you can easily grab from your OS repository (e.g. for Debian users apt-get install haskell-platform). Once you do that, installing lentil is as easy as:

cabal install lentil

The executable is located in .cabal/bin/; to make it available everywhere add this line to your .bashrc

export PATH=$PATH:~/.cabal/bin

If you prefer, you can use Stack:

stack install lentil

Stackage mainteinership is kindly provided by Luke Murphy, whom I thank!


Basic usage

To test lentil, fetch the example repository, unzip it, enter the folder and type:

lentil .

This should output a basic list of issues:

alpha.hs
   4  add prompt before getline, or the user might complain! [interface]
  11  add a type signature to replace [lint]

subfolder/beta.hs
   3  make export list explicit in Beta [lint]
   5  I think constants should not be exposed here, but imported from
      another package

You can specify more than one folder/path with lentil foldera folderb ... or exclude folders/paths with lentil . -x foldera/sub.

lentil scans directory recursively, not following symlinks, hidden folders (.git, .cabal, etc.) or folders starting with an underscore (_). Current working directory is indicated by a single dot (.).


Input format

lentil parses basic TODO issues. The precise syntax is: keyword (one of todo, fixme, xxx), optional semicolon, followed by a space, followed by free-form text (text can be multiline). In so many words, it is quite liberal in what it accepts:

-- These will all be accepted

// TODO: explanatory issue

// todo ehy you left an assert out there!

//Fixme bad coding style

/* Xxx: add to version control.
        Ask Timothy */

-- FIXME

You can optionally put tags at the end or at the beginning of your issue, like this:

// FIXME: Mr. Burns should enter from the *right* side of the
//        nuclear station [script] [priority:1]

-- todo: [rhyme] [magic] double trouble... I always forget the
--       words :s [memory]

Tags are single words which are useful to catalogue and identify issues. Use them aplenty as they will make slicing and dicing your issue-base a breeze. Since the semantic of FIXME and XXX is specific (in respect to the usual TODO), they are automatically added as a tag.

You can specify custom flag-words too, by using the -w option, e.g.:

lentil . -w hack

// HACK this issue will be parsed

User provided flagwords will have a tag automaticaly added (like FIXME and XXX).


Recognised files

As now lentil parses:

If you want a file type .xyz to be recognised as one in the list above, invoke lentil with an extension alias:

lentil . -a xyz%cpp

# multiple aliases
lentil . -a xyz%cpp -a qkw%js

but please please please contact me to have the extension(s) included in lentil natively, as this will make the program more convenient to use (if you want to speed up the process, please include a description of the comment syntax and string/character syntax too).


Query options

You can filter the issues to be displayed:

where EXPR is a valid regular expression. Examples:

# lists all issues with tag containing the string "bug"
lentil . -t bug

# lists all issues in files which name contains the
# string "ACME" or "foo"
lentil . -p "(ACME|foo)"

# lists all issues with tag containing the string "bug" and
# with "urgent" in the description
lentil . -p bug -d urgent

As the last example highlight, if you use these options together, they will be chained using a boolean AND.

To negate an EXPR use the corresponding capitalised option flags -T, -P, -D:

# lists all issues *without* the word "urgent" in their description
lentil . -D urgent

Orphan (tagless) issues are sometimes a nuisance, a handy way to list them is:

lentil . -T .


Format options

The -f TYPE option modifies the output format, with pretty being the default.

-f csv export issues to CSV (RFC 4180).

-f tagpop, lists tags by their popularity (reverse order), useful to get a summary of open issues:

lentil . -x test/test-files/ -f tagpop
Tags popularity:
     8  [feature:intermediate]
     6  [test]
     5  [feature:advanced]
     3  [bug]
     2  [refactor]
     2  [lint]
     2  [feature:basic]
     1  [urgency:3]
     1  [design]

-f comp displays issues in a format similar to the one emitted by compilers (GCC, GHC, etc.):

alpha.hs:4:
   add prompt before getline, or the user might complain! [interface]

alpha.hs:11:
   add a type signature to replace [lint]

This is useful because it is recognised by editors like EMACS, which can turn them into active links to the relevant file/position.


Other options

--output FILE is used to output the report to a file instead of stdout.

-v outputs the program version.

--help displays cheatsheet option help.


Tips

When output gets too big for a single screen, call lentil as:

lentil . | less -R

This will allow you to browse the issues in a pager without losing ANSI colour formatting.