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.

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

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.