|
1
|
<title>Fossil File Formats</title> |
|
2
|
|
|
3
|
The global state of a fossil repository is kept simple so that it can |
|
4
|
endure in useful form for decades or centuries. |
|
5
|
A fossil repository is intended to be readable, |
|
6
|
searchable, and extensible by people not yet born. |
|
7
|
|
|
8
|
The global state of a fossil repository is an unordered |
|
9
|
set of <i>artifacts</i>. |
|
10
|
An artifact might be a source code file, the text of a wiki page, |
|
11
|
part of a trouble ticket, a description of a check-in including all |
|
12
|
the files in that check-in with the check-in comment and so forth. |
|
13
|
Artifacts are broadly grouped into two types: content artifacts and |
|
14
|
structural artifacts. Content artifacts are the raw project source-code |
|
15
|
files that are checked into the repository. Structural artifacts have |
|
16
|
special formatting rules and are used to show the relationships between |
|
17
|
other artifacts in the repository. It is possible for an artifact to |
|
18
|
be both a structure artifact and a content artifact, though this is |
|
19
|
rare. Artifacts can be text or binary. |
|
20
|
|
|
21
|
In addition to the global state, |
|
22
|
each fossil repository also contains local state. |
|
23
|
The local state consists of web-page formatting |
|
24
|
preferences, authorized users, ticket display and reporting formats, |
|
25
|
and so forth. The global state is shared in common among all |
|
26
|
repositories for the same project, whereas the local state is often |
|
27
|
different in separate repositories. |
|
28
|
The local state is not versioned and is not synchronized |
|
29
|
with the global state. |
|
30
|
The local state is not composed of artifacts and is not intended to be enduring. |
|
31
|
This document is concerned with global state only. Local state is only |
|
32
|
mentioned here in order to distinguish it from global state. |
|
33
|
|
|
34
|
<h2 id="names">1.0 Artifact Names</h2> |
|
35
|
|
|
36
|
Each artifact in the repository is named by a hash of its content. |
|
37
|
No prefixes, suffixes, or other information is added to an artifact before |
|
38
|
the hash is computed. The artifact name is just the (lower-case |
|
39
|
hexadecimal) hash of the raw artifact. |
|
40
|
|
|
41
|
Fossil currently computes artifact names using either SHA1 or SHA3-256. It |
|
42
|
is relatively easy to add new algorithms in the future, but there are no |
|
43
|
plans to do so at this time. |
|
44
|
|
|
45
|
When referring to artifacts in using tty commands or webpage URLs, it is |
|
46
|
sufficient to specify a unique prefix for the artifact name. If the input |
|
47
|
prefix is not unique, Fossil will show an error. Within a structural |
|
48
|
artifact, however, all references to other artifacts must be the complete |
|
49
|
hash. |
|
50
|
|
|
51
|
Prior to Fossil version 2.0, all names were formed from the SHA1 hash of |
|
52
|
the artifact. The key innovation in Fossil 2.0 was adding support for |
|
53
|
alternative hash algorithms. |
|
54
|
|
|
55
|
<h2 id="structural">2.0 Structural Artifacts</h2> |
|
56
|
|
|
57
|
A structural artifact is an artifact with a particular format |
|
58
|
that is used to define the relationships between other artifacts in the |
|
59
|
repository. |
|
60
|
Fossil recognizes the following kinds of structural |
|
61
|
artifacts: |
|
62
|
|
|
63
|
<ul> |
|
64
|
<li> [#manifest | Manifests] </li> |
|
65
|
<li> [#cluster | Clusters] </li> |
|
66
|
<li> [#ctrl | Control (a.k.a. Tag) Artifacts] </li> |
|
67
|
<li> [#wikichng | Wiki Pages] </li> |
|
68
|
<li> [#tktchng | Ticket Changes] </li> |
|
69
|
<li> [#attachment | Attachments] </li> |
|
70
|
<li> [#event | TechNotes] </li> |
|
71
|
<li> [#forum | Forum Posts] </li> |
|
72
|
</ul> |
|
73
|
|
|
74
|
These eight structural artifact types are described in subsections below. |
|
75
|
|
|
76
|
Structural artifacts are UTF-8 text. The artifact may be PGP clearsigned. |
|
77
|
After removal of the PGP clearsign header and suffix (if any) a structural |
|
78
|
artifact consists of one or more "cards" separated by a single newline |
|
79
|
(ASCII: 0x0a) character. Each card begins with a single |
|
80
|
character "card type". Zero or more arguments may follow |
|
81
|
the card type. All arguments are separated from each other |
|
82
|
and from the card-type character by a single space |
|
83
|
character. There is no surplus white space between arguments |
|
84
|
and no leading or trailing whitespace except for the newline |
|
85
|
character that acts as the card separator. All cards must be in strict |
|
86
|
lexicographical order (except for an |
|
87
|
[./fileformat.wiki#outofordercards|historical bug compatibility]). |
|
88
|
There may not be any duplicate cards. |
|
89
|
|
|
90
|
In the current implementation (as of 2017-02-27) the artifacts that |
|
91
|
make up a fossil repository are stored as delta- and zlib-compressed |
|
92
|
blobs in an <a href="http://www.sqlite.org/">SQLite</a> database. This |
|
93
|
is an implementation detail and might change in a future release. For |
|
94
|
the purpose of this article "file format" means the format of the artifacts, |
|
95
|
not how the artifacts are stored on disk. It is the artifact format that |
|
96
|
is intended to be enduring. The specifics of how artifacts are stored on |
|
97
|
disk, though stable, is not intended to live as long as the |
|
98
|
artifact format. |
|
99
|
|
|
100
|
<h3 id="manifest">2.1 The Manifest</h3> |
|
101
|
|
|
102
|
A manifest defines a check-in. |
|
103
|
A manifest contains a list of artifacts for |
|
104
|
each file in the project and the corresponding filenames, as |
|
105
|
well as information such as parent check-ins, the username of the |
|
106
|
programmer who created the check-in, the date and time when |
|
107
|
the check-in was created, and any check-in comments associated |
|
108
|
with the check-in. |
|
109
|
|
|
110
|
Allowed cards in the manifest are as follows: |
|
111
|
|
|
112
|
<div class="indent"> |
|
113
|
<b>B</b> <i>baseline-manifest</i><br> |
|
114
|
<b>C</b> <i>checkin-comment</i><br> |
|
115
|
<b>D</b> <i>time-and-date-stamp</i><br> |
|
116
|
<b>F</b> <i>filename</i> ?<i>hash</i>? ?<i>permissions</i>? ?<i>old-name</i>?<br> |
|
117
|
<b>N</b> <i>mimetype</i><br> |
|
118
|
<b>P</b> <i>artifact-hash</i>+<br> |
|
119
|
<b>Q</b> (<b>+</b>|<b>-</b>)<i>artifact-hash</i> ?<i>artifact-hash</i>?<br> |
|
120
|
<b>R</b> <i>repository-checksum</i><br> |
|
121
|
<b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br> |
|
122
|
<b>U</b> <i>user-login</i><br> |
|
123
|
<b>Z</b> <i>manifest-checksum</i> |
|
124
|
</div> |
|
125
|
|
|
126
|
A manifest may optionally have a single <b>B</b> card. The <b>B</b> card specifies |
|
127
|
another manifest that serves as the "baseline" for this manifest. A |
|
128
|
manifest that has a <b>B</b> card is called a delta-manifest and a manifest |
|
129
|
that omits the <b>B</b> card is a baseline-manifest. The other manifest |
|
130
|
identified by the argument of the <b>B</b> card must be a baseline-manifest. |
|
131
|
A baseline-manifest records the complete contents of a check-in. |
|
132
|
A delta-manifest records only changes from its baseline. |
|
133
|
|
|
134
|
A manifest must have exactly one <b>C</b> card. The sole argument to |
|
135
|
the <b>C</b> card is a check-in comment that describes the check-in that |
|
136
|
the manifest defines. The check-in comment is text. The following |
|
137
|
escape sequences are applied to the text: |
|
138
|
A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A |
|
139
|
newline (ASCII 0x0a) is "\n" (ASCII 0x5C, x6E). A backslash |
|
140
|
(ASCII 0x5C) is represented as two backslashes "\\". Apart from |
|
141
|
space and newline, no other whitespace characters are allowed in |
|
142
|
the check-in comment. Nor are any unprintable characters allowed |
|
143
|
in the comment. |
|
144
|
|
|
145
|
A manifest must have exactly one <b>D</b> card. The sole argument to |
|
146
|
the <b>D</b> card is a date-time stamp in the ISO8601 format. The |
|
147
|
date and time should be in coordinated universal time (UTC). |
|
148
|
The format one of: |
|
149
|
|
|
150
|
<pre class="indent"><i>YYYY-MM-DD<b>T</b>HH:MM:SS |
|
151
|
YYYY-MM-DD<b>T</b>HH:MM:SS.SSS</i></pre> |
|
152
|
|
|
153
|
A manifest has zero or more <b>F</b> cards. Each <b>F</b> card identifies a file |
|
154
|
that is part of the check-in. There are one, two, three, or four |
|
155
|
arguments. The first argument is the pathname of the file in the |
|
156
|
check-in relative to the root of the project file hierarchy. No ".." |
|
157
|
or "." directories are allowed within the filename. Space characters |
|
158
|
are escaped as in <b>C</b> card comment text. Backslash characters and |
|
159
|
newlines are not allowed within filenames. The directory separator |
|
160
|
character is a forward slash (ASCII 0x2F). The second argument to the |
|
161
|
<b>F</b> card is the lower-case hexadecimal artifact hash of |
|
162
|
the content artifact. The second argument is required for baseline |
|
163
|
manifests but is optional for delta manifests. When the second |
|
164
|
argument to the <b>F</b> card is omitted, it means that the file has been |
|
165
|
deleted relative to the baseline (files removed in baseline manifests |
|
166
|
versions are <em>not</em> added as <b>F</b> cards). The optional 3rd argument |
|
167
|
defines any special access permissions associated with the file. This |
|
168
|
can be defined as "x" to mean that the file is executable or "l" |
|
169
|
(small letter ell) to mean a symlink. All files are always readable |
|
170
|
and writable. This can be expressed by "w" permission if desired but |
|
171
|
is optional. The file format might be extended with new permission |
|
172
|
letters in the future. The optional 4th argument is the name of the |
|
173
|
same file as it existed in the parent check-in. If the name of the |
|
174
|
file is unchanged from its parent, then the 4th argument is omitted. |
|
175
|
|
|
176
|
A manifest has zero or one <b>N</b> cards. The <b>N</b> card specifies the mimetype for the |
|
177
|
text in the comment of the <b>C</b> card. If the <b>N</b> card is omitted, a default mimetype |
|
178
|
is used. Note that the <b>N</b> card has never actually been used by |
|
179
|
any Fossil implementation. The implementation has always interpreted |
|
180
|
check-in comments according to the [/wiki_rules|Fossil Wiki formatting rules]. |
|
181
|
There are no current plans to ever change that. |
|
182
|
|
|
183
|
A manifest has zero or one <b>P</b> cards. Most manifests have one <b>P</b> card. |
|
184
|
The <b>P</b> card has a varying number of arguments that |
|
185
|
define other manifests from which the current manifest |
|
186
|
is derived. Each argument is a lowercase |
|
187
|
hexadecimal artifact hash of a predecessor manifest. All arguments |
|
188
|
to the <b>P</b> card must be unique within that card. |
|
189
|
The first argument is the artifact hash of the direct ancestor of the manifest. |
|
190
|
Other arguments define manifests with which the first was |
|
191
|
merged to yield the current manifest. Most manifests have |
|
192
|
a <b>P</b> card with a single argument. The first manifest in the |
|
193
|
project has no ancestors and thus has no <b>P</b> card or (depending |
|
194
|
on the Fossil version) an empty <b>P</b> card (no arguments). |
|
195
|
|
|
196
|
A manifest has zero or more <b>Q</b> cards. A <b>Q</b> card is similar to a <b>P</b> card |
|
197
|
in that it defines a predecessor to the current check-in. But |
|
198
|
whereas a <b>P</b> card defines the immediate ancestor or a merge |
|
199
|
ancestor, the <b>Q</b> card is used to identify a single check-in or a small |
|
200
|
range of check-ins which were cherry-picked for inclusion in or |
|
201
|
exclusion from the current manifest. The first argument of |
|
202
|
the <b>Q</b> card is the artifact ID of another manifest (the "target") |
|
203
|
which has had its changes included or excluded in the current manifest. |
|
204
|
The target is preceded by "+" or "-" to show inclusion or |
|
205
|
exclusion, respectively. The optional second argument to the |
|
206
|
<b>Q</b> card is another manifest artifact ID which is the "baseline" |
|
207
|
for the cherry-pick. If omitted, the baseline is the primary |
|
208
|
parent of the target. The |
|
209
|
changes included or excluded consist of all changes moving from |
|
210
|
the baseline to the target. |
|
211
|
|
|
212
|
The <b>Q</b> card was added to the interface specification on 2011-02-26. |
|
213
|
Older versions of Fossil will reject manifests that contain <b>Q</b> cards. |
|
214
|
|
|
215
|
A manifest may optionally have a single <b>R</b> card. The <b>R</b> card has |
|
216
|
a single argument which is the MD5 checksum of all files in |
|
217
|
the check-in except the manifest itself. The checksum is expressed |
|
218
|
as 32 characters of lowercase hexadecimal. The checksum is |
|
219
|
computed as follows: For each file in the check-in (except for |
|
220
|
the manifest itself) in strict sorted lexicographical order, |
|
221
|
take the pathname of the file relative to the root of the |
|
222
|
repository, append a single space (ASCII 0x20), the |
|
223
|
size of the file in ASCII decimal, a single newline |
|
224
|
character (ASCII 0x0A), and the complete text of the file. |
|
225
|
Compute the MD5 checksum of the result. |
|
226
|
|
|
227
|
A manifest might contain one or more <b>T</b> cards used to set |
|
228
|
[./branching.wiki#tags | tags or properties] |
|
229
|
on the check-in. The format of the <b>T</b> card is the same as |
|
230
|
described in <i>Control Artifacts</i> section below, except that the |
|
231
|
second argument is the single character "<b>*</b>" instead of an |
|
232
|
artifact ID. The <b>*</b> in place of the artifact ID indicates that |
|
233
|
the tag or property applies to the current artifact. It is not |
|
234
|
possible to encode the current artifact ID as part of an artifact, |
|
235
|
since the act of inserting the artifact ID would change the artifact ID, |
|
236
|
hence a <b>*</b> is used to represent "self". <b>T</b> cards are typically |
|
237
|
added to manifests in order to set the <b>branch</b> property and a |
|
238
|
symbolic name when the check-in is intended to start a new branch. |
|
239
|
|
|
240
|
Each manifest has a single <b>U</b> card. The argument to the <b>U</b> card is |
|
241
|
the login of the user who created the manifest. The login name |
|
242
|
is encoded using the same character escapes as is used for the |
|
243
|
check-in comment argument to the <b>C</b> card. |
|
244
|
|
|
245
|
A manifest must have a single <b>Z</b> card as its last line. The argument |
|
246
|
to the <b>Z</b> card is a 32-character lowercase hexadecimal MD5 hash |
|
247
|
of all prior lines of the manifest up to and including the newline |
|
248
|
character that immediately precedes the "Z", excluding any PGP |
|
249
|
clear-signing prefix. The <b>Z</b> card is |
|
250
|
a sanity check to prove that the manifest is well-formed and |
|
251
|
consistent. |
|
252
|
|
|
253
|
A sample manifest from Fossil itself can be seen |
|
254
|
[/artifact/28987096ac | here]. |
|
255
|
|
|
256
|
<h3 id="cluster">2.2 Clusters</h3> |
|
257
|
|
|
258
|
A cluster is an artifact that declares the existence of other artifacts. |
|
259
|
Clusters are used during repository synchronization to help |
|
260
|
reduce network traffic. As such, clusters are an optimization and |
|
261
|
may be removed from a repository without loss or damage to the |
|
262
|
underlying project code. |
|
263
|
|
|
264
|
Allowed cards in the cluster are as follows: |
|
265
|
|
|
266
|
<div class="indent"> |
|
267
|
<b>M</b> <i>artifact-id</i><br /> |
|
268
|
<b>Z</b> <i>checksum</i> |
|
269
|
</div> |
|
270
|
|
|
271
|
A cluster contains one or more <b>M</b> cards followed by a single <b>Z</b> card. |
|
272
|
Each <b>M</b> card has a single argument which is the artifact ID of |
|
273
|
another artifact in the repository. The <b>Z</b> card works exactly like |
|
274
|
the <b>Z</b> card of a manifest. The argument to the <b>Z</b> card is the |
|
275
|
lower-case hexadecimal representation of the MD5 checksum of all |
|
276
|
prior cards in the cluster. The <b>Z</b> card is required. |
|
277
|
|
|
278
|
An example cluster from Fossil can be seen |
|
279
|
[/artifact/d03dbdd73a2a8 | here]. |
|
280
|
|
|
281
|
<h3 id="ctrl">2.3 Control (a.k.a. Tag) Artifacts</h3> |
|
282
|
|
|
283
|
Control artifacts are used to assign properties to other artifacts |
|
284
|
within the repository. Allowed cards in a control artifact are as |
|
285
|
follows: |
|
286
|
|
|
287
|
<div class="indent"> |
|
288
|
<b>D</b> <i>time-and-date-stamp</i><br /> |
|
289
|
<b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br /> |
|
290
|
<b>U</b> <i>user-name</i><br /> |
|
291
|
<b>Z</b> <i>checksum</i><br /> |
|
292
|
</div> |
|
293
|
|
|
294
|
Control articles are also referred to as Tag artifacts, but tags can |
|
295
|
also be applied via other artifact types, as described in |
|
296
|
[#summary|the Card Summary table]. |
|
297
|
|
|
298
|
A control artifact must have one <b>D</b> card, one <b>U</b> card, one <b>Z</b> card and |
|
299
|
one or more <b>T</b> cards. No other cards or other text is |
|
300
|
allowed in a control artifact. Control artifacts might be PGP |
|
301
|
clearsigned. |
|
302
|
|
|
303
|
The <b>D</b> card and the <b>Z</b> card of a control artifact are the same |
|
304
|
as in a manifest. |
|
305
|
|
|
306
|
The <b>T</b> card represents a [./branching.wiki#tags | tag or property] |
|
307
|
that is applied to |
|
308
|
some other artifact. The <b>T</b> card has two or three values. The |
|
309
|
second argument is the lowercase artifact ID of the artifact |
|
310
|
to which the tag is to be applied. The |
|
311
|
first value is the tag name. The first character of the tag |
|
312
|
is either "+", "-", or "*". The "+" means the tag should be added |
|
313
|
to the artifact. The "-" means the tag should be removed. |
|
314
|
The "*" character means the tag should be added to the artifact |
|
315
|
and all direct descendants (but not descendants through a merge) down |
|
316
|
to but not including the first descendant that contains a |
|
317
|
more recent "-", "*", or "+" tag with the same name. |
|
318
|
The optional third argument is the value of the tag. A tag |
|
319
|
without a value is a Boolean. |
|
320
|
|
|
321
|
When two or more tags with the same name are applied to the |
|
322
|
same artifact, the tag with the latest (most recent) date is |
|
323
|
used. |
|
324
|
|
|
325
|
Some tags have special meaning. The "comment" tag when applied |
|
326
|
to a check-in will override the check-in comment of that check-in |
|
327
|
for display purposes. The "user" tag overrides the name of the |
|
328
|
check-in user. The "date" tag overrides the check-in date. |
|
329
|
The "branch" tag sets the name of the branch that at check-in |
|
330
|
belongs to. Symbolic tags begin with the "sym-" prefix. |
|
331
|
|
|
332
|
The <b>U</b> card is the name of the user that created the control |
|
333
|
artifact. The <b>Z</b> card is the usual required artifact checksum. |
|
334
|
|
|
335
|
An example control artifact can be seen [/info/9d302ccda8 | here]. |
|
336
|
|
|
337
|
|
|
338
|
<h3 id="wikichng">2.4 Wiki Pages</h3> |
|
339
|
|
|
340
|
A wiki artifact defines a single version of a |
|
341
|
single wiki page. |
|
342
|
Wiki artifacts accept |
|
343
|
the following card types: |
|
344
|
|
|
345
|
<div class="indent"> |
|
346
|
<b>C</b> <i>change-comment</i><br> |
|
347
|
<b>D</b> <i>time-and-date-stamp</i><br /> |
|
348
|
<b>L</b> <i>wiki-title</i><br /> |
|
349
|
<b>N</b> <i>mimetype</i><br /> |
|
350
|
<b>P</b> <i>parent-artifact-id</i>+<br /> |
|
351
|
<b>U</b> <i>user-name</i><br /> |
|
352
|
<b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
|
353
|
<b>Z</b> <i>checksum</i> |
|
354
|
</div> |
|
355
|
|
|
356
|
The <b>D</b> card is the date and time when the wiki page was edited. |
|
357
|
The <b>P</b> card specifies the parent wiki pages, if any. The <b>L</b> card |
|
358
|
gives the name of the wiki page. The optional <b>N</b> card specifies |
|
359
|
the mimetype of the wiki text. If the <b>N</b> card is omitted, the |
|
360
|
mimetype is assumed to be text/x-fossil-wiki. |
|
361
|
The <b>U</b> card specifies the login |
|
362
|
of the user who made this edit to the wiki page. The <b>Z</b> card is |
|
363
|
the usual checksum over the entire artifact and is required. |
|
364
|
|
|
365
|
The <b>W</b> card is used to specify the text of the wiki page. The |
|
366
|
argument to the <b>W</b> card is an integer which is the number of bytes |
|
367
|
of text in the wiki page. That text follows the newline character |
|
368
|
that terminates the <b>W</b> card. The wiki text is always followed by one |
|
369
|
extra newline. |
|
370
|
|
|
371
|
The <b>C</b> card on a wiki page is optional. The argument is a comment |
|
372
|
that explains why the changes were made. The ability to have a <b>C</b> |
|
373
|
card on a wiki page artifact was added on 2019-12-02 at the suggestion |
|
374
|
of user George Krivov and is not currently used or generated by the |
|
375
|
implementation. Older versions of Fossil will reject a wiki-page |
|
376
|
artifact that includes a <b>C</b> card. |
|
377
|
|
|
378
|
An example wiki artifact can be seen |
|
379
|
[/artifact?name=7b2f5fd0e0&txt=1 | here]. |
|
380
|
|
|
381
|
<h3 id="tktchng">2.5 Ticket Changes</h3> |
|
382
|
|
|
383
|
A ticket-change artifact represents a change to a trouble ticket. |
|
384
|
The following cards are allowed on a ticket change artifact: |
|
385
|
|
|
386
|
<div class="indent"> |
|
387
|
<b>D</b> <i>time-and-date-stamp</i><br /> |
|
388
|
<b>J</b> ?<b>+</b>?<i>name</i> ?<i>value</i>?<br /> |
|
389
|
<b>K</b> <i>ticket-id</i><br /> |
|
390
|
<b>U</b> <i>user-name</i><br /> |
|
391
|
<b>Z</b> <i>checksum</i> |
|
392
|
</div> |
|
393
|
|
|
394
|
The <b>D</b> card is the usual date and time stamp and represents the point |
|
395
|
in time when the change was entered. The <b>U</b> card is the login of the |
|
396
|
programmer who entered this change. The <b>Z</b> card is the required checksum over |
|
397
|
the entire artifact. |
|
398
|
|
|
399
|
Every ticket has a distinct ticket-id: |
|
400
|
40-character lower-case hexadecimal number. |
|
401
|
The ticket-id is given in the <b>K</b> card. A ticket exists if it contains one or |
|
402
|
more changes. The first "change" to a ticket is what brings the |
|
403
|
ticket into existence. |
|
404
|
|
|
405
|
<b>J</b> cards specify changes to the "value" of "fields" in the ticket. |
|
406
|
If the <i>value</i> parameter of the <b>J</b> card is omitted, then the |
|
407
|
field is set to an empty string. |
|
408
|
Each fossil server has a ticket configuration which specifies the fields it |
|
409
|
understands. The ticket configuration is part of the local state for |
|
410
|
the repository and thus can vary from one repository to another. |
|
411
|
Hence a <b>J</b> card might specify a <i>field</i> that does not exist in the |
|
412
|
local ticket configuration. If a <b>J</b> card specifies a <i>field</i> that |
|
413
|
is not in the local configuration, then that <b>J</b> card |
|
414
|
is simply ignored. |
|
415
|
|
|
416
|
The first argument of the <b>J</b> card is the field name. The second |
|
417
|
value is the field value. If the field name begins with "+" then |
|
418
|
the value is appended to the prior value. Otherwise, the value |
|
419
|
on the <b>J</b> card replaces any previous value of the field. |
|
420
|
The field name and value are both encoded using the character |
|
421
|
escapes defined for the <b>C</b> card of a manifest. |
|
422
|
|
|
423
|
An example ticket-change artifact can be seen |
|
424
|
[/artifact/91f1ec6af053 | here]. |
|
425
|
|
|
426
|
<h3 id="attachment">2.6 Attachments</h3> |
|
427
|
|
|
428
|
An attachment artifact associates some other artifact that is the |
|
429
|
attachment (the source artifact) with a ticket or wiki page or |
|
430
|
technical note to which |
|
431
|
the attachment is connected (the target artifact). |
|
432
|
The following cards are allowed on an attachment artifact: |
|
433
|
|
|
434
|
<div class="indent"> |
|
435
|
<b>A</b> <i>filename target</i> ?<i>source</i>?<br /> |
|
436
|
<b>C</b> <i>comment</i><br /> |
|
437
|
<b>D</b> <i>time-and-date-stamp</i><br /> |
|
438
|
<b>N</b> <i>mimetype</i><br /> |
|
439
|
<b>U</b> <i>user-name</i><br /> |
|
440
|
<b>Z</b> <i>checksum</i> |
|
441
|
</div> |
|
442
|
|
|
443
|
The <b>A</b> card specifies a filename for the attachment in its first argument. |
|
444
|
The second argument to the <b>A</b> card is the name of the wiki page or |
|
445
|
ticket or technical note to which the attachment is connected. The |
|
446
|
third argument is either missing or else it is the lower-case artifact |
|
447
|
ID of the attachment itself. A missing third argument means that the |
|
448
|
attachment should be deleted. |
|
449
|
|
|
450
|
The <b>C</b> card is an optional comment describing what the attachment is about. |
|
451
|
The <b>C</b> card is optional, but there can only be one. |
|
452
|
|
|
453
|
A single <b>D</b> card is required to give the date and time when the attachment |
|
454
|
was applied. |
|
455
|
|
|
456
|
There may be zero or one <b>N</b> cards. The <b>N</b> card specifies the mimetype of the |
|
457
|
comment text provided in the <b>C</b> card. If the <b>N</b> card is omitted, the <b>C</b> card |
|
458
|
mimetype is taken to be text/plain. |
|
459
|
|
|
460
|
A single <b>U</b> card gives the name of the user who added the attachment. |
|
461
|
If an attachment is added anonymously, then the <b>U</b> card may be omitted. |
|
462
|
|
|
463
|
The <b>Z</b> card is the usual checksum over the rest of the attachment artifact. |
|
464
|
The <b>Z</b> card is required. |
|
465
|
|
|
466
|
|
|
467
|
<h3 id="event">2.7 Technical Notes</h3> |
|
468
|
|
|
469
|
A technical note or "technote" artifact (formerly known as an "event" artifact) |
|
470
|
associates a timeline comment and a page of text |
|
471
|
(similar to a wiki page) with a point in time. Technotes can be used |
|
472
|
to record project milestones, release notes, blog entries, process |
|
473
|
checkpoints, or news articles. |
|
474
|
The following cards are allowed on a technote artifact: |
|
475
|
|
|
476
|
<div class="indent"> |
|
477
|
<b>C</b> <i>comment</i><br> |
|
478
|
<b>D</b> <i>time-and-date-stamp</i><br /> |
|
479
|
<b>E</b> <i>technote-time</i> <i>technote-id</i><br /> |
|
480
|
<b>N</b> <i>mimetype</i><br /> |
|
481
|
<b>P</b> <i>parent-artifact-id</i>+<br /> |
|
482
|
<b>T</b> <b>+</b><i>tag-name</i> <b>*</b> ?<i>value</i>?<br /> |
|
483
|
<b>U</b> <i>user-name</i><br /> |
|
484
|
<b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
|
485
|
<b>Z</b> <i>checksum</i> |
|
486
|
</div> |
|
487
|
|
|
488
|
The <b>C</b> card contains text that is displayed on the timeline for the |
|
489
|
technote. The <b>C</b> card is optional, but there can only be one. |
|
490
|
|
|
491
|
A single <b>D</b> card is required to give the date and time when the |
|
492
|
technote artifact was created. This is different from the time at which |
|
493
|
the technote appears on the timeline. |
|
494
|
|
|
495
|
A single <b>E</b> card gives the time of the technote (the point on the timeline |
|
496
|
where the technote is displayed) and a unique identifier for the technote. |
|
497
|
When there are multiple artifacts with the same technote-id, the one with |
|
498
|
the most recent <b>D</b> card is the only one used. The technote-id must be a |
|
499
|
40-character lower-case hexadecimal string. |
|
500
|
|
|
501
|
The optional <b>N</b> card specifies the mimetype of the text of the technote |
|
502
|
that is contained in the <b>W</b> card. If the <b>N</b> card is omitted, then the |
|
503
|
<b>W</b> card text mimetype is assumed to be text/x-fossil-wiki, which is the |
|
504
|
Fossil wiki format. |
|
505
|
|
|
506
|
The optional <b>P</b> card specifies a prior technote with the same technote-id |
|
507
|
from which the current technote is an edit. The <b>P</b> card is a hint to the |
|
508
|
system that it might be space efficient to store one technote as a delta of |
|
509
|
the other. |
|
510
|
|
|
511
|
A technote might contain one or more <b>T</b> cards used to set |
|
512
|
[./branching.wiki#tags | tags or properties] |
|
513
|
on the technote. The format of the <b>T</b> card is the same as |
|
514
|
described in [#ctrl | Control Artifacts] section above, except that the |
|
515
|
second argument is the single character "<b>*</b>" instead of an |
|
516
|
artifact ID and the name is always prefaced by "<b>+</b>". |
|
517
|
The <b>*</b> in place of the artifact ID indicates that |
|
518
|
the tag or property applies to the current artifact. It is not |
|
519
|
possible to encode the current artifact ID as part of an artifact, |
|
520
|
since the act of inserting the artifact ID would change the artifact ID, |
|
521
|
hence a <b>*</b> is used to represent "self". The "<b>+</b>" on the |
|
522
|
name means that tags can only be "add" and they can only be non-propagating |
|
523
|
tags. In a technote, <b>T</b> cards are normally used to set the background |
|
524
|
display color for timelines. |
|
525
|
|
|
526
|
The optional <b>U</b> card gives the name of the user who entered the technote. |
|
527
|
|
|
528
|
A single <b>W</b> card provides wiki text for the document associated with the |
|
529
|
technote. The format of the <b>W</b> card is exactly the same as for a |
|
530
|
[#wikichng | wiki artifact]. |
|
531
|
|
|
532
|
The <b>Z</b> card is the required checksum over the rest of the artifact. |
|
533
|
|
|
534
|
<h3 id="forum">2.8 Forum Posts</h3> |
|
535
|
|
|
536
|
Forum posts are intended as a mechanism for users and developers to |
|
537
|
discuss a project. Forum posts are like messages on a mailing list. |
|
538
|
|
|
539
|
The following cards are allowed on an forum post artifact: |
|
540
|
|
|
541
|
<div class="indent"> |
|
542
|
<b>D</b> <i>time-and-date-stamp</i><br /> |
|
543
|
<b>G</b> <i>thread-root</i><br /> |
|
544
|
<b>H</b> <i>thread-title</i><br /> |
|
545
|
<b>I</b> <i>in-reply-to</i><br /> |
|
546
|
<b>N</b> <i>mimetype</i><br /> |
|
547
|
<b>P</b> <i>parent-artifact-id</i><br /> |
|
548
|
<b>U</b> <i>user-name</i><br /> |
|
549
|
<b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
|
550
|
<b>Z</b> <i>checksum</i> |
|
551
|
</div> |
|
552
|
|
|
553
|
Every forum post must have either one <b>I</b> card and one <b>G</b> card |
|
554
|
or one <b>H</b> card. |
|
555
|
Forum posts are organized into topic threads. The initial |
|
556
|
post for a thread (the root post) has an <b>H</b> card giving the title or |
|
557
|
subject for that thread. The argument to the <b>H</b> card is a string |
|
558
|
in the same format as a comment string in a <b>C</b> card. |
|
559
|
All follow-up posts have an <b>I</b> card that |
|
560
|
indicates which prior post in the same thread the current forum |
|
561
|
post is replying to, and a <b>G</b> card specifying the root post for |
|
562
|
the entire thread. The argument to <b>G</b> and <b>I</b> cards is the |
|
563
|
artifact hash for the prior forum post to which the card refers. |
|
564
|
|
|
565
|
In theory, it is sufficient for follow-up posts to have only an |
|
566
|
<b>I</b> card, since the <b>G</b> card value could be computed by following a |
|
567
|
chain of <b>I</b> cards. However, the <b>G</b> card is required in order to |
|
568
|
associate the artifact with a forum thread in the case where an |
|
569
|
intermediate artifact in the <b>I</b> card chain is shunned or otherwise |
|
570
|
becomes unreadable. |
|
571
|
|
|
572
|
A single <b>D</b> card is required to give the date and time when the |
|
573
|
forum post was created. |
|
574
|
|
|
575
|
The optional <b>N</b> card specifies the mimetype of the text of the technote |
|
576
|
that is contained in the <b>W</b> card. If the <b>N</b> card is omitted, then the |
|
577
|
<b>W</b> card text mimetype is assumed to be text/x-fossil-wiki, which is the |
|
578
|
Fossil wiki format. |
|
579
|
|
|
580
|
The optional <b>P</b> card specifies a prior forum post for which this |
|
581
|
forum post is an edit. For display purposes, only the child post |
|
582
|
is shown, though the historical post is retained as a record. |
|
583
|
If <b>P</b> cards are used and there exist multiple versions of the same |
|
584
|
forum post, then <b>I</b> cards for other artifacts refer to whichever |
|
585
|
version of the post was current at the time the reply was made, |
|
586
|
but <b>G</b> cards refer to the initial, unedited root post for the thread. |
|
587
|
Thus, following the chain of <b>I</b> cards back to the root of the thread |
|
588
|
may land on a different post than the one given in the <b>G</b> card. |
|
589
|
However, following the chain of <b>I</b> cards back to the thread root, |
|
590
|
then following <b>P</b> cards back to the initial version of the thread |
|
591
|
root must give the same artifact as is provided by the <b>G</b> card, |
|
592
|
otherwise the artifact containing the <b>G</b> card is considered invalid |
|
593
|
and should be ignored. |
|
594
|
|
|
595
|
In general, <b>P</b> cards may contain multiple arguments, indicating a |
|
596
|
merge. But since forum posts cannot be merged, the |
|
597
|
<b>P</b> card of a forum post may only contain a single argument. |
|
598
|
|
|
599
|
The <b>U</b> card gives name of the user who entered the forum post. |
|
600
|
|
|
601
|
A single <b>W</b> card provides wiki text for the forum post. |
|
602
|
The format of the <b>W</b> card is exactly the same as for a |
|
603
|
[#wikichng | wiki artifact]. |
|
604
|
|
|
605
|
The <b>Z</b> card is the required checksum over the rest of the artifact. |
|
606
|
|
|
607
|
|
|
608
|
<h2 id="summary">3.0 Card Summary</h2> |
|
609
|
|
|
610
|
The following table summarizes the various kinds of cards that appear |
|
611
|
on Fossil artifacts. A blank entry means that combination of card and |
|
612
|
artifact is not legal. A number or range of numbers indicates the number |
|
613
|
of times a card may (or must) appear in the corresponding artifact type. |
|
614
|
e.g. a value of 1 indicates a required unique card and 1+ indicates that one |
|
615
|
or more such cards are required. |
|
616
|
|
|
617
|
<table> |
|
618
|
<tr> |
|
619
|
<th>⇩ Card Format / Used By ⇨</th> |
|
620
|
<th>Manifest</th> |
|
621
|
<th>Cluster</th> |
|
622
|
<th>Control</th> |
|
623
|
<th>Wiki</th> |
|
624
|
<th>Ticket</th> |
|
625
|
<th>Attachment</th> |
|
626
|
<th>Technote</th> |
|
627
|
<th>Forum</th> |
|
628
|
</tr> |
|
629
|
<tr> |
|
630
|
<td><b>A</b> <i>filename</i> <i>target</i> ?<i>source</i>?</td> |
|
631
|
<td> </td> |
|
632
|
<td> </td> |
|
633
|
<td> </td> |
|
634
|
<td> </td> |
|
635
|
<td> </td> |
|
636
|
<td align=center><b>1</b></td> |
|
637
|
<td> </td> |
|
638
|
<td> </td> |
|
639
|
</tr> |
|
640
|
<tr> |
|
641
|
<td><b>B</b> <i>baseline</i></td> |
|
642
|
<td align=center><b>0-1</b></td> |
|
643
|
<td> </td> |
|
644
|
<td> </td> |
|
645
|
<td> </td> |
|
646
|
<td> </td> |
|
647
|
<td> </td> |
|
648
|
<td> </td> |
|
649
|
<td> </td> |
|
650
|
</tr> |
|
651
|
<tr> |
|
652
|
<td><b>C</b> <i>comment-text</i></td> |
|
653
|
<td align=center><b>1</b></td> |
|
654
|
<td> </td> |
|
655
|
<td> </td> |
|
656
|
<td align=center><b>0-1</b></td> |
|
657
|
<td> </td> |
|
658
|
<td align=center><b>0-1</b></td> |
|
659
|
<td align=center><b>0-1</b></td> |
|
660
|
<td> </td> |
|
661
|
</tr> |
|
662
|
<tr> |
|
663
|
<td><b>D</b> <i>date-time-stamp</i></td> |
|
664
|
<td align=center><b>1</b></td> |
|
665
|
<td> </td> |
|
666
|
<td align=center><b>1</b></td> |
|
667
|
<td align=center><b>1</b></td> |
|
668
|
<td align=center><b>1</b></td> |
|
669
|
<td align=center><b>1</b></td> |
|
670
|
<td align=center><b>1</b></td> |
|
671
|
<td align=center><b>1</b></td> |
|
672
|
</tr> |
|
673
|
<tr> |
|
674
|
<td><b>E</b> <i>technote-time technote-id</i></td> |
|
675
|
<td> </td> |
|
676
|
<td> </td> |
|
677
|
<td> </td> |
|
678
|
<td> </td> |
|
679
|
<td> </td> |
|
680
|
<td> </td> |
|
681
|
<td align=center><b>1</b></td> |
|
682
|
<td> </td> |
|
683
|
</tr> |
|
684
|
<tr> |
|
685
|
<td><b>F</b> <i>filename</i> ?<i>uuid</i>? ?<i>permissions</i>? ?<i>oldname</i>?</td> |
|
686
|
<td align=center><b>0+</b></td> |
|
687
|
<td> </td> |
|
688
|
<td> </td> |
|
689
|
<td> </td> |
|
690
|
<td> </td> |
|
691
|
<td> </td> |
|
692
|
<td> </td> |
|
693
|
<td> </td> |
|
694
|
</tr> |
|
695
|
<tr> |
|
696
|
<td><b>G</b> <i>thread-root</i></td> |
|
697
|
<td> </td> |
|
698
|
<td> </td> |
|
699
|
<td> </td> |
|
700
|
<td> </td> |
|
701
|
<td> </td> |
|
702
|
<td> </td> |
|
703
|
<td> </td> |
|
704
|
<td align=center><b>0-1</b></td> |
|
705
|
</tr> |
|
706
|
<tr> |
|
707
|
<td><b>H</b> <i>thread-title</i></td> |
|
708
|
<td> </td> |
|
709
|
<td> </td> |
|
710
|
<td> </td> |
|
711
|
<td> </td> |
|
712
|
<td> </td> |
|
713
|
<td> </td> |
|
714
|
<td> </td> |
|
715
|
<td align=center><b>0-1</b><sup><nowiki>[4]</nowiki></sup></td> |
|
716
|
</tr> |
|
717
|
<tr> |
|
718
|
<td><b>I</b> <i>in-reply-to</i></td> |
|
719
|
<td> </td> |
|
720
|
<td> </td> |
|
721
|
<td> </td> |
|
722
|
<td> </td> |
|
723
|
<td> </td> |
|
724
|
<td> </td> |
|
725
|
<td> </td> |
|
726
|
<td align=center><b>0-1</b><sup><nowiki>[4]</nowiki></sup></td> |
|
727
|
</tr> |
|
728
|
<tr> |
|
729
|
<td><b>J</b> <i>name</i> ?<i>value</i>?</td> |
|
730
|
<td> </td> |
|
731
|
<td> </td> |
|
732
|
<td> </td> |
|
733
|
<td> </td> |
|
734
|
<td align=center><b>1+</b></td> |
|
735
|
<td> </td> |
|
736
|
<td> </td> |
|
737
|
<td> </td> |
|
738
|
</tr> |
|
739
|
<tr> |
|
740
|
<td><b>K</b> <i>ticket-uuid</i></td> |
|
741
|
<td> </td> |
|
742
|
<td> </td> |
|
743
|
<td> </td> |
|
744
|
<td> </td> |
|
745
|
<td align=center><b>1</b></td> |
|
746
|
<td> </td> |
|
747
|
<td> </td> |
|
748
|
<td> </td> |
|
749
|
</tr> |
|
750
|
<tr> |
|
751
|
<td><b>L</b> <i>wiki-title</i></td> |
|
752
|
<td> </td> |
|
753
|
<td> </td> |
|
754
|
<td> </td> |
|
755
|
<td align=center><b>1</b></td> |
|
756
|
<td> </td> |
|
757
|
<td> </td> |
|
758
|
<td> </td> |
|
759
|
<td> </td> |
|
760
|
</tr> |
|
761
|
<tr> |
|
762
|
<td><b>M</b> <i>uuid</i></td> |
|
763
|
<td> </td> |
|
764
|
<td align=center><b>1+</b></td> |
|
765
|
<td> </td> |
|
766
|
<td> </td> |
|
767
|
<td> </td> |
|
768
|
<td> </td> |
|
769
|
<td> </td> |
|
770
|
<td> </td> |
|
771
|
</tr> |
|
772
|
<tr> |
|
773
|
<td><b>N</b> <i>mimetype</i></td> |
|
774
|
<td align=center><b>0-1</b></td> |
|
775
|
<td> </td> |
|
776
|
<td> </td> |
|
777
|
<td align=center><b>0-1</b></td> |
|
778
|
<td> </td> |
|
779
|
<td align=center><b>0-1</b></td> |
|
780
|
<td align=center><b>0-1</b></td> |
|
781
|
<td align=center><b>0-1</b></td> |
|
782
|
</tr> |
|
783
|
<tr> |
|
784
|
<td><b>P</b> <i>uuid ...</i></td> |
|
785
|
<td align=center><b>0-1</b></td> |
|
786
|
<td> </td> |
|
787
|
<td> </td> |
|
788
|
<td align=center><b>0-1</b></td> |
|
789
|
<td> </td> |
|
790
|
<td> </td> |
|
791
|
<td align=center><b>0-1</b></td> |
|
792
|
<td align=center><b>0-1</b><sup><nowiki>[5]</nowiki></sup></td> |
|
793
|
</tr> |
|
794
|
<tr> |
|
795
|
<td><b>Q</b> (<b>+</b>|<b>-</b>)<i>uuid</i> ?<i>uuid</i>?</td> |
|
796
|
<td align=center><b>0+</b></td> |
|
797
|
<td> </td> |
|
798
|
<td> </td> |
|
799
|
<td> </td> |
|
800
|
<td> </td> |
|
801
|
<td> </td> |
|
802
|
<td> </td> |
|
803
|
<td> </td> |
|
804
|
</tr> |
|
805
|
<tr> |
|
806
|
<td><b>R</b> <i>md5sum</i></td> |
|
807
|
<td align=center><b>0-1</b></td> |
|
808
|
<td> </td> |
|
809
|
<td> </td> |
|
810
|
<td> </td> |
|
811
|
<td> </td> |
|
812
|
<td> </td> |
|
813
|
<td> </td> |
|
814
|
<td> </td> |
|
815
|
<tr> |
|
816
|
<td><b>T</b> (<b>+</b>|<b>*</b>|<b>-</b>)<i>tagname</i> <i>uuid</i> ?<i>value</i>?<sup><nowiki>[1]</nowiki></sup></td> |
|
817
|
<td align=center><b>0+</b></td> |
|
818
|
<td> </td> |
|
819
|
<td align=center><b>1+</b><sup><nowiki>[2]</nowiki></sup></td> |
|
820
|
<td> </td> |
|
821
|
<td> </td> |
|
822
|
<td> </td> |
|
823
|
<td align=center><b>0+</b><sup><nowiki>[3]</nowiki></sup></td> |
|
824
|
<td> </td> |
|
825
|
</tr> |
|
826
|
<tr> |
|
827
|
<td><b>U</b> <i>username</i></td> |
|
828
|
<td align=center><b>1</b></td> |
|
829
|
<td> </td> |
|
830
|
<td align=center><b>1</b></td> |
|
831
|
<td align=center><b>1</b></td> |
|
832
|
<td align=center><b>1</b></td> |
|
833
|
<td align=center><b>0-1</b></td> |
|
834
|
<td align=center><b>0-1</b></td> |
|
835
|
<td align=center><b>1</b></td> |
|
836
|
</tr> |
|
837
|
<tr> |
|
838
|
<td><b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b></td> |
|
839
|
<td> </td> |
|
840
|
<td> </td> |
|
841
|
<td> </td> |
|
842
|
<td align=center><b>1</b></td> |
|
843
|
<td> </td> |
|
844
|
<td> </td> |
|
845
|
<td align=center><b>1</b></td> |
|
846
|
<td align=center><b>1</b></td> |
|
847
|
</tr> |
|
848
|
<tr> |
|
849
|
<td><b>Z</b> <i>md5sum</i></td> |
|
850
|
<td align=center><b>1</b></td> |
|
851
|
<td align=center><b>1</b></td> |
|
852
|
<td align=center><b>1</b></td> |
|
853
|
<td align=center><b>1</b></td> |
|
854
|
<td align=center><b>1</b></td> |
|
855
|
<td align=center><b>1</b></td> |
|
856
|
<td align=center><b>1</b></td> |
|
857
|
<td align=center><b>1</b></td> |
|
858
|
</tr> |
|
859
|
</table> |
|
860
|
|
|
861
|
Footnotes: |
|
862
|
|
|
863
|
1) T-card names may not be made up of only hexadecimal characters, as |
|
864
|
they would be indistinguishable from a hash prefix. |
|
865
|
|
|
866
|
2) Tags in [#ctrl | Control Artifacts] may not be |
|
867
|
self-referential. i.e. their target hash may not be <tt>*</tt>. |
|
868
|
|
|
869
|
3) Tags in [#event | Technotes] must be self-referential. i.e. their |
|
870
|
target hash must be <tt>*</tt>. Similarly, technote tags may only |
|
871
|
be non-propagating "add" tags. i.e. their name prefix must be |
|
872
|
<tt>+</tt>. |
|
873
|
|
|
874
|
4) [#forum | Forum Posts] must have either one H-card or one |
|
875
|
I-card, not both. |
|
876
|
|
|
877
|
5) [#forum | Forum Post] P-cards may have only a single parent |
|
878
|
hash. i.e. they may not have merge parents. |
|
879
|
|
|
880
|
<h2 id="addenda">4.0 Addenda</h2> |
|
881
|
|
|
882
|
This section contains additional information which may be useful when |
|
883
|
implementing algorithms described above. |
|
884
|
|
|
885
|
<h3 id="outofordercards">4.1 Relaxed Card Ordering Due To An Historical Bug</h3> |
|
886
|
|
|
887
|
All cards of a structural artifact should be in lexicographical order. |
|
888
|
The Fossil implementation verifies this and rejects any structural |
|
889
|
artifact which has out-of-order cards. Futhermore, when Fossil is |
|
890
|
generating new structural artifacts, it runs the generated artifact |
|
891
|
through the parser to confirm that all cards really are in the correct |
|
892
|
order before committing the transaction. In this way, Fossil prevents |
|
893
|
bugs in the code from accidentally inserting misformatted artifacts. |
|
894
|
The test parse of newly created artifacts is part of the |
|
895
|
[./selfcheck.wiki|self-check strategy] of Fossil. It takes a |
|
896
|
few more CPU cycles to double check each artifact before inserting it. |
|
897
|
The developers consider those CPU cycles well-spent. |
|
898
|
|
|
899
|
However, the card-order safety check was accidentally disabled due to |
|
900
|
[15d04de574383d61|a bug]. |
|
901
|
And while that bug was lurking undetected in the code, |
|
902
|
[5e67a7f4041a36ad|another bug] caused the N cards of Technical Notes |
|
903
|
to occur after the P card rather than before. |
|
904
|
Thus for a span of several years, Technical Note artifacts were being |
|
905
|
inserted into Fossil repositories that had their N and P cards in the |
|
906
|
wrong order. |
|
907
|
|
|
908
|
Both bugs have now been fixed. However, to prevent historical |
|
909
|
Technical Note artifacts that were inserted by users in good faith |
|
910
|
from being rejected by newer Fossil builds, the card ordering |
|
911
|
requirement is relaxed slightly. The actual implementation is this: |
|
912
|
|
|
913
|
<p class=blockquote> |
|
914
|
"All cards must be in strict lexicographic order, except that the |
|
915
|
N and P cards of a Technical Note artifact are allowed to be |
|
916
|
interchanged." |
|
917
|
</p> |
|
918
|
|
|
919
|
Future versions of Fossil might strengthen this slightly to only allow |
|
920
|
the out of order N and P cards for Technical Notes entered before |
|
921
|
a certain date. |
|
922
|
|
|
923
|
<h3>4.2 R-Card Hash Calculation</h3> |
|
924
|
|
|
925
|
Given a manifest file named <tt>MF</tt>, the following Bash shell code |
|
926
|
demonstrates how to compute the value of the <b>R</b> card in that manifest. |
|
927
|
This example uses manifest [28987096ac]. Lines starting with <tt>#</tt> are |
|
928
|
shell input and other lines are output. This demonstration assumes that the |
|
929
|
file versions represented by the input manifest are checked out |
|
930
|
under the current directory. |
|
931
|
|
|
932
|
<nowiki><pre> |
|
933
|
# head MF |
|
934
|
-----BEGIN PGP SIGNED MESSAGE----- |
|
935
|
Hash: SHA1 |
|
936
|
|
|
937
|
C Make\sthe\s"clearsign"\sPGP\ssigning\sdefault\sto\soff. |
|
938
|
D 2010-02-23T15:33:14 |
|
939
|
F BUILD.txt 4f7988767e4e48b29f7eddd0e2cdea4555b9161c |
|
940
|
F COPYRIGHT-GPL2.txt 06877624ea5c77efe3b7e39b0f909eda6e25a4ec |
|
941
|
... |
|
942
|
|
|
943
|
# grep '^R ' MF |
|
944
|
R c0788982781981c96a0d81465fec7192 |
|
945
|
|
|
946
|
# for i in $(awk '/^F /{print $2}' MF); do \ |
|
947
|
echo $i $(stat -c '%s' $i); \ |
|
948
|
cat $i; \ |
|
949
|
done | md5sum |
|
950
|
c0788982781981c96a0d81465fec7192 - |
|
951
|
</pre></nowiki> |
|
952
|
|
|
953
|
Minor caveats: the above demonstration will work only when none of the |
|
954
|
filenames in the manifest are "fossilized" (encoded) because they contain |
|
955
|
spaces. In that case the shell-generated hash would differ because the |
|
956
|
<tt>stat</tt> calls will fail to find such files (which are output in encoded |
|
957
|
form here). That approach also won't work for delta manifests. Calculating |
|
958
|
the <b>R</b> card for delta manifests requires traversing both the delta and its baseline in |
|
959
|
lexical order of the files, preferring the delta's copy if both contain |
|
960
|
a given file. |
|
961
|
|