Artifact [9974dfbc]

Artifact 9974dfbc5c0ca5074910467a9b5034796470b77e:

     1  <title>Fossil File Formats</title>
     2  <h1 align="center">
     3  Fossil File Formats
     4  </h1>
     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.
    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.
    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.
    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>
    38  Some artifacts have a particular format which gives them special
    39  meaning to fossil.  Fossil recognizes:
    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>
    51  These seven artifact types are described in the following sections.
    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="">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.
    63  All of the artifacts can be extracted from a Fossil repository using
    64  the "fossil deconstruct" command.
    66  <a name="manifest"></a>
    67  <h2>1.0 The Manifest</h2>
    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.
    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.
    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.
    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.
    97  Allowed cards in the manifest are as follows:
    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>
   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.  
   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.
   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:
   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>
   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.
   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.
   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 [./ | 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 [./ | 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 [./ | 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>&nbsp;</td> 560 <td>&nbsp;</td> 561 <td>&nbsp;</td> 562 <td>&nbsp;</td> 563 <td>&nbsp;</td> 564 <td align=center><b>1</b></td> 565 <td>&nbsp;</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>&nbsp;</td> 571 <td>&nbsp;</td> 572 <td>&nbsp;</td> 573 <td>&nbsp;</td> 574 <td>&nbsp;</td> 575 <td>&nbsp;</td> 576 </tr> 577 <tr><td>&nbsp;</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>&nbsp;</td> 582 <td>&nbsp;</td> 583 <td>&nbsp;</td> 584 <td>&nbsp;</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>&nbsp;</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>&nbsp;</td> 601 <td align=center>&nbsp;</td> 602 <td align=center>&nbsp;</td> 603 <td align=center>&nbsp;</td> 604 <td align=center>&nbsp;</td> 605 <td align=center>&nbsp;</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>&nbsp;</td> 612 <td align=center>&nbsp;</td> 613 <td align=center>&nbsp;</td> 614 <td align=center>&nbsp;</td> 615 <td align=center>&nbsp;</td> 616 <td align=center>&nbsp;</td> 617 </tr> 618 <tr> 619 <td><b>J</b> <i>name</i> ?<i>value</i>?</td> 620 <td align=center>&nbsp;</td> 621 <td align=center>&nbsp;</td> 622 <td align=center>&nbsp;</td> 623 <td align=center>&nbsp;</td> 624 <td align=center><b>1+</b></td> 625 <td align=center>&nbsp;</td> 626 <td align=center>&nbsp;</td> 627 </tr> 628 <tr> 629 <td><b>K</b> <i>ticket-uuid</i></td> 630 <td align=center>&nbsp;</td> 631 <td align=center>&nbsp;</td> 632 <td align=center>&nbsp;</td> 633 <td align=center>&nbsp;</td> 634 <td align=center><b>1</b></td> 635 <td align=center>&nbsp;</td> 636 <td align=center>&nbsp;</td> 637 </tr> 638 <tr> 639 <td><b>L</b> <i>wiki-title</i></td> 640 <td align=center>&nbsp;</td> 641 <td align=center>&nbsp;</td> 642 <td align=center>&nbsp;</td> 643 <td align=center><b>1</b></td> 644 <td align=center>&nbsp;</td> 645 <td align=center>&nbsp;</td> 646 <td align=center>&nbsp;</td> 647 </tr> 648 <tr> 649 <td><b>M</b> <i>uuid</i></td> 650 <td align=center>&nbsp;</td> 651 <td align=center><b>1+</b></td> 652 <td align=center>&nbsp;</td> 653 <td align=center>&nbsp;</td> 654 <td align=center>&nbsp;</td> 655 <td align=center>&nbsp;</td> 656 <td align=center>&nbsp;</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>&nbsp;</td> 662 <td align=center>&nbsp;</td> 663 <td align=center><b>0-1</b></td> 664 <td align=center>&nbsp;</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>&nbsp;</td> 672 <td align=center>&nbsp;</td> 673 <td align=center><b>0-1</b></td> 674 <td align=center>&nbsp;</td> 675 <td align=center>&nbsp;</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>&nbsp;</td> 682 <td align=center>&nbsp;</td> 683 <td align=center>&nbsp;</td> 684 <td align=center>&nbsp;</td> 685 <td align=center>&nbsp;</td> 686 <td align=center>&nbsp;</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>&nbsp;</td> 692 <td align=center>&nbsp;</td> 693 <td align=center>&nbsp;</td> 694 <td align=center>&nbsp;</td> 695 <td align=center>&nbsp;</td> 696 <td align=center>&nbsp;</td> 697 <tr><td>&nbsp;</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>&nbsp;</td> 702 <td align=center><b>1+</b></td> 703 <td align=center>&nbsp;</td> 704 <td align=center>&nbsp;</td> 705 <td align=center>&nbsp;</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>&nbsp;</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>&nbsp;</td> 721 <td align=center>&nbsp;</td> 722 <td align=center>&nbsp;</td> 723 <td align=center><b>1</b></td> 724 <td align=center>&nbsp;</td> 725 <td align=center>&nbsp;</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.