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/