|
1
|
# JSON API: /tag |
|
2
|
([⬑JSON API Index](index.md)) |
|
3
|
|
|
4
|
Jump to: |
|
5
|
|
|
6
|
* [Add](#add) |
|
7
|
* [Cancel](#cancel) |
|
8
|
* [Find](#find) |
|
9
|
* [List](#list) |
|
10
|
|
|
11
|
--- |
|
12
|
|
|
13
|
<a id="add"></a> |
|
14
|
# Add Tag |
|
15
|
|
|
16
|
**Status:** implemented 20111006 |
|
17
|
|
|
18
|
**Required permissions:** "i" |
|
19
|
|
|
20
|
**Request:** `/json/tag/add[/name[/checkin[/value]]]` |
|
21
|
|
|
22
|
**Request options:** |
|
23
|
|
|
24
|
- `name=string` The tag name. |
|
25
|
- `checkin=string` The checkin to tag. May be a symbolic branch name. |
|
26
|
- raw=bool (=false) If true, then the name is set as it is provided by |
|
27
|
the client, else it gets "sym-" prefixed to it. Do not use this |
|
28
|
unless you really know what you're doing. |
|
29
|
- `value=string` (=null) An optional value. While tags *may* have values |
|
30
|
in fossil, it is unusual for them to have a value. (This probably |
|
31
|
has some interesting uses in custom UIs.) |
|
32
|
- `propagate=bool` (=false) Sets the tag to propagate to all descendants |
|
33
|
of the given checkin. |
|
34
|
|
|
35
|
In CLI modes, the name, checkin, and value parameters may optionally be |
|
36
|
supplied as positional parameters (in that order, after the command |
|
37
|
name). In HTTP mode they may optionally be the 4th-6th path elements or |
|
38
|
specified via GET/`POST.envelope` parameters. |
|
39
|
|
|
40
|
**Response payload example:** |
|
41
|
|
|
42
|
```json |
|
43
|
{ |
|
44
|
"name":"my-tag", |
|
45
|
"value":"abc", |
|
46
|
"propagate":true, |
|
47
|
"raw":false, |
|
48
|
"appliedTo":"626ab2f3743543122cc11bc082a0603d2b5b2b1b" |
|
49
|
} |
|
50
|
``` |
|
51
|
|
|
52
|
The `appliedTo` property is the hash of the check-in to which the tag was |
|
53
|
applied. This is the "resolved" version of the check-in name provided by |
|
54
|
the client. |
|
55
|
|
|
56
|
<a id="cancel"></a> |
|
57
|
# Cancel Tag |
|
58
|
|
|
59
|
**Status:** implemented 20111006 |
|
60
|
|
|
61
|
**Required permissions:** "i" |
|
62
|
|
|
63
|
**Request:** `/json/tag/cancel[/name[/checkin]]` |
|
64
|
|
|
65
|
**Request options:** |
|
66
|
|
|
67
|
- `name=string` The tag name. May optionally be provided as the 4th path |
|
68
|
element. |
|
69
|
- `checkin=string` The checkin to untag. May be a symbolic branch name. |
|
70
|
May optionally be provided as the 5th path element. |
|
71
|
|
|
72
|
In CLI modes, the name and checkin parameters may optionally be supplied |
|
73
|
as positional parameters (in that order, after the command name) or |
|
74
|
using the `-name NAME` and `-checkin NAME` options. In HTTP mode they may |
|
75
|
optionally be the 4th and 5th path elements. |
|
76
|
|
|
77
|
**Response payload:** none (resultCode indicates failure) |
|
78
|
|
|
79
|
|
|
80
|
<a id="find"></a> |
|
81
|
# Find Tag |
|
82
|
|
|
83
|
Fetches information about artifacts having a particular tag. |
|
84
|
|
|
85
|
Achtung: the output of this response is based on the HTML-mode |
|
86
|
implementation, but it's not yet certain that it's exactly what we want |
|
87
|
for JSON mode. The request options and response format may change. |
|
88
|
|
|
89
|
**Status:** implemented 20111006 |
|
90
|
|
|
91
|
**Required permissions:** "o" |
|
92
|
|
|
93
|
**Request:** `/json/tag/find[/tagName]` |
|
94
|
|
|
95
|
The response format differs somewhat depending on the options: |
|
96
|
|
|
97
|
- `name=string` The tag name to search for. Can optionally be the 3rd |
|
98
|
path element. |
|
99
|
- `limit=int` (defalt=0) Limits the number of results (0=no limit). |
|
100
|
Since they are ordered from oldest to newest, the newest N results |
|
101
|
will be returned. |
|
102
|
- `type=string` (default=`*`) Searches only for the given type of |
|
103
|
artifact (using fossil's conventional type naming: ci, e, t, w.) |
|
104
|
- `raw=bool` (=false) If enabled, the response is an array of hashes |
|
105
|
of the requested artifact type; otherwise, |
|
106
|
it is an array of higher-level objects. If this is |
|
107
|
true, the "name" property is interpreted as-is. If it is false, the |
|
108
|
name is automatically prepended with "sym-" (meaning a branch). |
|
109
|
(FIXME: the current semantics are confusing and hard to remember. |
|
110
|
Re-do them.) |
|
111
|
|
|
112
|
**Response payload example, in RAW mode: (expect this format to change |
|
113
|
at some point!)** |
|
114
|
|
|
115
|
```json |
|
116
|
{ |
|
117
|
"name":"sym-trunk" |
|
118
|
"raw":true, |
|
119
|
"type":"*", |
|
120
|
"limit":2, |
|
121
|
"artifacts":[ |
|
122
|
"a28c83647dfa805f05f3204a7e146eb1f0d90505", |
|
123
|
"dbda8d6ce9ddf01a16f6c81db2883f546298efb7" |
|
124
|
] |
|
125
|
} |
|
126
|
``` |
|
127
|
|
|
128
|
Very likely todo: return more information with that (at least the |
|
129
|
artifact type and timestamp). Once the `/json/artifact` family of bits is |
|
130
|
finished we could use that to return artifact-type-dependent values |
|
131
|
here. |
|
132
|
|
|
133
|
**Response payload example, in non-raw mode:** |
|
134
|
|
|
135
|
``` |
|
136
|
{ |
|
137
|
"name":"trunk", |
|
138
|
"raw":false, |
|
139
|
"type":"*", |
|
140
|
"limit":1, |
|
141
|
"artifacts":[{ |
|
142
|
"uuid":"4b0f813b8c59ac8f7fbbe33c0a369acc65407841", |
|
143
|
"timestamp":1317833899, |
|
144
|
"comment":"fixed [fc825dcf52]", |
|
145
|
"user":"ron", |
|
146
|
"eventType":"checkin" |
|
147
|
}] |
|
148
|
} |
|
149
|
``` |
|
150
|
|
|
151
|
<a id="list"></a> |
|
152
|
# List Tags |
|
153
|
|
|
154
|
**Status:** implemented 20111006 |
|
155
|
|
|
156
|
**Required permissions:** "o" |
|
157
|
|
|
158
|
**Request:** `/json/tag/list[/checkinName]` |
|
159
|
|
|
160
|
Potential fixme: we probably have too many different response formats |
|
161
|
here. We should probably break this into multiple subcommands. |
|
162
|
|
|
163
|
The response format differs somewhat depending on the options: |
|
164
|
|
|
165
|
- `checkin=string` Lists the tags only for the given CHECKIN (can be a |
|
166
|
branch name). If set, includeTickets is ignored (meaningless in this |
|
167
|
combination). This option can be set as either a GET/`POST.payload` |
|
168
|
option, as the last element of the request path, e.g. |
|
169
|
`/json/tag/list/MYBRANCH` *or* with `POST.payload` set to a string |
|
170
|
value. |
|
171
|
- `raw=bool` (default=false) uses "raw" tag names |
|
172
|
- `includeTickets=bool` (default=false) Determines whether `tkt-` tags |
|
173
|
are included. There is one of these for each ticket, so there can be |
|
174
|
many of them (over 900 in the main fossil repo as of this writing). |
|
175
|
|
|
176
|
**Response format when raw=false and no checkin is specified:** |
|
177
|
|
|
178
|
```json |
|
179
|
{ |
|
180
|
"raw":false, |
|
181
|
"includeTickets":false, |
|
182
|
"tags":[ |
|
183
|
"bgcolor", |
|
184
|
"branch", |
|
185
|
"closed", |
|
186
|
…all tag names... |
|
187
|
] |
|
188
|
} |
|
189
|
``` |
|
190
|
|
|
191
|
Enabling the `raw` option will leave the internal `sym-` prefix on tags |
|
192
|
which have them but will not change the structure. If `includeTickets` is |
|
193
|
true then `tkt-` entries (possibly very many!) will be included in the |
|
194
|
output, else they are elided. |
|
195
|
|
|
196
|
**General notes:** |
|
197
|
|
|
198
|
The `tags` property will be null if there are no tags, every non-empty |
|
199
|
repo has at least one tag (for the trunk branch). |
|
200
|
|
|
201
|
**Response format when raw=false and checkin is specified:** |
|
202
|
|
|
203
|
```json |
|
204
|
{ |
|
205
|
"raw":false, |
|
206
|
"tags":{ |
|
207
|
"json":null, |
|
208
|
"json-multitag-test":null |
|
209
|
} |
|
210
|
} |
|
211
|
``` |
|
212
|
|
|
213
|
The `null`s there are the tag values (most tags don't have values). |
|
214
|
|
|
215
|
If `raw=true` then the tags property changes slightly: |
|
216
|
|
|
217
|
```json |
|
218
|
{ |
|
219
|
"raw":true, |
|
220
|
"tags":{ |
|
221
|
"branch":"json", |
|
222
|
"sym-json":null, |
|
223
|
"sym-json-multitag-test":null |
|
224
|
} |
|
225
|
} |
|
226
|
``` |
|
227
|
|
|
228
|
TODO?: change the tag values to objects in the form |
|
229
|
`{value:..., tipUuid:string, propagating:bool}`. |
|
230
|
|