|
1
|
# JSON API: /artifact |
|
2
|
([⬑JSON API Index](index.md)) |
|
3
|
|
|
4
|
Jump to: |
|
5
|
|
|
6
|
* [Checkin Artifacts (Commits)](#checkin) |
|
7
|
* [File Artifacts](#file) |
|
8
|
* [Wiki Artifacts](#wiki) |
|
9
|
|
|
10
|
--- |
|
11
|
|
|
12
|
<a id="checkin"></a> |
|
13
|
# Checkin Artifacts (Commits) |
|
14
|
|
|
15
|
Returns information about checkin artifacts (commits). |
|
16
|
|
|
17
|
**Status:** implemented 201110xx |
|
18
|
|
|
19
|
**Request:** `/json/artifact/COMMIT_HASH` |
|
20
|
|
|
21
|
**Required permissions:** "o" (was "h" prior to 20120408) |
|
22
|
|
|
23
|
**Response payload example: (CHANGED SIGNIFICANTLY ON 20120713)** |
|
24
|
|
|
25
|
```json |
|
26
|
{ |
|
27
|
"type":"checkin", |
|
28
|
"name":"18dd383e5e7684e", // as given on CLI |
|
29
|
"uuid":"18dd383e5e7684ecee327d3de7d3ff846069d1b2", |
|
30
|
"isLeaf":false, |
|
31
|
"user":"drh", |
|
32
|
"comment":"Merge wideAnnotateUser and jsonWarnings into trunk.", |
|
33
|
"timestamp":1330090810, |
|
34
|
"parents":[ |
|
35
|
// 1st entry is primary parent hash: |
|
36
|
"3a44f95f40a193739aaafc2409f155df43e74a6f", |
|
37
|
// Remaining entries are merged-in branch hashes: |
|
38
|
"86f6e675eb3f8761d70d8b82b052ce2b297fffd2",\ |
|
39
|
"dbf4ecf414881c9aad6f4f125dab9762589ef3d7"\ |
|
40
|
], |
|
41
|
"tags":["trunk"], |
|
42
|
"files":[{ |
|
43
|
"name":"src/diff.c", |
|
44
|
// BLOB hashes, NOT commit hashes: |
|
45
|
"uuid":"78c74c3b37e266f8f7e570d5cf476854b7af9d76", |
|
46
|
"parent":"b1fa7e636cf4e7b6ed20bba2d2680397f80c096a", |
|
47
|
"state":"modified", |
|
48
|
"downloadPath":"/raw/src/diff.c?name=78c74c3b37e266f8f7e570d5cf476854b7af9d76" |
|
49
|
}, |
|
50
|
...] |
|
51
|
} |
|
52
|
``` |
|
53
|
|
|
54
|
The "parents" property lists the parent hashes of the checkin. The |
|
55
|
"parent" property of file entries refers to the parent hash of that |
|
56
|
file. In the case of a merge there may be essentially an arbitrary |
|
57
|
number. The first entry in the list is the "primary" parent. The primary |
|
58
|
parent is the parent which was not pulled in via a merge operation. The |
|
59
|
ordering of remaining entries is unspecified and may even change between |
|
60
|
calls. For example: if, from branch C, we merge in A and B and then |
|
61
|
commit, then in the artifact response for that commit the hash of branch |
|
62
|
C will be in the first (primary) position, with the hashes for branches A |
|
63
|
and B in the following entries (in an unspecified, and possibly |
|
64
|
unstable, order). |
|
65
|
|
|
66
|
Note that the "uuid" and "parent" properties of the "files" entries |
|
67
|
refer to raw blob hashes, not commit (a.k.a. check-in) hashes. See also |
|
68
|
[the UUID vs. Hash discussion][uvh]. |
|
69
|
|
|
70
|
<a id="file"></a> |
|
71
|
# File Artifacts |
|
72
|
|
|
73
|
Fetches information about file artifacts. |
|
74
|
|
|
75
|
**FIXME:** the content type guessing is currently very primitive, and |
|
76
|
may (but I haven't seen this) mis-diagnose some non-binary files as |
|
77
|
binary. Fossil doesn't yet have a mechanism for mime-type mappings. |
|
78
|
|
|
79
|
**Status:** implemented 20111020 |
|
80
|
|
|
81
|
**Required permissions:** "o" |
|
82
|
|
|
83
|
**Request:** `/json/artifact/FILE_HASH` |
|
84
|
|
|
85
|
**Request options:** |
|
86
|
|
|
87
|
- `format=(raw|html|none)` (default=none). If set, the contents of the |
|
88
|
artifact are included if they are text, else they are not (JSON does |
|
89
|
not do binary). The "html" flag runs it through the wiki parser. The |
|
90
|
results of doing so are unspecified for non-embedded-doc files. The |
|
91
|
"raw" format means to return the content as-is. "none" is the same |
|
92
|
as not specifying this flag, and elides the content from the |
|
93
|
response. |
|
94
|
- DEPRECATED (use format instead): `includeContent=bool` (=false) (CLI: |
|
95
|
`--content|-c`). If true, the full content of the artifact is returned |
|
96
|
for text-only artifacts (but not for non-text artifacts). As of |
|
97
|
20120713 this option is only inspected if "format" is not specified. |
|
98
|
|
|
99
|
**Response payload example: (CHANGED SIGNIFICANTLY ON 20120713)** |
|
100
|
|
|
101
|
```json |
|
102
|
{ |
|
103
|
"type":"file", |
|
104
|
"name":"same name specified as FILE_HASH argument", |
|
105
|
"size": 12345, // in bytes, independent of format=... |
|
106
|
"parent": "hash of parent file blob. Not set for first generation.", |
|
107
|
"checkins":[{ |
|
108
|
"name":"src/json_detail.h", |
|
109
|
"timestamp":1319058803, |
|
110
|
"comment":"...", |
|
111
|
"user":"stephan", |
|
112
|
"checkin":"d2c1ae23a90b24f6ca1d7637193a59d5ecf3e680", |
|
113
|
"branch":"json", |
|
114
|
"state":"added|modified|removed" |
|
115
|
}, |
|
116
|
...], |
|
117
|
/* The following "content" properties are only set if format=raw|html */ |
|
118
|
"content": "file contents", |
|
119
|
"contentSize": "size of content field, in bytes. Affected by the format option!", |
|
120
|
"contentType": "text/plain", /* currently always text/plain */ |
|
121
|
"contentFormat": "html|raw" |
|
122
|
} |
|
123
|
``` |
|
124
|
|
|
125
|
The "checkins" array lists all checkins which include this file, and a |
|
126
|
file might have different names across different branches. The size and |
|
127
|
hash, however, are the same across all checkins for a given blob. |
|
128
|
|
|
129
|
<a id="wiki"></a> |
|
130
|
# Wiki Artifacts |
|
131
|
|
|
132
|
Returns information about wiki artifacts. |
|
133
|
|
|
134
|
**Status:** implemented 20111020, fixed to return the requested version |
|
135
|
(instead of the latest) on 20120302. |
|
136
|
|
|
137
|
**Request:** `/json/artifact/WIKI_HASH` |
|
138
|
|
|
139
|
**Required permissions:** "j" |
|
140
|
|
|
141
|
**Options:** |
|
142
|
|
|
143
|
- DEPRECATED (use format instead): `bool includeContent` (=false). If |
|
144
|
true then the raw content is returned with the wiki page, else no |
|
145
|
content is returned.\ |
|
146
|
CLI: `--includeContent|-c` |
|
147
|
- The `--format` option works as for |
|
148
|
[`/json/wiki/get`](api-wiki.md#get), and if set then it |
|
149
|
implies the `includeContent` option. |
|
150
|
|
|
151
|
**Response payload example:** |
|
152
|
|
|
153
|
Currently the same as [`/json/wiki/get`](api-wiki.md#get). |
|
154
|
|
|
155
|
[uvh]: ../hashes.md#uvh |
|
156
|
|