|
1 Artemis |
|
2 ======= |
|
3 |
|
4 Artemis is a lightweight distributed issue tracking extension for Mercurial_. |
|
5 |
|
6 Individual issues are stored in directories in an ``.issues`` subdirectory. Each |
|
7 one is a Maildir_ and each one is assumed to have a single root message. |
|
8 Various properties of an issue are stored in the headers of that message. |
|
9 |
|
10 .. _Mercurial: http://www.selenic.com/mercurial/ |
|
11 .. _Maildir: http://en.wikipedia.org/wiki/Maildir |
|
12 |
|
13 Artemis' home is at http://hg.mrzv.org/Artemis. |
|
14 |
|
15 |
|
16 Setup |
|
17 ----- |
|
18 |
|
19 In the ``[extensions]`` section of your ``~/.hgrc`` add:: |
|
20 |
|
21 artemis = /path/to/artemis.py |
|
22 |
|
23 |
|
24 Example |
|
25 ------- |
|
26 |
|
27 Create an issue:: |
|
28 |
|
29 # hg iadd |
|
30 ... enter some text in an editor ... |
|
31 Added new issue 907ab57e04502afd |
|
32 |
|
33 # hg ilist |
|
34 907ab57e04502afd ( 0) [new]: New issue |
|
35 |
|
36 # hg ishow 907 |
|
37 ====================================================================== |
|
38 From: ... |
|
39 Date: ... |
|
40 Subject: New issue |
|
41 State: new |
|
42 |
|
43 Detailed description. |
|
44 |
|
45 ---------------------------------------------------------------------- |
|
46 |
|
47 Add a comment to the issue:: |
|
48 |
|
49 # hg iadd 907 |
|
50 ... enter the comment text |
|
51 ====================================================================== |
|
52 From: ... |
|
53 [snip] |
|
54 Detailed description. |
|
55 |
|
56 ---------------------------------------------------------------------- |
|
57 Comments: |
|
58 1: [dmitriy] Some comment |
|
59 ---------------------------------------------------------------------- |
|
60 |
|
61 And a comment to the comment:: |
|
62 |
|
63 # hg iadd 907 1 |
|
64 ... enter the comment text ... |
|
65 ====================================================================== |
|
66 From: ... |
|
67 [snip] |
|
68 Detailed description. |
|
69 |
|
70 ---------------------------------------------------------------------- |
|
71 Comments: |
|
72 1: [dmitriy] Some comment |
|
73 2: [dmitriy] Comment on a comment |
|
74 ---------------------------------------------------------------------- |
|
75 |
|
76 Close the issue:: |
|
77 |
|
78 # hg iadd 907 -p state=resolved -p resolution=fixed -n |
|
79 ====================================================================== |
|
80 From: ... |
|
81 [snip] |
|
82 Detailed description. |
|
83 |
|
84 ---------------------------------------------------------------------- |
|
85 Comments: |
|
86 1: [dmitriy] Some comment |
|
87 2: [dmitriy] Comment on a comment |
|
88 3: [dmitriy] changed properties (state=resolved, resolution=fixed) |
|
89 ---------------------------------------------------------------------- |
|
90 |
|
91 No more new issues, and one resolved issue:: |
|
92 |
|
93 # hg ilist |
|
94 # hg ilist -a |
|
95 907ab57e04502afd ( 3) [resolved=fixed]: New issue |
|
96 |
|
97 The fact that issues are Maildirs, allows one to look at them in, for example, |
|
98 ``mutt`` with predictable results:: |
|
99 |
|
100 mutt -Rf .issues/907ab57e04502afd |
|
101 |
|
102 Commands |
|
103 -------- |
|
104 |
|
105 `iadd` ``[ID] [COMMENT]`` |
|
106 Add an issue, or a comment to an existing issue or comment. The comment is |
|
107 recorded as a reply to the particular message. `iadd` is the only command |
|
108 that changes the state of the repository (by adding the new issue files to |
|
109 the list of tracked files or updating some of them), however, it does not |
|
110 perform an actual commit. |
|
111 |
|
112 `-p`, `--property` |
|
113 update a property of the issue ``ID``, e.g. ``-p state=resolved -p resolution=fixed`` |
|
114 |
|
115 `-a`, `--attach` |
|
116 attach a file to the message, e.g. ``-a filename1 -a filename2`` |
|
117 |
|
118 `-n`, `--no-property-comment` |
|
119 do not launch an editor to record a comment (useful if only changing |
|
120 properties) |
|
121 |
|
122 |
|
123 `ilist` |
|
124 List issues. |
|
125 |
|
126 `-a`, `--all` |
|
127 list all issues (not just the `new` ones) |
|
128 |
|
129 `-p`, `--property` |
|
130 list issues with specific property values, e.g. |
|
131 ``-p state=resolved -p category=documentation``; |
|
132 if no property value is provided (e.g. ``-p category``), lists all |
|
133 possible values for that property (among the issues that satisfy the |
|
134 rest of the criteria) |
|
135 |
|
136 `-d`, `--date` |
|
137 restrict to issues matching the given date, e.g. ``-d ">1/1/2008"`` |
|
138 |
|
139 `-f`, `--filter` |
|
140 restrict to a predefined filter, see Filters_ below |
|
141 |
|
142 |
|
143 `ishow` ``[ID] [COMMENT]`` |
|
144 Show an issue or a comment. |
|
145 |
|
146 `-a`, `--all` |
|
147 list all comments to an issue (i.e. not just a single message, and a |
|
148 thread of subjects of its replies) |
|
149 |
|
150 `-s`, `--skip` |
|
151 in the output skip lines of the messages starting with the given |
|
152 substring, defaults to ``>`` |
|
153 |
|
154 `-x`, `--extract` |
|
155 extract attachments (given their numbers) |
|
156 |
|
157 |
|
158 Filters |
|
159 ------- |
|
160 |
|
161 Artemis scans all files of the form ``.issues/.filter*``, and processes them as |
|
162 config files. Section names become filter names, and the individual settings |
|
163 become properties. For example the following:: |
|
164 |
|
165 [olddoc] |
|
166 category=documentation |
|
167 state=resolved |
|
168 |
|
169 placed in a file ``.issues/.filter`` creates a filter `olddoc` which can be |
|
170 invoked with the `ilist` command:: |
|
171 |
|
172 hg ilist -f olddoc |