1 <title>Fossil File Formats</title>
2 <h1 align="center">
3 Fossil File Formats
4 </h1>
5
6 The global state of a fossil repository is kept simple so that it can
7 endure in useful form for decades or centuries.
8 A fossil repository is intended to be readable,
9 searchable, and extensible by people not yet born.
10
11 The global state of a fossil repository is an unordered
12 set of <i>artifacts</i>.
13 An artifact might be a source code file, the text of a wiki page,
14 part of a trouble ticket, or one of several special control artifacts
15 used to show the relationships between other artifacts within the
16 project. Each artifact is normally represented on disk as a separate
17 file. Artifacts can be text or binary.
18
19 In addition to the global state,
20 each fossil repository also contains local state.
21 The local state consists of web-page formatting
22 preferences, authorized users, ticket display and reporting formats,
23 and so forth. The global state is shared in common among all
24 repositories for the same project, whereas the local state is often
25 different in separate repositories.
26 The local state is not versioned and is not synchronized
27 with the global state.
28 The local state is not composed of artifacts and is not intended to be enduring.
29 This document is concerned with global state only. Local state is only
30 mentioned here in order to distinguish it from global state.
31
32 Each artifact in the repository is named by its SHA1 hash.
33 No prefixes or meta information is added to a artifact before
34 its hash is computed. The name of a artifact in the repository
35 is exactly the same SHA1 hash that is computed by sha1sum
36 on the file as it exists in your source tree.</p>
37
38 Some artifacts have a particular format which gives them special
39 meaning to fossil. Fossil recognizes:
40
41 <ul>
42 <li> [#manifest | Manifests] </li>
43 <li> [#cluster | Clusters] </li>
44 <li> [#ctrl | Control Artifacts] </li>
45 <li> [#wikichng | Wiki Pages] </li>
46 <li> [#tktchng | Ticket Changes] </li>
47 <li> [#attachment | Attachments] </li>
48 <li> [#event | Events] </li>
49 </ul>
50
51 These seven artifact types are described in the following sections.
52
53 In the current implementation (as of 2009-01-25) the artifacts that
54 make up a fossil repository are stored in in as delta- and zlib-compressed
55 blobs in an <a href="http://www.sqlite.org/">SQLite</a> database. This
56 is an implementation detail and might change in a future release. For
57 the purpose of this article "file format" means the format of the artifacts,
58 not how the artifacts are stored on disk. It is the artifact format that
59 is intended to be enduring. The specifics of how artifacts are stored on
60 disk, though stable, is not intended to live as long as the
61 artifact format.
62
63 All of the artifacts can be extracted from a Fossil repository using
64 the "fossil deconstruct" command.
65
66 <a name="manifest"></a>
67 <h2>1.0 The Manifest</h2>
68
69 A manifest defines a check-in or version of the project
70 source tree. The manifest contains a list of artifacts for
71 each file in the project and the corresponding filenames, as
72 well as information such as parent check-ins, the name of the
73 programmer who created the check-in, the date and time when
74 the check-in was created, and any check-in comments associated
75 with the check-in.
76
77 Any artifact in the repository that follows the syntactic rules
78 of a manifest is a manifest. Note that a manifest can
79 be both a real manifest and also a content file, though this
80 is rare.
81
82 A manifest is a text file. Newline characters
83 (ASCII 0x0a) separate the file into "cards".
84 Each card begins with a single
85 character "card type". Zero or more arguments may follow
86 the card type. All arguments are separated from each other
87 and from the card-type character by a single space
88 character. There is no surplus white space between arguments
89 and no leading or trailing whitespace except for the newline
90 character that acts as the card separator.
91
92 All cards of the manifest occur in strict sorted lexicographical order.
93 No card may be duplicated.
94 The entire manifest may be PGP clear-signed, but otherwise it
95 may contain no additional text or data beyond what is described here.
96
97 Allowed cards in the manifest are as follows:
98
99 <blockquote>
100 <b>B</b> <i>baseline-manifest</i><br>
101 <b>C</b> <i>checkin-comment</i><br>
102 <b>D</b> <i>time-and-date-stamp</i><br>
103 <b>F</b> <i>filename</i> ?<i>SHA1-hash</i>? ?<i>permissions</i>? ?<i>old-name</i>?<br>
104 <b>N</b> <i>mimetype</i><br>
105 <b>P</b> <i>SHA1-hash</i>+<br>
106 <b>Q</b> (<b>+</b>|<b>-</b>)<i>SHA1-hash</i> ?<i>SHA1-hash</i>?<br>
107 <b>R</b> <i>repository-checksum</i><br>
108 <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br>
109 <b>U</b> <i>user-login</i><br>
110 <b>Z</b> <i>manifest-checksum</i>
111 </blockquote>
112
113 A manifest may optionally have a single B-card. The B-card specifies
114 another manifest that serves as the "baseline" for this manifest. A
115 manifest that has a B-card is called a delta-manifest and a manifest
116 that omits the B-card is a baseline-manifest. The other manifest
117 identified by the argument of the B-card must be a baseline-manifest.
118 A baseline-manifest records the complete contents of a checkin.
119 A delta-manifest records only changes from its baseline.
120
121 A manifest must have exactly one C-card. The sole argument to
122 the C-card is a check-in comment that describes the check-in that
123 the manifest defines. The check-in comment is text. The following
124 escape sequences are applied to the text:
125 A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A
126 newline (ASCII 0x0a) is "\n" (ASCII 0x5C, x6E). A backslash
127 (ASCII 0x5C) is represented as two backslashes "\\". Apart from
128 space and newline, no other whitespace characters are allowed in
129 the check-in comment. Nor are any unprintable characters allowed
130 in the comment.
131
132 A manifest must have exactly one D-card. The sole argument to
133 the D-card is a date-time stamp in the ISO8601 format. The
134 date and time should be in coordinated universal time (UTC).
135 The format one of:
136
137 <blockquote>
138 <i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i><br>
139 <i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i><b>.</b><i>SSS</i>
140 </blockquote>
141
142 A manifest has zero or more F-cards. Each F-card identifies a file
143 that is part of the check-in. There are one, two, three, or four arguments.
144 The first argument
145 is the pathname of the file in the check-in relative to the root
146 of the project file hierarchy. No ".." or "." directories are allowed
147 within the filename. Space characters are escaped as in C-card
148 comment text. Backslash characters and newlines are not allowed
149 within filenames. The directory separator character is a forward
150 slash (ASCII 0x2F). The second argument to the F-card is the
151 full 40-character lower-case hexadecimal SHA1 hash of the content
152 artifact. The second argument is required for baseline manifests
153 but is optional for delta manifests. When the second argument to the
154 F-card is omitted, it means that the file has been deleted relative
155 to the baseline. The optional 3rd argument defines any special access
156 permissions associated with the file. The only special code currently
157 defined is "x" which means that the file is executable. All files are
158 always readable and writable. This can be expressed by "w" permission
159 if desired but is optional. The file format might be extended with
160 new permission letters in the future.
161 The optional 4th argument is the name of the same file as it existed in
162 the parent check-in. If the name of the file is unchanged from its
163 parent, then the 4th argument is omitted.
164
165 A manifest has zero or one N-cards. The N-card specifies the mimetype for the
166 text in the comment of the C-card. If the N-card is omitted, a default mimetype
167 is used.
168
169 A manifest has zero or one P-cards. Most manifests have one P-card.
170 The P-card has a varying number of arguments that
171 defines other manifests from which the current manifest
172 is derived. Each argument is an 40-character lowercase
173 hexadecimal SHA1 of the predecessor manifest. All arguments
174 to the P-card must be unique to that line.
175 The first predecessor is the direct ancestor of the manifest.
176 Other arguments define manifests with which the first was
177 merged to yield the current manifest. Most manifests have
178 a P-card with a single argument. The first manifest in the
179 project has no ancestors and thus has no P-card.
180
181 A manifest has zero or more Q-cards. A Q-card is similar to a P-card
182 in that it defines a predecessor to the current check-in. But
183 whereas a P-card defines the immediate ancestor or a merge
184 ancestor, the Q-card is used to identify a single check-in or a small
185 range of check-ins which were cherry-picked for inclusion in or
186 exclusion from the current manifest. The first argument of
187 the Q-card is the artifact ID of another manifest (the "target")
188 which has had its changes included or excluded in the current manifest.
189 The target is preceeded by "+" or "-" to show inclusion or
190 exclusion, respectively. The optional second argument to the
191 Q-card is another manifest artifact ID which is the "baseline"
192 for the cherry-pick. If omitted, the baseline is the primary
193 parent of the target. The
194 changes included or excluded consist of all changes moving from
195 the baseline to the target.
196
197 The Q-card was added to the interface specification on 2011-02-26.
198 Older versions of Fossil will reject manifests that contain Q-cards.
199
200 A manifest may optionally have a single R-card. The R-card has
201 a single argument which is the MD5 checksum of all files in
202 the check-in except the manifest itself. The checksum is expressed
203 as 32-characters of lowercase hexadecimal. The checksum is
204 computed as follows: For each file in the check-in (except for
205 the manifest itself) in strict sorted lexicographical order,
206 take the pathname of the file relative to the root of the
207 repository, append a single space (ASCII 0x20), the
208 size of the file in ASCII decimal, a single newline
209 character (ASCII 0x0A), and the complete text of the file.
210 Compute the MD5 checksum of the result.
211
212 A manifest might contain one or more T-cards used to set
213 [./branching.wiki#tags | tags or properties]
214 on the check-in. The format of the T-card is the same as
215 described in <i>Control Artifacts</i> section below, except that the
216 second argument is the single characcter "<b>*</b>" instead of an
217 artifact ID. The <b>*</b> in place of the artifact ID indicates that
218 the tag or property applies to the current artifact. It is not
219 possible to encode the current artifact ID as part of an artifact,
220 since the act of inserting the artifact ID would change the artifact ID,
221 hence a <b>*</b> is used to represent "self". T-cards are typically
222 added to manifests in order to set the <b>branch</b> property and a
223 symbolic name when the check-in is intended to start a new branch.
224
225 Each manifest has a single U-card. The argument to the U-card is
226 the login of the user who created the manifest. The login name
227 is encoded using the same character escapes as is used for the
228 check-in comment argument to the C-card.
229
230 A manifest must have a single Z-card as its last line. The argument
231 to the Z-card is a 32-character lowercase hexadecimal MD5 hash
232 of all prior lines of the manifest up to and including the newline
233 character that immediately precedes the "Z". The Z-card is
234 a sanity check to prove that the manifest is well-formed and
235 consistent.
236
237 A sample manifest from Fossil itself can be seen
238 [/artifact/28987096ac | here].
239
240 <a name="cluster"></a>
241 <h2>2.0 Clusters</h2>
242
243 A cluster is a artifact that declares the existence of other artifacts.
244 Clusters are used during repository synchronization to help
245 reduce network traffic. As such, clusters are an optimization and
246 may be removed from a repository without loss or damage to the
247 underlying project code.
248
249 Clusters follow a syntax that is very similar to manifests.
250 A Cluster is a line-oriented text file. Newline characters
251 (ASCII 0x0a) separate the artifact into cards. Each card begins with a single
252 character "card type". Zero or more arguments may follow
253 the card type. All arguments are separated from each other
254 and from the card-type character by a single space
255 character. There is no surplus white space between arguments
256 and no leading or trailing whitespace except for the newline
257 character that acts as the card separator.
258 All cards of a cluster occur in strict sorted lexicographical order.
259 No card may be duplicated.
260 The cluster may not contain additional text or data beyond
261 what is described here.
262 Unlike manifests, clusters are never PGP signed.
263
264 Allowed cards in the cluster are as follows:
265
266 <blockquote>
267 <b>M</b> <i>artifact-id</i><br />
268 <b>Z</b> <i>checksum</i>
269 </blockquote>
270
271 A cluster contains one or more "M" cards followed by a single "Z"
272 line. Each M card has a single argument which is the artifact ID of
273 another artifact in the repository. The Z card work exactly like
274 the Z card of a manifest. The argument to the Z card is the
275 lower-case hexadecimal representation of the MD5 checksum of all
276 prior cards in the cluster. The Z-card is required.
277
278 An example cluster from Fossil can be seen
279 [/artifact/d03dbdd73a2a8 | here].
280
281 <a name="ctrl"></a>
282 <h2>3.0 Control Artifacts</h2>
283
284 Control artifacts are used to assign properties to other artifacts
285 within the repository. The basic format of a control artifact is
286 the same as a manifest or cluster. A control artifact is a text
287 file divided into cards by newline characters. Each card has a
288 single-character card type followed by arguments. Spaces separate
289 the card type and the arguments. No surplus whitespace is allowed.
290 All cards must occur in strict lexicographical order.
291
292 Allowed cards in a control artifact are as follows:
293
294 <blockquote>
295 <b>D</b> <i>time-and-date-stamp</i><br />
296 <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br />
297 <b>U</b> <i>user-name</i><br />
298 <b>Z</b> <i>checksum</i><br />
299 </blockquote>
300
301 A control artifact must have one D card, one U card, one Z card and
302 one or more T cards. No other cards or other text is
303 allowed in a control artifact. Control artifacts might be PGP
304 clearsigned.
305
306 The D card and the Z card of a control artifact are the same
307 as in a manifest.
308
309 The T card represents a [./branching.wiki#tags | tag or property]
310 that is applied to
311 some other artifact. The T card has two or three values. The
312 second argument is the 40 character lowercase artifact ID of the artifact
313 to which the tag is to be applied. The
314 first value is the tag name. The first character of the tag
315 is either "+", "-", or "*". The "+" means the tag should be added
316 to the artifact. The "-" means the tag should be removed.
317 The "*" character means the tag should be added to the artifact
318 and all direct descendants (but not descendents through a merge) down
319 to but not including the first descendant that contains a
320 more recent "-" or "+" tag with the same name.
321 The optional third argument is the value of the tag. A tag
322 without a value is a boolean.
323
324 When two or more tags with the same name are applied to the
325 same artifact, the tag with the latest (most recent) date is
326 used.
327
328 Some tags have special meaning. The "comment" tag when applied
329 to a check-in will override the check-in comment of that check-in
330 for display purposes. The "user" tag overrides the name of the
331 check-in user. The "date" tag overrides the check-in date.
332 The "branch" tag sets the name of the branch that at check-in
333 belongs to. Symbolic tags begin with the "sym-" prefix.
334
335 The U card is the name of the user that created the control
336 artifact. The Z card is the usual required artifact checksum.
337
338 An example control artifacts can be seen [/info/9d302ccda8 | here].
339
340
341 <a name="wikichng"></a>
342 <h2>4.0 Wiki Pages</h2>
343
344 A wiki page is an artifact with a format similar to manifests,
345 clusters, and control artifacts. The artifact is divided into
346 cards by newline characters. The format of each card is as in
347 manifests, clusters, and control artifacts. Wiki artifacts accept
348 the following card types:
349
350 <blockquote>
351 <b>D</b> <i>time-and-date-stamp</i><br />
352 <b>L</b> <i>wiki-title</i><br />
353 <b>N</b> <i>mimetype</i><br />
354 <b>P</b> <i>parent-artifact-id</i>+<br />
355 <b>U</b> <i>user-name</i><br />
356 <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br />
357 <b>Z</b> <i>checksum</i>
358 </blockquote>
359
360 The D card is the date and time when the wiki page was edited.
361 The P card specifies the parent wiki pages, if any. The L card
362 gives the name of the wiki page. The optional N card specifies
363 the mimetype of the wiki text. If the N card is omitted, the
364 mimetype is assumed to be text/x-fossil.
365 The U card specifies the login
366 of the user who made this edit to the wiki page. The Z card is
367 the usual checksum over the either artifact and is required.
368
369 The W card is used to specify the text of the wiki page. The
370 argument to the W card is an integer which is the number of bytes
371 of text in the wiki page. That text follows the newline character
372 that terminates the W card. The wiki text is always followed by one
373 extra newline.
374
375 An example wiki artifact can be seen
376 [/artifact?name=7b2f5fd0e0&txt=1 | here].
377
378 <a name="tktchng"></a>
379 <h2>5.0 Ticket Changes</h2>
380
381 A ticket-change artifact represents a change to a trouble ticket.
382 The following cards are allowed on a ticket change artifact:
383
384 <blockquote>
385 <b>D</b> <i>time-and-date-stamp</i><br />
386 <b>J</b> ?<b>+</b>?<i>name</i> ?<i>value</i>?<br />
387 <b>K</b> <i>ticket-id</i><br />
388 <b>U</b> <i>user-name</i><br />
389 <b>Z</b> <i>checksum</i>
390 </blockquote>
391
392 The D card is the usual date and time stamp and represents the point
393 in time when the change was entered. The U card is the login of the
394 programmer who entered this change. The Z card is the required checksum over
395 the entire artifact.
396
397 Every ticket has a distinct ticket-id:
398 40-character lower-case hexadecimal number.
399 The ticket-id is given in the K-card. A ticket exists if it contains one or
400 more changes. The first "change" to a ticket is what brings the
401 ticket into existence.
402
403 J cards specify changes to the "value" of "fields" in the ticket.
404 If the <i>value</i> parameter of the J card is omitted, then the
405 field is set to an empty string.
406 Each fossil server has a ticket configuration which specifies the fields its
407 understands. The ticket configuration is part of the local state for
408 the repository and thus can vary from one repository to another.
409 Hence a J card might specify a <i>field</i> that do not exist in the
410 local ticket configuration. If a J card specifies a <i>field</i> that
411 is not in the local configuration, then that J card
412 is simply ignored.
413
414 The first argument of the J card is the field name. The second
415 value is the field value. If the field name begins with "+" then
416 the value is appended to the prior value. Otherwise, the value
417 on the J card replaces any previous value of the field.
418 The field name and value are both encoded using the character
419 escapes defined for the C card of a manifest.
420
421 An example ticket-change artifact can be seen
422 [/artifact/91f1ec6af053 | here].
423
424 <a name="attachment"></a>
425 <h2>6.0 Attachments</h2>
426
427 An attachment artifact associates some other artifact that is the
428 attachment (the source artifact) with a ticket or wiki page or event to which
429 the attachment is connected (the target artifact).
430 The following cards are allowed on an attachment artifact:
431
432 <blockquote>
433 <b>A</b> <i>filename target</i> ?<i>source</i>?<br />
434 <b>C</b> <i>comment</i><br />
435 <b>D</b> <i>time-and-date-stamp</i><br />
436 <b>N</b> <i>mimetype</i><br />
437 <b>U</b> <i>user-name</i><br />
438 <b>Z</b> <i>checksum</i>
439 </blockquote>
440
441 The A card specifies a filename for the attachment in its first argument.
442 The second argument to the A card is the name
443 of the wiki page or ticket or event to which the attachment is connected. The
444 third argument is either missing or else it is the 40-character artifact
445 ID of the attachment itself. A missing third argument means that the
446 attachment should be deleted.
447
448 The C card is an optional comment describing what the attachment is about.
449 The C card is optional, but there can only be one.
450
451 A single D card is required to give the date and time when the attachment
452 was applied.
453
454 There may be zero or one N cards. The N card specifies the mimetype of the
455 comment text provided in the C card. If the N card is omitted, the C card
456 mimetype is taken to be text/plain.
457
458 A single U card gives the name of the user to added the attachment.
459 If an attachment is added anonymously, then the U card may be omitted.
460
461 The Z card is the usual checksum over the rest of the attachment artifact.
462 The Z card is required.
463
464
465 <a name="event"></a>
466 <h2>7.0 Events</h2>
467
468 An event artifact associates a timeline comment and a page of text
469 (similar to a wiki page) with a point in time. Events can be used
470 to record project milestones, release notes, blog entries, process
471 checkpoints, or news articles.
472 The following cards are allowed on an event artifact:
473
474 <blockquote>
475 <b>C</b> <i>comment</i><br>
476 <b>D</b> <i>time-and-date-stamp</i><br />
477 <b>E</b> <i>event-time</i> <i>event-id</i><br />
478 <b>N</b> <i>mimetype</i><br />
479 <b>P</b> <i>parent-artifact-id</i>+<br />
480 <b>T</b> <b>+</b><i>tag-name</i> <b>*</b> ?<i>value</i>?<br />
481 <b>U</b> <i>user-name</i><br />
482 <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br />
483 <b>Z</b> <i>checksum</i>
484 </blockquote>
485
486 The C card contains text that is displayed on the timeline for the
487 event. Exactly one C card is required on an event artifact.
488
489 A single D card is required to give the date and time when the
490 event artifact was created. This is different from the time at which
491 the event occurs.
492
493 A single E card gives the time of the event (the point on the timeline
494 where the event is displayed) and a unique identifier for the event.
495 When there are multiple artifacts with the same event-id, the one with
496 the most recent D card is the only one used. The event-id must be a
497 40-character lower-case hexadecimal string.
498
499 The optional N card specifies the mimetype of the text of the event
500 that is contained in the W card. If the N card is omitted, then the
501 W card text mimetype is assumed to be text/x-fossil, which is the
502 Fossil wiki format.
503
504 The optional P card specifies a prior event with the same event-id from
505 which the current event is an edit. The P card is a hint to the system
506 that it might be space efficient to store one event as a delta of the
507 other.
508
509 An event might contain one or more T-cards used to set
510 [./branching.wiki#tags | tags or properties]
511 on the event. The format of the T-card is the same as
512 described in [#ctrl | Control Artifacts] section above, except that the
513 second argument is the single characcter "<b>*</b>" instead of an
514 artifact ID and the name is always prefaced by "<b>+</b>".
515 The <b>*</b> in place of the artifact ID indicates that
516 the tag or property applies to the current artifact. It is not
517 possible to encode the current artifact ID as part of an artifact,
518 since the act of inserting the artifact ID would change the artifact ID,
519 hence a <b>*</b> is used to represent "self". The "<b>+</b>" on the
520 name means that tags can only be add and they can only be non-propagating
521 tags. A an event, T cards are normally used to set the background
522 display color for timelines.
523
524 The optional U card gives name of the user who entered the event.
525
526 A single W card provides wiki text for the document associated with the
527 event. The format of the W card is exactly the same as for a
528 [#wikichng | wiki artifact].
529
530 The Z card is the required checksum over the rest of the artifact.
531
532
533 <a name="summary"></a>
534 <h2>8.0 Card Summary</h2>
535
536 The following table summarizes the various kinds of cards that appear
537 on Fossil artifacts. A blank entry means that combination of card and
538 artifact is not legal. A number or range of numbers indicates the number
539 of times a card may (or must) appear in the corresponding artifact type.
540 e.g. a value of 1 indicates a required unique card and 1+ indicates that one
541 or more such cards are required.
542
543 <table border=1 width="100%">
544 <tr>
545 <th rowspan=2 valign=bottom>Card Format</th>
546 <th colspan=7>Used By</th>
547 </tr>
548 <tr>
549 <th>Manifest</th>
550 <th>Cluster</th>
551 <th>Control</th>
552 <th>Wiki</th>
553 <th>Ticket</th>
554 <th>Attachment</th>
555 <th>Event</th>
556 </tr>
557 <tr>
558 <td><b>A</b> <i>filename</i> <i>target</i> ?<i>source</i>?</td>
559 <td> </td>
560 <td> </td>
561 <td> </td>
562 <td> </td>
563 <td> </td>
564 <td align=center><b>1</b></td>
565 <td> </td>
566 </tr>
567 <tr>
568 <td><b>B</b> <i>baseline</i></td>
569 <td align=center><b>0-1*</b></td>
570 <td> </td>
571 <td> </td>
572 <td> </td>
573 <td> </td>
574 <td> </td>
575 <td> </td>
576 </tr>
577 <tr><td> </td><td colspan='7'>* = Required for delta manifests</td></tr>
578 <tr>
579 <td><b>C</b> <i>comment-text</i></td>
580 <td align=center><b>1</b></td>
581 <td> </td>
582 <td> </td>
583 <td> </td>
584 <td> </td>
585 <td align=center><b>0-1</b></td>
586 <td align=center><b>1</b></td>
587 </tr>
588 <tr>
589 <td><b>D</b> <i>date-time-stamp</i></td>
590 <td align=center><b>1</b></td>
591 <td align=center> </td>
592 <td align=center><b>1</b></td>
593 <td align=center><b>1</b></td>
594 <td align=center><b>1</b></td>
595 <td align=center><b>1</b></td>
596 <td align=center><b>1</b></td>
597 </tr>
598 <tr>
599 <td><b>E</b> <i>event-time event-id</i></td>
600 <td align=center> </td>
601 <td align=center> </td>
602 <td align=center> </td>
603 <td align=center> </td>
604 <td align=center> </td>
605 <td align=center> </td>
606 <td align=center><b>1</b></td>
607 </tr>
608 <tr>
609 <td><b>F</b> <i>filename</i> ?<i>uuid</i>? ?<i>permissions</i>? ?<i>oldname</i>?</td>
610 <td align=center><b>0+</b></td>
611 <td align=center> </td>
612 <td align=center> </td>
613 <td align=center> </td>
614 <td align=center> </td>
615 <td align=center> </td>
616 <td align=center> </td>
617 </tr>
618 <tr>
619 <td><b>J</b> <i>name</i> ?<i>value</i>?</td>
620 <td align=center> </td>
621 <td align=center> </td>
622 <td align=center> </td>
623 <td align=center> </td>
624 <td align=center><b>1+</b></td>
625 <td align=center> </td>
626 <td align=center> </td>
627 </tr>
628 <tr>
629 <td><b>K</b> <i>ticket-uuid</i></td>
630 <td align=center> </td>
631 <td align=center> </td>
632 <td align=center> </td>
633 <td align=center> </td>
634 <td align=center><b>1</b></td>
635 <td align=center> </td>
636 <td align=center> </td>
637 </tr>
638 <tr>
639 <td><b>L</b> <i>wiki-title</i></td>
640 <td align=center> </td>
641 <td align=center> </td>
642 <td align=center> </td>
643 <td align=center><b>1</b></td>
644 <td align=center> </td>
645 <td align=center> </td>
646 <td align=center> </td>
647 </tr>
648 <tr>
649 <td><b>M</b> <i>uuid</i></td>
650 <td align=center> </td>
651 <td align=center><b>1+</b></td>
652 <td align=center> </td>
653 <td align=center> </td>
654 <td align=center> </td>
655 <td align=center> </td>
656 <td align=center> </td>
657 </tr>
658 <tr>
659 <td><b>N</b> <i>mimetype</i></td>
660 <td align=center><b>0-1</b></td>
661 <td align=center> </td>
662 <td align=center> </td>
663 <td align=center><b>0-1</b></td>
664 <td align=center> </td>
665 <td align=center><b>0-1</b></td>
666 <td align=center><b>0-1</b></td>
667 </tr>
668 <tr>
669 <td><b>P</b> <i>uuid ...</i></td>
670 <td align=center><b>0-1</b></td>
671 <td align=center> </td>
672 <td align=center> </td>
673 <td align=center><b>0-1</b></td>
674 <td align=center> </td>
675 <td align=center> </td>
676 <td align=center><b>0-1</b></td>
677 </tr>
678 <tr>
679 <td><b>Q</b> (<b>+</b>|<b>-</b>)<i>uuid</i> ?<i>uuid</i>?</td>
680 <td align=center><b>0+</b></td>
681 <td align=center> </td>
682 <td align=center> </td>
683 <td align=center> </td>
684 <td align=center> </td>
685 <td align=center> </td>
686 <td align=center> </td>
687 </tr>
688 <tr>
689 <td><b>R</b> <i>md5sum</i></td>
690 <td align=center><b>0-1*</b></td>
691 <td align=center> </td>
692 <td align=center> </td>
693 <td align=center> </td>
694 <td align=center> </td>
695 <td align=center> </td>
696 <td align=center> </td>
697 <tr><td> </td><td colspan='7'>* = Required when using F cards</td></tr>
698 <tr>
699 <td><b>T</b> (<b>+</b>|<b>*</b>|<b>-</b>)<i>tagname</i> <i>uuid</i> ?<i>value</i>?</td>
700 <td align=center><b>0+</b></td>
701 <td align=center> </td>
702 <td align=center><b>1+</b></td>
703 <td align=center> </td>
704 <td align=center> </td>
705 <td align=center> </td>
706 <td align=center><b>0+</b></td>
707 </tr>
708 <tr>
709 <td><b>U</b> <i>username</i></td>
710 <td align=center><b>1</b></td>
711 <td align=center> </td>
712 <td align=center><b>1</b></td>
713 <td align=center><b>1</b></td>
714 <td align=center><b>1</b></td>
715 <td align=center><b>0-1</b></td>
716 <td align=center><b>0-1</b></td>
717 </tr>
718 <tr>
719 <td><b>W</b> <i>size</i></td>
720 <td align=center> </td>
721 <td align=center> </td>
722 <td align=center> </td>
723 <td align=center><b>1</b></td>
724 <td align=center> </td>
725 <td align=center> </td>
726 <td align=center><b>1</b></td>
727 </tr>
728 <tr>
729 <td><b>Z</b> <i>md5sum</i></td>
730 <td align=center><b>1</b></td>
731 <td align=center><b>1</b></td>
732 <td align=center><b>1</b></td>
733 <td align=center><b>1</b></td>
734 <td align=center><b>1</b></td>
735 <td align=center><b>1</b></td>
736 <td align=center><b>1</b></td>
737 </tr>
738 </table>
739
740
741 <a name="addenda"></a>
742 <h2>9.0 Addenda</h2>
743
744 This section contains additional information which may be useful when
745 implementing algorithms described above.
746
747 <h3>R Card Hash Calculation</h3>
748
749 Given a manifest file named <tt>MF</tt>, the following Bash shell code
750 demonstrates how to compute the value of the R card in that manifest.
751 This example uses manifest [28987096ac]. Lines starting with <tt>#</tt> are
752 shell input and other lines are output. This demonstration assumes that the
753 file versions represented by the input manifest are checked out
754 under the current directory.
755
756 <nowiki><pre>
757 # head MF
758 -----BEGIN PGP SIGNED MESSAGE-----
759 Hash: SHA1
760
761 C Make\sthe\s"clearsign"\sPGP\ssigning\sdefault\sto\soff.
762 D 2010-02-23T15:33:14
763 F BUILD.txt 4f7988767e4e48b29f7eddd0e2cdea4555b9161c
764 F COPYRIGHT-GPL2.txt 06877624ea5c77efe3b7e39b0f909eda6e25a4ec
765 ...
766
767 # grep '^R ' MF
768 R c0788982781981c96a0d81465fec7192
769
770 # for i in $(awk '/^F /{print $2}' MF); do \
771 echo $i $(stat -c '%s' $i); \
772 cat $i; \
773 done | md5sum
774 c0788982781981c96a0d81465fec7192 -
775 </pre></nowiki>
776
777 Minor caveats: the above demonstration will work only when none of the
778 filenames in the manifest are "fossilized" (encoded) because they contain
779 spaces. In that case the shell-generated hash would differ because the
780 <tt>stat</tt> calls will fail to find such files (which are output in encoded
781 form here). That approach also won't work for delta manifests. Calculating
782 the R-card for delta manifests requires traversing both the delta and its baseline in
783 lexical order of the files, prefering the delta's copy if both contain
784 a given file.