page.rst

--------------------------------------------------------------------------------
title: lentil manual
author: Francesco Ariis
summary: lentil issue tracker user manual
tags: lentil,issue,bug,issue tracker,bug tracker,manual
published: 2015-06-15 00:00:00
revised: 2015-06-15 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.

.. raw:: html

   <p><br/></p>

Installation
------------

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

   <p><br/></p>

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

   <p><br/></p>


Input format
------------

lentil parses issues that start with ``TODO:`` and ``FIXE:``, followed by
a space, followed by freeform text (text can be multiline).

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.

As now lentil parses haskell source files (``.hs``, ``.lhs``), C source
files (``.c``, ``.h``) and plain text files (``.txt``) and ignores
everything else.

.. raw:: html

   <p><br/></p>


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

   <p><br/></p>


Output options
--------------

You can change the ``-f TYPE`` option to change the output format. You
can choose the default format ``pretty``, export issues to CSV format
using ``-f csv`` or pick ``tagpop``. Tagpop lists tags by their popularity
(reverse order) and is useful to see a summary of the 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]


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

.. raw:: html

   <p><br/></p>


Other options
-------------

``-v`` outputs the program version, ``--help`` displays cheatsheet option
help.