+
−Artemis
+
−=======
+
−
+
−Artemis is a lightweight distributed issue tracking extension for Mercurial_.
+
−
+
−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/
+
−.. _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
+
−
+
−
+
−Setup
+
−-----
+
−
+
−In the ``[extensions]`` section of your ``~/.hgrc`` add::
+
−
+
−    artemis = /path/to/artemis.py
+
−
+
−Optionally, provide a section ``[artemis]``, and specify an alternative path for
+
−the issues subdirectory (instead of the default ``.issues``)::
+
−
+
−    [artemis]
+
−    issues = _issues
+
−
+
−
+
−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