Artemis
=======

Artemis is a lightweight distributed issue tracking extension for
Mercurial_.  Alpha-quality `git support`_ is recently available and
is described in its own section below.

Individual issues are stored in directories in an ``.issues`` subdirectory
(overridable in a config file).  Each one is a Maildir_ and each one is assumed
to have a single root message.  Various properties of an issue are stored in the
headers of that message.

.. _Mercurial:      http://www.selenic.com/mercurial/
.. _`git support`:  GitSupport_
.. _Maildir:        http://en.wikipedia.org/wiki/Maildir

One can obtain Artemis by cloning its repository:

.. parsed-literal::

    hg clone http://hg.mrzv.org/Artemis/

or downloading the entire `repository as a tarball`_.

.. _`repository as a tarball`:  http://hg.mrzv.org/Artemis/archive/tip.tar.gz

A git mirror is `hosted on GitHub`_.

.. _`hosted on GitHub`: https://github.com/mrzv/artemis


Setup
-----

In the ``[extensions]`` section of your ``~/.hgrc`` add::

    artemis = /path/to/Artemis/artemis

Optionally, provide a section ``[artemis]``, and specify an alternative path for
the issues subdirectory (instead of the default ``.issues``)::

    [artemis]
    issues = _issues

Additionally, one can specify filters_ and output formats_.

.. _formats:     Format_

Example
-------

Create an issue::

    # hg iadd
    ... enter some text in an editor ...
    Added new issue 907ab57e04502afd

    # hg ilist
    907ab57e04502afd (  0) [new]: New issue

    # hg ishow 907
    ======================================================================
    From: ...
    Date: ...
    Subject: New issue
    State: new

    Detailed description.

    ----------------------------------------------------------------------

Add a comment to the issue::

    # hg iadd 907
    ... enter the comment text
    ======================================================================
    From: ...
    [snip]
    Detailed description.

    ----------------------------------------------------------------------
    Comments:
      1: [dmitriy] Some comment
    ----------------------------------------------------------------------

And a comment to the comment::

    # hg iadd 907 1
    ... enter the comment text ...
    ======================================================================
    From: ...
    [snip]
    Detailed description.

    ----------------------------------------------------------------------
    Comments:
      1: [dmitriy] Some comment
        2: [dmitriy] Comment on a comment
    ----------------------------------------------------------------------

Close the issue::

    # hg iadd 907 -p state=resolved -p resolution=fixed -n
    ======================================================================
    From: ...
    [snip]
    Detailed description.

    ----------------------------------------------------------------------
    Comments:
      1: [dmitriy] Some comment
        2: [dmitriy] Comment on a comment
      3: [dmitriy] changed properties (state=resolved, resolution=fixed)
    ----------------------------------------------------------------------

No more new issues, and one resolved issue::

    # hg ilist
    # hg ilist -a
    907ab57e04502afd (  3) [resolved=fixed]: New issue

The fact that issues are Maildirs, allows one to look at them in, for example,
``mutt`` with predictable results::

    mutt -Rf .issues/907ab57e04502afd

Commands
--------

`iadd` ``[ID] [COMMENT]``
    Add an issue, or a comment to an existing issue or comment. The comment is
    recorded as a reply to the particular message. `iadd` is the only command
    that changes the state of the repository (by adding the new issue files to
    the list of tracked files or updating some of them), however, it does not
    perform an actual commit unless explicitly asked to do so.

    `-p`, `--property`
        update a property of the issue ``ID``, e.g. ``-p state=resolved -p resolution=fixed``

    `-a`, `--attach`
        attach a file to the message, e.g. ``-a filename1 -a filename2``

    `-n`, `--no-property-comment`
        do not launch an editor to record a comment (useful if only changing
        properties)

    `-m`, `--message`
        use ``text`` as an issue subject

    `-c`, `--commit`
        commit the issue after the addition (all changes to the issue will be
        committed)


`ilist`
    List issues.

    `-a`, `--all`
        list all issues (not just the `new` ones)

    `-p`, `--property`
        list issues with specific property values, e.g.
        ``-p state=resolved -p category=documentation``;
        if no property value is provided (e.g. ``-p category``), lists all
        possible values for that property (among the issues that satisfy the
        rest of the criteria)

    `-o`, `--order`
        order of the issues; choices: "new" (date submitted), "latest" (date of
        the most recent message)

    `-d`, `--date`
        restrict to issues matching the given date, e.g. ``-d ">1/1/2008"``

    `-f`, `--filter`
        restrict to a predefined filter, see Filters_ below


`ishow` ``[ID] [COMMENT]``
    Show an issue or a comment.

    `-a`, `--all`
        list all comments to an issue (i.e. not just a single message, and a
        thread of subjects of its replies)

    `-s`, `--skip`
        in the output skip lines of the messages starting with the given
        substring, defaults to ``>``

    `-x`, `--extract`
        extract attachments (given their numbers)

    `--mutt`
        use ``mutt`` to show issue


Filters
-------

Artemis scans all files of the form ``.issues/.filter*``, and processes them as
config files. Section names become filter names, and the individual settings
become properties. For example the following::

    [olddoc]
    category=documentation
    state=resolved

placed in a file ``.issues/.filter`` creates a filter `olddoc` which can be
invoked with the `ilist` command::

    hg ilist -f olddoc


Format
------

One can specify the output format for the `ilist` command. The default looks
like::

    [artemis]
    format = %(id)s (%(len)3d) [%(state)s]: %(subject)s

Artemis passes a dictionary with the issue properties to the format string.
(Plus ``id`` contains the issue id, and ``len`` contains the number of replies.)

It's possible to specify different output formats depending on the properties of
the issue. The conditions are encoded in the config variable names as follows::

    format:state*resolved&resolution*fixed  = %(id)s (%(len)3d) [fixed]: %(Subject)s
    format:state*resolved                   = %(id)s (%(len)3d) [%(state)s=%(resolution)s]: %(Subject)s

The first rule matches issues with the ``state`` property set to ``resolved``
and ``resolution`` set to ``fixed``; it abridges the output. The secod rule
matches all the ``resolved`` issues (not matched by the first rule); it annotates
the issue's state with its ``resolution``.

Finally, the dictionary passed to the format string contains a subset of
`ANSI codes`_, so one could color the summary lines::

    format:state*new = %(red)s%(bold)s%(id)s (%(len)3d) [%(state)s]: %(Subject)s%(reset)s

.. _`ANSI codes`:       http://en.wikipedia.org/wiki/ANSI_escape_code


.. _GitSupport:

Git
---

Artemis can now be used with git_.

This requires the `git-artemis` script to be in the executable path,
and the `artemis` module to be findable by python.  This can be done
by installing using the supplied `setup.py`.

Artemis commands are accessed from git like this::

    git artemis list

similarly for `show` or `add`.  Arguments and flags are exactly the
same as for the mercurial version.

It is not yet possible to specify formats via the `git config` command.

.. _git:      https://git-scm.com/