-------------------------------------------------------------------------------- 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 */ 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. As now lentil parses: - haskell source files (``.hs``, ``.lhs``) - C source files (``.c``, ``.h``), C++ (``.cpp``, ``.hpp``), Java (``.java``) - javascript source files (``.js``) - python source files (``.py``) - ruby source files (``.rb``) - pascal source files (``.pas``, ``.pp``, ``.inc``) - 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


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


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