README
author frostbane <frostbane@programmer.net>
Wed, 25 May 2016 09:16:17 +0900
branchfeature/find
changeset 84 f423f67d4560
parent 77 af9913ddbb3d
child 88 14472fccbe89
permissions -rw-r--r--
add options to README

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.


options:

|     |                       | description                           |
|-----|-----------------------|---------------------------------------|
| -a  | --attach VALUE [+]    | attach file(s)                        |
|     |                       | (e.g., -a filename1 -a filename2)     |
| -p  | --property VALUE [+]  | update properties                     |
|     |                       | (e.g. -p state=fixed,                 |
|     |                       | -p state=resolved                     |
|     |                       | -p resolution=fixed)                  |
| -n  | --no-property-comment | do not add a comment about changed    |
|     |                       | properties                            |
| -m  | --message VALUE       | use <text> as an issue subject        |
| -i  | --index VALUE         | 0 based index of the message to show  |
|     |                       | (default: 0)                          |
| -c  | --commit              | perform a commit after the addition   |

[+] marked option can be specified multiple times


`ilist`
> List issues associated with the project

options:

|     |                      | description                            |
|-----|----------------------|----------------------------------------|
| -a  | --all                | list all issues                        |
|     |                      | (by default only those with state new) |
| -p  | --property VALUE [+] | list issues with specific field values |
|     |                      | (e.g., -p state=fixed,                 |
|     |                      | -p state=resolved -p category=doc);    |
|     |                      | lists all possible values of a         |
|     |                      | property if no = sign is provided.     |
|     |                      | (e.g. -p category)                     |
|     | --all-properties     | list all available properties          |
| -o  | --order VALUE        | order of the issues; choices: "new"    |
|     |                      | (date submitted), "latest"             |
|     |                      | (date of the last message)             |
|     |                      | (default: new)                         |
| -d  | --date VALUE         | restrict to issues matching the date   |
|     |                      | (e.g., -d ">12/28/2007)"               |
| -f  | --filter VALUE       | restrict to pre-defined filter         |
|     |                      | (in .issues/.filter*)                  |

[+] marked option can be specified multiple times


`ishow` ``[ID] [COMMENT]``
> Shows issue ID, or possibly its comment COMMENT

options:

|     |                     | description                             |
|-----|---------------------|-----------------------------------------|
| -a  | --all               | list all comments                       |
| -s  | --skip VALUE        | skip lines starting with a substring    |
|     |                     | (default: >)                            |
| -x  | --extract VALUE [+] | extract attachments                     |
|     |                     | (provide attachment number as argument) |
| -i  | --index VALUE       | 0 based index of the message to show    |
|     |                     | (default: 0)                            |
| -o  | --output VALUE      | extract output directory                |
|     | --mutt              | use mutt to show issue                  |

[+] marked option can be specified multiple times


`ifind`

> Shows a list of issues matching the specified QUERY

options:

|     |                   | description                               |
|-----|-------------------|-------------------------------------------|
| -p  | --property VALUE  | issue property to match                   |
|     |                   | [state, from, subject, date, priority,    |
|     |                   | [resolution, ticket, etc..]               |
|     |                   | (default: subject)                        |
| -c  | --case-sensitive  | case sensitive search                     |
| -r  | --regex           | use regular expressions                   |
|     |                   | (exact option will be ignored)            |
| -e  | --exact           | use exact comparison                      |
|     |                   | like comparison is used if uspecified     |

[+] marked option can be specified multiple times


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/