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

# Artemis #
-----------

> [Artemis](http://www.mrzv.org/software/artemis/) is a lightweight distributed issue tracking extension for [Mercurial](http://www.selenic.com/mercurial/).

* [Setup](#markdown-header-setup)
* [Example](#markdown-header-example)
* [Commands](#markdown-header-commands)
* [Filters](#markdown-header-filters)
* [Format](#markdown-header-format)


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.

One can obtain Artemis by cloning its [repository](http://hg.mrzv.org/Artemis/):

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

or downloading the entire 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/artemis
```

Optionally, provide a section `[artemis]` in your `~/.hgrc` file or the repository local `.hg/hgrc` file, and specify an alternative path for the issues subdirectory (instead of the default `.issues`):

```
    [artemis]
    issues = _issues
```

Additionally, one can specify [filters](#markdown-header-filters) and output [formats](#markdown-header-format).

### Windows ###
---------------

The TortoiseHg for windows comes with a sandboxed Python, that means that thg will not be using the Python installed in the system.

If you get a `No module named mailbox!` error find the `mailbox.py` under `%PYTHON_PATH%\Lib` and add it to the `%HG_PATH%\lib\library.zip`. 


[↑ back to top](#markdown-header-artemis)


## Example ##
-------------

**Create an issue:**

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

**List the issues:**

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

**Show an issue:**

```
    $ hg ishow 907ab57e04502afd
    ======================================================================
    From: ...
    Date: ...
    Subject: New issue
    State: new

    Detailed description.

    ----------------------------------------------------------------------
```

**Add a comment to the issue:**

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

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

**And a comment to the comment:**

```
    $ hg iadd 907ab57e04502afd -i 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 907ab57e04502afd -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
```

**Search the issues:**

Search a property using regular expressions
```
    hg ifind -p state -r "fix(ed)?|resolve(d)?"
    907ab57e04502afd (  3) [resolved]: New issue
    baca6256d98fb593 (  1) [resolved]: Another issue
```

Search the message for a string
```
    hg ifind -mn "comment" 
    907ab57e04502afd (  3) [resolved]: New issue
    baca6256d98fb593 (  1) [resolved]: Another issue
    ba564b23fcff6358 (  1) [new]: New issue
```



[↑ back to top](#markdown-header-artemis)

## Commands ##
--------------

**hg iadd [OPTIONS] [ID]**

> Adds a new issue, or comment to an existing issue ID or its comment COMMENT


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





**hg ilist [OPTIONS]**

> 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



**hg ishow [OPTIONS] ID**

> 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



**hg ifind [OPTIONS] QUERY**

> 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)                        |
| -n  | --no-property     | Do not match the property. Use with       |
|     |                   | --message to search only the message. The |
|     |                   | --property will be ignored.               |
| -m  | --message         | Search the message. If no match is found  |
|     |                   | it will then search the property for a    |
|     |                   | match. Use a blank property to ignore the | 
|     |                   | property search.                          | 
| -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







[↑ back to top](#markdown-header-artemis)


## 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/.filterMyCustom` creates a filter `olddoc` which can be invoked with the `ilist` command:

```
    hg ilist -f olddoc
```


[↑ back to top](#markdown-header-artemis)



## Format ##
------------

One can specify the output format for the `ilist` command in the global hg configuration `~/.hgrc` or the repository local configuration `.hg/hgrc`.

```
    hg config --edit
```

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](http://en.wikipedia.org/wiki/ANSI_escape_code), so one could color the summary lines:

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


[↑ back to top](#markdown-header-artemis)



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

[http://www.mrzv.org/software/artemis/](http://www.mrzv.org/software/artemis/)