24 |
24 |
25 Setup |
25 Setup |
26 ----- |
26 ----- |
27 |
27 |
28 In the ``[extensions]`` section of your ``~/.hgrc`` add:: |
28 In the ``[extensions]`` section of your ``~/.hgrc`` add:: |
29 |
29 |
30 artemis = /path/to/artemis.py |
30 artemis = /path/to/Artemis/artemis |
31 |
31 |
32 Optionally, provide a section ``[artemis]``, and specify an alternative path for |
32 Optionally, provide a section ``[artemis]``, and specify an alternative path for |
33 the issues subdirectory (instead of the default ``.issues``):: |
33 the issues subdirectory (instead of the default ``.issues``):: |
34 |
34 |
35 [artemis] |
35 [artemis] |
36 issues = _issues |
36 issues = _issues |
37 |
37 |
|
38 Additionally, one can specify filters_ and output formats_. |
|
39 |
|
40 .. _formats: Format_ |
38 |
41 |
39 Example |
42 Example |
40 ------- |
43 ------- |
41 |
44 |
42 Create an issue:: |
45 Create an issue:: |
43 |
46 |
44 # hg iadd |
47 # hg iadd |
45 ... enter some text in an editor ... |
48 ... enter some text in an editor ... |
46 Added new issue 907ab57e04502afd |
49 Added new issue 907ab57e04502afd |
47 |
50 |
48 # hg ilist |
51 # hg ilist |
49 907ab57e04502afd ( 0) [new]: New issue |
52 907ab57e04502afd ( 0) [new]: New issue |
50 |
53 |
51 # hg ishow 907 |
54 # hg ishow 907 |
54 Date: ... |
57 Date: ... |
55 Subject: New issue |
58 Subject: New issue |
56 State: new |
59 State: new |
57 |
60 |
58 Detailed description. |
61 Detailed description. |
59 |
62 |
60 ---------------------------------------------------------------------- |
63 ---------------------------------------------------------------------- |
61 |
64 |
62 Add a comment to the issue:: |
65 Add a comment to the issue:: |
63 |
66 |
64 # hg iadd 907 |
67 # hg iadd 907 |
65 ... enter the comment text |
68 ... enter the comment text |
66 ====================================================================== |
69 ====================================================================== |
67 From: ... |
70 From: ... |
68 [snip] |
71 [snip] |
69 Detailed description. |
72 Detailed description. |
70 |
73 |
71 ---------------------------------------------------------------------- |
74 ---------------------------------------------------------------------- |
72 Comments: |
75 Comments: |
73 1: [dmitriy] Some comment |
76 1: [dmitriy] Some comment |
74 ---------------------------------------------------------------------- |
77 ---------------------------------------------------------------------- |
75 |
78 |
79 ... enter the comment text ... |
82 ... enter the comment text ... |
80 ====================================================================== |
83 ====================================================================== |
81 From: ... |
84 From: ... |
82 [snip] |
85 [snip] |
83 Detailed description. |
86 Detailed description. |
84 |
87 |
85 ---------------------------------------------------------------------- |
88 ---------------------------------------------------------------------- |
86 Comments: |
89 Comments: |
87 1: [dmitriy] Some comment |
90 1: [dmitriy] Some comment |
88 2: [dmitriy] Comment on a comment |
91 2: [dmitriy] Comment on a comment |
89 ---------------------------------------------------------------------- |
92 ---------------------------------------------------------------------- |
93 # hg iadd 907 -p state=resolved -p resolution=fixed -n |
96 # hg iadd 907 -p state=resolved -p resolution=fixed -n |
94 ====================================================================== |
97 ====================================================================== |
95 From: ... |
98 From: ... |
96 [snip] |
99 [snip] |
97 Detailed description. |
100 Detailed description. |
98 |
101 |
99 ---------------------------------------------------------------------- |
102 ---------------------------------------------------------------------- |
100 Comments: |
103 Comments: |
101 1: [dmitriy] Some comment |
104 1: [dmitriy] Some comment |
102 2: [dmitriy] Comment on a comment |
105 2: [dmitriy] Comment on a comment |
103 3: [dmitriy] changed properties (state=resolved, resolution=fixed) |
106 3: [dmitriy] changed properties (state=resolved, resolution=fixed) |
120 `iadd` ``[ID] [COMMENT]`` |
123 `iadd` ``[ID] [COMMENT]`` |
121 Add an issue, or a comment to an existing issue or comment. The comment is |
124 Add an issue, or a comment to an existing issue or comment. The comment is |
122 recorded as a reply to the particular message. `iadd` is the only command |
125 recorded as a reply to the particular message. `iadd` is the only command |
123 that changes the state of the repository (by adding the new issue files to |
126 that changes the state of the repository (by adding the new issue files to |
124 the list of tracked files or updating some of them), however, it does not |
127 the list of tracked files or updating some of them), however, it does not |
125 perform an actual commit. |
128 perform an actual commit unless explicitly asked to do so. |
126 |
129 |
127 `-p`, `--property` |
130 `-p`, `--property` |
128 update a property of the issue ``ID``, e.g. ``-p state=resolved -p resolution=fixed`` |
131 update a property of the issue ``ID``, e.g. ``-p state=resolved -p resolution=fixed`` |
129 |
132 |
130 `-a`, `--attach` |
133 `-a`, `--attach` |
135 properties) |
138 properties) |
136 |
139 |
137 `-m`, `--message` |
140 `-m`, `--message` |
138 use ``text`` as an issue subject |
141 use ``text`` as an issue subject |
139 |
142 |
|
143 `-c`, `--commit` |
|
144 commit the issue after the addition (all changes to the issue will be |
|
145 committed) |
|
146 |
140 |
147 |
141 `ilist` |
148 `ilist` |
142 List issues. |
149 List issues. |
143 |
150 |
144 `-a`, `--all` |
151 `-a`, `--all` |
145 list all issues (not just the `new` ones) |
152 list all issues (not just the `new` ones) |
146 |
153 |
147 `-p`, `--property` |
154 `-p`, `--property` |
148 list issues with specific property values, e.g. |
155 list issues with specific property values, e.g. |
149 ``-p state=resolved -p category=documentation``; |
156 ``-p state=resolved -p category=documentation``; |
150 if no property value is provided (e.g. ``-p category``), lists all |
157 if no property value is provided (e.g. ``-p category``), lists all |
151 possible values for that property (among the issues that satisfy the |
158 possible values for that property (among the issues that satisfy the |
152 rest of the criteria) |
159 rest of the criteria) |
153 |
160 |
|
161 `-o`, `--order` |
|
162 order of the issues; choices: "new" (date submitted), "latest" (date of |
|
163 the most recent message) |
|
164 |
154 `-d`, `--date` |
165 `-d`, `--date` |
155 restrict to issues matching the given date, e.g. ``-d ">1/1/2008"`` |
166 restrict to issues matching the given date, e.g. ``-d ">1/1/2008"`` |
156 |
167 |
157 `-f`, `--filter` |
168 `-f`, `--filter` |
158 restrict to a predefined filter, see Filters_ below |
169 restrict to a predefined filter, see Filters_ below |
159 |
170 |
160 |
171 |
161 `ishow` ``[ID] [COMMENT]`` |
172 `ishow` ``[ID] [COMMENT]`` |
162 Show an issue or a comment. |
173 Show an issue or a comment. |
163 |
174 |
164 `-a`, `--all` |
175 `-a`, `--all` |
189 |
200 |
190 placed in a file ``.issues/.filter`` creates a filter `olddoc` which can be |
201 placed in a file ``.issues/.filter`` creates a filter `olddoc` which can be |
191 invoked with the `ilist` command:: |
202 invoked with the `ilist` command:: |
192 |
203 |
193 hg ilist -f olddoc |
204 hg ilist -f olddoc |
|
205 |
|
206 |
|
207 Format |
|
208 ------ |
|
209 |
|
210 One can specify the output format for the `ilist` command. The default looks |
|
211 like:: |
|
212 |
|
213 [artemis] |
|
214 format = %(id)s (%(len)3d) [%(state)s]: %(subject)s |
|
215 |
|
216 Artemis passes a dictionary with the issue properties to the format string. |
|
217 (Plus ``id`` contains the issue id, and ``len`` contains the number of replies.) |
|
218 |
|
219 It's possible to specify different output formats depending on the properties of |
|
220 the issue. The conditions are encoded in the config variable names as follows:: |
|
221 |
|
222 format:state*resolved&resolution*fixed = %(id)s (%(len)3d) [fixed]: %(Subject)s |
|
223 format:state*resolved = %(id)s (%(len)3d) [%(state)s=%(resolution)s]: %(Subject)s |
|
224 |
|
225 The first rule matches issues with the ``state`` property set to ``resolved`` |
|
226 and ``resolution`` set to ``fixed``; it abridges the output. The secod rule |
|
227 matches all the ``resolved`` issues (not matched by the first rule); it annotates |
|
228 the issue's state with its ``resolution``. |
|
229 |
|
230 Finally, the dictionary passed to the format string contains a subset of |
|
231 `ANSI codes`_, so one could color the summary lines:: |
|
232 |
|
233 format:state*new = %(red)s%(bold)s%(id)s (%(len)3d) [%(state)s]: %(Subject)s%(reset)s |
|
234 |
|
235 .. _`ANSI codes`: http://en.wikipedia.org/wiki/ANSI_escape_code |