--------------------------------------------------------------------------------
title: lentil manual
author: Francesco Ariis
summary: lentil issue tracker user manual
tags: lentil,issue,bug,issue tracker,bug tracker,manual
published: 2015-06-09 00:00:00
revised: 2015-06-10 00:00:00
--------------------------------------------------------------------------------
==================================
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.
.. _`lentil`: http://ariis.it/static/articles/lentil/page.html
.. raw:: html
Installation
------------
(if you don't want to compile it yourself, `binaries`_ are available)
.. _`binaries`: http://ariis.it/link/repos/lentil/bin/
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
.. raw:: html
Basic usage
-----------
To test lentil, fetch the `example repository`_, unzip it, enter the folder
and type:
.. _`example repository`: test.zip
::
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. Current working
directory is indicated by a single dot (``.``).
.. raw:: html
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 of your issue, like this:
::
// FIXME: Mr. Burns should enter from the *right* side of the
// nuclear station [script] [priority:1]
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.
As now lentil parses:
- haskell source files (``.hs``, ``.lhs``)
- C source files (``.c``, ``.h``), C++ (``.cpp``, ``.hpp``), Java (``.java``)
- javascript source files (``.js``)
- pascal source files (``.pas``, ``.pp``, ``.inc``)
- python source files (``.py``)
- ruby source files (``.rb``)
- perl source files (``.pl``, ``.pm``, ``.t``)
- shell script source files (``.sh``)
- nix source files (``.nix``)
- plain text files (``.txt``)
Every other file-type will get ignored! Contact me if you need another
language to be added.
.. raw:: html
Query options
-------------
You can filter the issues to be displayed:
- ``-t EXPR`` filters by issue tag
- ``-p EXPR`` filters by issue filepath
- ``-d EXPR`` filters by description
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`` (i.e. to search for issues which have *not* the word
"urgent" in them, etc.) use the corresponding capitalised option flags
``-T``, ``-P``, ``-D``. Orphan (tagless) issues are sometimes a nuisance,
a handy way to list them is:
::
lentil . -T .
.. raw:: html
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.
.. raw:: html
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.
.. raw:: html
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.