Fossil SCM
Updates to to the fileformat.wiki document.
Commit
d9bef53b1a27eeed5dd7b99d1f2b6426e6e9203c
Parent
81a73593d3cf152…
1 file changed
+75
-85
+75
-85
| --- www/fileformat.wiki | ||
| +++ www/fileformat.wiki | ||
| @@ -9,14 +9,19 @@ | ||
| 9 | 9 | searchable, and extensible by people not yet born. |
| 10 | 10 | |
| 11 | 11 | The global state of a fossil repository is an unordered |
| 12 | 12 | set of <i>artifacts</i>. |
| 13 | 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. | |
| 14 | +part of a trouble ticket, a description of a check-in including all | |
| 15 | +the files in that check-in with the check-in comment and so forth. | |
| 16 | +Artifacts are broadly grouped into two types: content artifacts and | |
| 17 | +structural artifacts. Content artifacts are the raw project source-code | |
| 18 | +files that are checked into the repository. Structural artifacts have | |
| 19 | +special formatting rules and are used to show the relationships between | |
| 20 | +other artifacts in the repository. It is possible for an artifact to | |
| 21 | +be both a structure artifact and a content artifact, though this is | |
| 22 | +rare. Artifacts can be text or binary. | |
| 18 | 23 | |
| 19 | 24 | In addition to the global state, |
| 20 | 25 | each fossil repository also contains local state. |
| 21 | 26 | The local state consists of web-page formatting |
| 22 | 27 | preferences, authorized users, ticket display and reporting formats, |
| @@ -27,27 +32,44 @@ | ||
| 27 | 32 | with the global state. |
| 28 | 33 | The local state is not composed of artifacts and is not intended to be enduring. |
| 29 | 34 | This document is concerned with global state only. Local state is only |
| 30 | 35 | mentioned here in order to distinguish it from global state. |
| 31 | 36 | |
| 32 | -Each artifact in the repository is named by a hash of the artifact | |
| 33 | -content. | |
| 34 | -No prefixes or meta information is added to an artifact before | |
| 35 | -its hash is computed. | |
| 36 | - | |
| 37 | -Each repository uses a single hash algorithm to compute artifact names. | |
| 38 | -The default algorithm is currently SHA3-256, though this might change | |
| 39 | -in future releases of Fossil. Historical versions of Fossil used | |
| 40 | -SHA1. The hash algorithm for a repository can be changed. When a hash | |
| 41 | -algorithm change occurs, a set of aliases are set up (using the | |
| 42 | -two-argument version of the M-card on cluster artifacts) so that the | |
| 43 | -older hash values can be mapped into the new hash values for artifacts | |
| 44 | -that were added to the repository before the hash algorithm change. | |
| 45 | - | |
| 46 | -Some artifacts have a particular format which gives them special | |
| 47 | -meaning to Fossil. The special artifacts are calls "structural | |
| 48 | -artifacts". Fossil recognizes the following kinds of structural | |
| 37 | +<a name='#names'></a> | |
| 38 | +<h2>1.0 Artifact Names</h2> | |
| 39 | + | |
| 40 | +Each artifact in the repository is named by a hash of its content. | |
| 41 | +No prefixes, suffixes, or other information is added to an artifact before | |
| 42 | +the hash is computed. The artifact name is just the (lower-case | |
| 43 | +hexadecimal) hash of the raw artifact. | |
| 44 | + | |
| 45 | +Fossil supports multiple hash algorithms including SHA1 and various | |
| 46 | +lengths of SHA3. Because an artifact can be hashed using multiple algorithms, | |
| 47 | +a single artifact can have multiple names. Usually, Fossil knows | |
| 48 | +each artifact by just a single name called the "display name". But it is | |
| 49 | +possible for Fossil to know an artifact by multiple names from different | |
| 50 | +hashes. In that case, Fossil uses the display name for output, but continues | |
| 51 | +to accept the alternative names as command-line arguments or as parameters to | |
| 52 | +webpage URLs. | |
| 53 | + | |
| 54 | +When referring to artifacts in using tty commands or webpage URLs, it is | |
| 55 | +sufficient to specify a unique prefix for the artifact name. If the input | |
| 56 | +prefix is not unique, Fossil will show an error. Within a structural | |
| 57 | +artifact, however, all references to other artifacts must be the complete | |
| 58 | +hash. | |
| 59 | + | |
| 60 | +Prior to Fossil version 2.0, all names were formed from the SHA1 hash of | |
| 61 | +the artifact. The key innovation in Fossil 2.0 was adding support for | |
| 62 | +alternative hash algorithms. | |
| 63 | + | |
| 64 | +<a name="structural"></a> | |
| 65 | +<h2>2.0 Structural Artifacts</h2> | |
| 66 | + | |
| 67 | +A structural artifact is an artifact that has a particular format and | |
| 68 | +that is used to define the relationships between other artifacts in the | |
| 69 | +repository. | |
| 70 | +Fossil recognizes the following kinds of structural | |
| 49 | 71 | artifacts: |
| 50 | 72 | |
| 51 | 73 | <ul> |
| 52 | 74 | <li> [#manifest | Manifests] </li> |
| 53 | 75 | <li> [#cluster | Clusters] </li> |
| @@ -56,11 +78,23 @@ | ||
| 56 | 78 | <li> [#tktchng | Ticket Changes] </li> |
| 57 | 79 | <li> [#attachment | Attachments] </li> |
| 58 | 80 | <li> [#event | TechNotes] </li> |
| 59 | 81 | </ul> |
| 60 | 82 | |
| 61 | -These seven structural artifact types are described in the following sections. | |
| 83 | +These seven structural artifact types are described in subsections below. | |
| 84 | + | |
| 85 | +Structural artifacts are ASCII text. The artifact may be PGP clearsigned. | |
| 86 | +After removal of the PGP clearsign header and suffix (if any) a structural | |
| 87 | +artifact consists of one or more "cards" separated by a single newline | |
| 88 | +(ASCII: 0x0a) character. Each card begins with a single | |
| 89 | +character "card type". Zero or more arguments may follow | |
| 90 | +the card type. All arguments are separated from each other | |
| 91 | +and from the card-type character by a single space | |
| 92 | +character. There is no surplus white space between arguments | |
| 93 | +and no leading or trailing whitespace except for the newline | |
| 94 | +character that acts as the card separator. All cards must be in strict | |
| 95 | +lexicographical order. There may not be any duplicate cards. | |
| 62 | 96 | |
| 63 | 97 | In the current implementation (as of 2017-02-27) the artifacts that |
| 64 | 98 | make up a fossil repository are stored as delta- and zlib-compressed |
| 65 | 99 | blobs in an <a href="http://www.sqlite.org/">SQLite</a> database. This |
| 66 | 100 | is an implementation detail and might change in a future release. For |
| @@ -68,44 +102,21 @@ | ||
| 68 | 102 | not how the artifacts are stored on disk. It is the artifact format that |
| 69 | 103 | is intended to be enduring. The specifics of how artifacts are stored on |
| 70 | 104 | disk, though stable, is not intended to live as long as the |
| 71 | 105 | artifact format. |
| 72 | 106 | |
| 73 | -All of the artifacts can be extracted from a Fossil repository using | |
| 74 | -the "fossil deconstruct" command. | |
| 75 | - | |
| 76 | 107 | <a name="manifest"></a> |
| 77 | -<h2>1.0 The Manifest</h2> | |
| 108 | +<h3>2.1 The Manifest</h3> | |
| 78 | 109 | |
| 79 | -A manifest defines a check-in or version of the project | |
| 80 | -source tree. The manifest contains a list of artifacts for | |
| 110 | +A manifest defines a check-in. | |
| 111 | +A manifest contains a list of artifacts for | |
| 81 | 112 | each file in the project and the corresponding filenames, as |
| 82 | -well as information such as parent check-ins, the name of the | |
| 113 | +well as information such as parent check-ins, the username of the | |
| 83 | 114 | programmer who created the check-in, the date and time when |
| 84 | 115 | the check-in was created, and any check-in comments associated |
| 85 | 116 | with the check-in. |
| 86 | 117 | |
| 87 | -Any artifact in the repository that follows the syntactic rules | |
| 88 | -of a manifest is a manifest. Note that a manifest can | |
| 89 | -be both a real manifest and also a content file, though this | |
| 90 | -is rare. | |
| 91 | - | |
| 92 | -A manifest is a text file. Newline characters | |
| 93 | -(ASCII 0x0a) separate the file into "cards". | |
| 94 | -Each card begins with a single | |
| 95 | -character "card type". Zero or more arguments may follow | |
| 96 | -the card type. All arguments are separated from each other | |
| 97 | -and from the card-type character by a single space | |
| 98 | -character. There is no surplus white space between arguments | |
| 99 | -and no leading or trailing whitespace except for the newline | |
| 100 | -character that acts as the card separator. | |
| 101 | - | |
| 102 | -All cards of the manifest occur in strict sorted lexicographical order. | |
| 103 | -No card may be duplicated. | |
| 104 | -The entire manifest may be PGP clear-signed, but otherwise it | |
| 105 | -may contain no additional text or data beyond what is described here. | |
| 106 | - | |
| 107 | 118 | Allowed cards in the manifest are as follows: |
| 108 | 119 | |
| 109 | 120 | <blockquote> |
| 110 | 121 | <b>B</b> <i>baseline-manifest</i><br> |
| 111 | 122 | <b>C</b> <i>checkin-comment</i><br> |
| @@ -239,41 +250,27 @@ | ||
| 239 | 250 | check-in comment argument to the C-card. |
| 240 | 251 | |
| 241 | 252 | A manifest must have a single Z-card as its last line. The argument |
| 242 | 253 | to the Z-card is a 32-character lowercase hexadecimal MD5 hash |
| 243 | 254 | of all prior lines of the manifest up to and including the newline |
| 244 | -character that immediately precedes the "Z". The Z-card is | |
| 255 | +character that immediately precedes the "Z", excluding any PGP | |
| 256 | +clear-signing prefix. The Z-card is | |
| 245 | 257 | a sanity check to prove that the manifest is well-formed and |
| 246 | 258 | consistent. |
| 247 | 259 | |
| 248 | 260 | A sample manifest from Fossil itself can be seen |
| 249 | 261 | [/artifact/28987096ac | here]. |
| 250 | 262 | |
| 251 | 263 | <a name="cluster"></a> |
| 252 | -<h2>2.0 Clusters</h2> | |
| 264 | +<h3>2.2 Clusters</h3> | |
| 253 | 265 | |
| 254 | 266 | A cluster is an artifact that declares the existence of other artifacts. |
| 255 | 267 | Clusters are used during repository synchronization to help |
| 256 | 268 | reduce network traffic. As such, clusters are an optimization and |
| 257 | 269 | may be removed from a repository without loss or damage to the |
| 258 | 270 | underlying project code. |
| 259 | 271 | |
| 260 | -Clusters follow a syntax that is very similar to manifests. | |
| 261 | -A cluster is a line-oriented text file. Newline characters | |
| 262 | -(ASCII 0x0a) separate the artifact into cards. Each card begins with a single | |
| 263 | -character "card type". Zero or more arguments may follow | |
| 264 | -the card type. All arguments are separated from each other | |
| 265 | -and from the card-type character by a single space | |
| 266 | -character. There is no surplus white space between arguments | |
| 267 | -and no leading or trailing whitespace except for the newline | |
| 268 | -character that acts as the card separator. | |
| 269 | -All cards of a cluster occur in strict sorted lexicographical order. | |
| 270 | -No card may be duplicated. | |
| 271 | -The cluster may not contain additional text or data beyond | |
| 272 | -what is described here. | |
| 273 | -Unlike manifests, clusters are never PGP signed. | |
| 274 | - | |
| 275 | 272 | Allowed cards in the cluster are as follows: |
| 276 | 273 | |
| 277 | 274 | <blockquote> |
| 278 | 275 | <b>M</b> <i>artifact-id</i><br /> |
| 279 | 276 | <b>Z</b> <i>checksum</i> |
| @@ -288,20 +285,14 @@ | ||
| 288 | 285 | |
| 289 | 286 | An example cluster from Fossil can be seen |
| 290 | 287 | [/artifact/d03dbdd73a2a8 | here]. |
| 291 | 288 | |
| 292 | 289 | <a name="ctrl"></a> |
| 293 | -<h2>3.0 Control Artifacts</h2> | |
| 290 | +<h3>2.3 Control Artifacts</h3> | |
| 294 | 291 | |
| 295 | 292 | Control artifacts are used to assign properties to other artifacts |
| 296 | -within the repository. The basic format of a control artifact is | |
| 297 | -the same as a manifest or cluster. A control artifact is a text | |
| 298 | -file divided into cards by newline characters. Each card has a | |
| 299 | -single-character card type followed by arguments. Spaces separate | |
| 300 | -the card type and the arguments. No surplus whitespace is allowed. | |
| 301 | -All cards must occur in strict lexicographical order. | |
| 302 | - | |
| 293 | +within the repository. | |
| 303 | 294 | Allowed cards in a control artifact are as follows: |
| 304 | 295 | |
| 305 | 296 | <blockquote> |
| 306 | 297 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 307 | 298 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br /> |
| @@ -348,16 +339,15 @@ | ||
| 348 | 339 | |
| 349 | 340 | An example control artifacts can be seen [/info/9d302ccda8 | here]. |
| 350 | 341 | |
| 351 | 342 | |
| 352 | 343 | <a name="wikichng"></a> |
| 353 | -<h2>4.0 Wiki Pages</h2> | |
| 344 | +<h3>2.4 Wiki Pages</h3> | |
| 354 | 345 | |
| 355 | -A wiki page is an artifact with a format similar to manifests, | |
| 356 | -clusters, and control artifacts. The artifact is divided into | |
| 357 | -cards by newline characters. The format of each card is as in | |
| 358 | -manifests, clusters, and control artifacts. Wiki artifacts accept | |
| 346 | +A wiki artifact defines a single version of a | |
| 347 | +single wiki page. | |
| 348 | +Wiki artifacts accept | |
| 359 | 349 | the following card types: |
| 360 | 350 | |
| 361 | 351 | <blockquote> |
| 362 | 352 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 363 | 353 | <b>L</b> <i>wiki-title</i><br /> |
| @@ -385,11 +375,11 @@ | ||
| 385 | 375 | |
| 386 | 376 | An example wiki artifact can be seen |
| 387 | 377 | [/artifact?name=7b2f5fd0e0&txt=1 | here]. |
| 388 | 378 | |
| 389 | 379 | <a name="tktchng"></a> |
| 390 | -<h2>5.0 Ticket Changes</h2> | |
| 380 | +<h3>2.5 Ticket Changes</h3> | |
| 391 | 381 | |
| 392 | 382 | A ticket-change artifact represents a change to a trouble ticket. |
| 393 | 383 | The following cards are allowed on a ticket change artifact: |
| 394 | 384 | |
| 395 | 385 | <blockquote> |
| @@ -431,11 +421,11 @@ | ||
| 431 | 421 | |
| 432 | 422 | An example ticket-change artifact can be seen |
| 433 | 423 | [/artifact/91f1ec6af053 | here]. |
| 434 | 424 | |
| 435 | 425 | <a name="attachment"></a> |
| 436 | -<h2>6.0 Attachments</h2> | |
| 426 | +<h3>2.6 Attachments</h3> | |
| 437 | 427 | |
| 438 | 428 | An attachment artifact associates some other artifact that is the |
| 439 | 429 | attachment (the source artifact) with a ticket or wiki page or |
| 440 | 430 | technical note to which |
| 441 | 431 | the attachment is connected (the target artifact). |
| @@ -473,11 +463,11 @@ | ||
| 473 | 463 | The Z card is the usual checksum over the rest of the attachment artifact. |
| 474 | 464 | The Z card is required. |
| 475 | 465 | |
| 476 | 466 | |
| 477 | 467 | <a name="event"></a> |
| 478 | -<h2>7.0 Technical Notes</h2> | |
| 468 | +<h3>2.7 Technical Notes</h3> | |
| 479 | 469 | |
| 480 | 470 | A technical note or "technote" artifact (formerly known as an "event" artifact) |
| 481 | 471 | associates a timeline comment and a page of text |
| 482 | 472 | (similar to a wiki page) with a point in time. Technotes can be used |
| 483 | 473 | to record project milestones, release notes, blog entries, process |
| @@ -542,11 +532,11 @@ | ||
| 542 | 532 | |
| 543 | 533 | The Z card is the required checksum over the rest of the artifact. |
| 544 | 534 | |
| 545 | 535 | |
| 546 | 536 | <a name="summary"></a> |
| 547 | -<h2>8.0 Card Summary</h2> | |
| 537 | +<h2>3.0 Card Summary</h2> | |
| 548 | 538 | |
| 549 | 539 | The following table summarizes the various kinds of cards that appear |
| 550 | 540 | on Fossil artifacts. A blank entry means that combination of card and |
| 551 | 541 | artifact is not legal. A number or range of numbers indicates the number |
| 552 | 542 | of times a card may (or must) appear in the corresponding artifact type. |
| @@ -749,16 +739,16 @@ | ||
| 749 | 739 | </tr> |
| 750 | 740 | </table> |
| 751 | 741 | |
| 752 | 742 | |
| 753 | 743 | <a name="addenda"></a> |
| 754 | -<h2>9.0 Addenda</h2> | |
| 744 | +<h2>4.0 Addenda</h2> | |
| 755 | 745 | |
| 756 | 746 | This section contains additional information which may be useful when |
| 757 | 747 | implementing algorithms described above. |
| 758 | 748 | |
| 759 | -<h3>R Card Hash Calculation</h3> | |
| 749 | +<h3>4.1 R-Card Hash Calculation</h3> | |
| 760 | 750 | |
| 761 | 751 | Given a manifest file named <tt>MF</tt>, the following Bash shell code |
| 762 | 752 | demonstrates how to compute the value of the R card in that manifest. |
| 763 | 753 | This example uses manifest [28987096ac]. Lines starting with <tt>#</tt> are |
| 764 | 754 | shell input and other lines are output. This demonstration assumes that the |
| 765 | 755 |
| --- www/fileformat.wiki | |
| +++ www/fileformat.wiki | |
| @@ -9,14 +9,19 @@ | |
| 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, |
| @@ -27,27 +32,44 @@ | |
| 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 a hash of the artifact |
| 33 | content. |
| 34 | No prefixes or meta information is added to an artifact before |
| 35 | its hash is computed. |
| 36 | |
| 37 | Each repository uses a single hash algorithm to compute artifact names. |
| 38 | The default algorithm is currently SHA3-256, though this might change |
| 39 | in future releases of Fossil. Historical versions of Fossil used |
| 40 | SHA1. The hash algorithm for a repository can be changed. When a hash |
| 41 | algorithm change occurs, a set of aliases are set up (using the |
| 42 | two-argument version of the M-card on cluster artifacts) so that the |
| 43 | older hash values can be mapped into the new hash values for artifacts |
| 44 | that were added to the repository before the hash algorithm change. |
| 45 | |
| 46 | Some artifacts have a particular format which gives them special |
| 47 | meaning to Fossil. The special artifacts are calls "structural |
| 48 | artifacts". Fossil recognizes the following kinds of structural |
| 49 | artifacts: |
| 50 | |
| 51 | <ul> |
| 52 | <li> [#manifest | Manifests] </li> |
| 53 | <li> [#cluster | Clusters] </li> |
| @@ -56,11 +78,23 @@ | |
| 56 | <li> [#tktchng | Ticket Changes] </li> |
| 57 | <li> [#attachment | Attachments] </li> |
| 58 | <li> [#event | TechNotes] </li> |
| 59 | </ul> |
| 60 | |
| 61 | These seven structural artifact types are described in the following sections. |
| 62 | |
| 63 | In the current implementation (as of 2017-02-27) the artifacts that |
| 64 | make up a fossil repository are stored as delta- and zlib-compressed |
| 65 | blobs in an <a href="http://www.sqlite.org/">SQLite</a> database. This |
| 66 | is an implementation detail and might change in a future release. For |
| @@ -68,44 +102,21 @@ | |
| 68 | not how the artifacts are stored on disk. It is the artifact format that |
| 69 | is intended to be enduring. The specifics of how artifacts are stored on |
| 70 | disk, though stable, is not intended to live as long as the |
| 71 | artifact format. |
| 72 | |
| 73 | All of the artifacts can be extracted from a Fossil repository using |
| 74 | the "fossil deconstruct" command. |
| 75 | |
| 76 | <a name="manifest"></a> |
| 77 | <h2>1.0 The Manifest</h2> |
| 78 | |
| 79 | A manifest defines a check-in or version of the project |
| 80 | source tree. The manifest contains a list of artifacts for |
| 81 | each file in the project and the corresponding filenames, as |
| 82 | well as information such as parent check-ins, the name of the |
| 83 | programmer who created the check-in, the date and time when |
| 84 | the check-in was created, and any check-in comments associated |
| 85 | with the check-in. |
| 86 | |
| 87 | Any artifact in the repository that follows the syntactic rules |
| 88 | of a manifest is a manifest. Note that a manifest can |
| 89 | be both a real manifest and also a content file, though this |
| 90 | is rare. |
| 91 | |
| 92 | A manifest is a text file. Newline characters |
| 93 | (ASCII 0x0a) separate the file into "cards". |
| 94 | Each card begins with a single |
| 95 | character "card type". Zero or more arguments may follow |
| 96 | the card type. All arguments are separated from each other |
| 97 | and from the card-type character by a single space |
| 98 | character. There is no surplus white space between arguments |
| 99 | and no leading or trailing whitespace except for the newline |
| 100 | character that acts as the card separator. |
| 101 | |
| 102 | All cards of the manifest occur in strict sorted lexicographical order. |
| 103 | No card may be duplicated. |
| 104 | The entire manifest may be PGP clear-signed, but otherwise it |
| 105 | may contain no additional text or data beyond what is described here. |
| 106 | |
| 107 | Allowed cards in the manifest are as follows: |
| 108 | |
| 109 | <blockquote> |
| 110 | <b>B</b> <i>baseline-manifest</i><br> |
| 111 | <b>C</b> <i>checkin-comment</i><br> |
| @@ -239,41 +250,27 @@ | |
| 239 | check-in comment argument to the C-card. |
| 240 | |
| 241 | A manifest must have a single Z-card as its last line. The argument |
| 242 | to the Z-card is a 32-character lowercase hexadecimal MD5 hash |
| 243 | of all prior lines of the manifest up to and including the newline |
| 244 | character that immediately precedes the "Z". The Z-card is |
| 245 | a sanity check to prove that the manifest is well-formed and |
| 246 | consistent. |
| 247 | |
| 248 | A sample manifest from Fossil itself can be seen |
| 249 | [/artifact/28987096ac | here]. |
| 250 | |
| 251 | <a name="cluster"></a> |
| 252 | <h2>2.0 Clusters</h2> |
| 253 | |
| 254 | A cluster is an artifact that declares the existence of other artifacts. |
| 255 | Clusters are used during repository synchronization to help |
| 256 | reduce network traffic. As such, clusters are an optimization and |
| 257 | may be removed from a repository without loss or damage to the |
| 258 | underlying project code. |
| 259 | |
| 260 | Clusters follow a syntax that is very similar to manifests. |
| 261 | A cluster is a line-oriented text file. Newline characters |
| 262 | (ASCII 0x0a) separate the artifact into cards. Each card begins with a single |
| 263 | character "card type". Zero or more arguments may follow |
| 264 | the card type. All arguments are separated from each other |
| 265 | and from the card-type character by a single space |
| 266 | character. There is no surplus white space between arguments |
| 267 | and no leading or trailing whitespace except for the newline |
| 268 | character that acts as the card separator. |
| 269 | All cards of a cluster occur in strict sorted lexicographical order. |
| 270 | No card may be duplicated. |
| 271 | The cluster may not contain additional text or data beyond |
| 272 | what is described here. |
| 273 | Unlike manifests, clusters are never PGP signed. |
| 274 | |
| 275 | Allowed cards in the cluster are as follows: |
| 276 | |
| 277 | <blockquote> |
| 278 | <b>M</b> <i>artifact-id</i><br /> |
| 279 | <b>Z</b> <i>checksum</i> |
| @@ -288,20 +285,14 @@ | |
| 288 | |
| 289 | An example cluster from Fossil can be seen |
| 290 | [/artifact/d03dbdd73a2a8 | here]. |
| 291 | |
| 292 | <a name="ctrl"></a> |
| 293 | <h2>3.0 Control Artifacts</h2> |
| 294 | |
| 295 | Control artifacts are used to assign properties to other artifacts |
| 296 | within the repository. The basic format of a control artifact is |
| 297 | the same as a manifest or cluster. A control artifact is a text |
| 298 | file divided into cards by newline characters. Each card has a |
| 299 | single-character card type followed by arguments. Spaces separate |
| 300 | the card type and the arguments. No surplus whitespace is allowed. |
| 301 | All cards must occur in strict lexicographical order. |
| 302 | |
| 303 | Allowed cards in a control artifact are as follows: |
| 304 | |
| 305 | <blockquote> |
| 306 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 307 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br /> |
| @@ -348,16 +339,15 @@ | |
| 348 | |
| 349 | An example control artifacts can be seen [/info/9d302ccda8 | here]. |
| 350 | |
| 351 | |
| 352 | <a name="wikichng"></a> |
| 353 | <h2>4.0 Wiki Pages</h2> |
| 354 | |
| 355 | A wiki page is an artifact with a format similar to manifests, |
| 356 | clusters, and control artifacts. The artifact is divided into |
| 357 | cards by newline characters. The format of each card is as in |
| 358 | manifests, clusters, and control artifacts. Wiki artifacts accept |
| 359 | the following card types: |
| 360 | |
| 361 | <blockquote> |
| 362 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 363 | <b>L</b> <i>wiki-title</i><br /> |
| @@ -385,11 +375,11 @@ | |
| 385 | |
| 386 | An example wiki artifact can be seen |
| 387 | [/artifact?name=7b2f5fd0e0&txt=1 | here]. |
| 388 | |
| 389 | <a name="tktchng"></a> |
| 390 | <h2>5.0 Ticket Changes</h2> |
| 391 | |
| 392 | A ticket-change artifact represents a change to a trouble ticket. |
| 393 | The following cards are allowed on a ticket change artifact: |
| 394 | |
| 395 | <blockquote> |
| @@ -431,11 +421,11 @@ | |
| 431 | |
| 432 | An example ticket-change artifact can be seen |
| 433 | [/artifact/91f1ec6af053 | here]. |
| 434 | |
| 435 | <a name="attachment"></a> |
| 436 | <h2>6.0 Attachments</h2> |
| 437 | |
| 438 | An attachment artifact associates some other artifact that is the |
| 439 | attachment (the source artifact) with a ticket or wiki page or |
| 440 | technical note to which |
| 441 | the attachment is connected (the target artifact). |
| @@ -473,11 +463,11 @@ | |
| 473 | The Z card is the usual checksum over the rest of the attachment artifact. |
| 474 | The Z card is required. |
| 475 | |
| 476 | |
| 477 | <a name="event"></a> |
| 478 | <h2>7.0 Technical Notes</h2> |
| 479 | |
| 480 | A technical note or "technote" artifact (formerly known as an "event" artifact) |
| 481 | associates a timeline comment and a page of text |
| 482 | (similar to a wiki page) with a point in time. Technotes can be used |
| 483 | to record project milestones, release notes, blog entries, process |
| @@ -542,11 +532,11 @@ | |
| 542 | |
| 543 | The Z card is the required checksum over the rest of the artifact. |
| 544 | |
| 545 | |
| 546 | <a name="summary"></a> |
| 547 | <h2>8.0 Card Summary</h2> |
| 548 | |
| 549 | The following table summarizes the various kinds of cards that appear |
| 550 | on Fossil artifacts. A blank entry means that combination of card and |
| 551 | artifact is not legal. A number or range of numbers indicates the number |
| 552 | of times a card may (or must) appear in the corresponding artifact type. |
| @@ -749,16 +739,16 @@ | |
| 749 | </tr> |
| 750 | </table> |
| 751 | |
| 752 | |
| 753 | <a name="addenda"></a> |
| 754 | <h2>9.0 Addenda</h2> |
| 755 | |
| 756 | This section contains additional information which may be useful when |
| 757 | implementing algorithms described above. |
| 758 | |
| 759 | <h3>R Card Hash Calculation</h3> |
| 760 | |
| 761 | Given a manifest file named <tt>MF</tt>, the following Bash shell code |
| 762 | demonstrates how to compute the value of the R card in that manifest. |
| 763 | This example uses manifest [28987096ac]. Lines starting with <tt>#</tt> are |
| 764 | shell input and other lines are output. This demonstration assumes that the |
| 765 |
| --- www/fileformat.wiki | |
| +++ www/fileformat.wiki | |
| @@ -9,14 +9,19 @@ | |
| 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, a description of a check-in including all |
| 15 | the files in that check-in with the check-in comment and so forth. |
| 16 | Artifacts are broadly grouped into two types: content artifacts and |
| 17 | structural artifacts. Content artifacts are the raw project source-code |
| 18 | files that are checked into the repository. Structural artifacts have |
| 19 | special formatting rules and are used to show the relationships between |
| 20 | other artifacts in the repository. It is possible for an artifact to |
| 21 | be both a structure artifact and a content artifact, though this is |
| 22 | rare. Artifacts can be text or binary. |
| 23 | |
| 24 | In addition to the global state, |
| 25 | each fossil repository also contains local state. |
| 26 | The local state consists of web-page formatting |
| 27 | preferences, authorized users, ticket display and reporting formats, |
| @@ -27,27 +32,44 @@ | |
| 32 | with the global state. |
| 33 | The local state is not composed of artifacts and is not intended to be enduring. |
| 34 | This document is concerned with global state only. Local state is only |
| 35 | mentioned here in order to distinguish it from global state. |
| 36 | |
| 37 | <a name='#names'></a> |
| 38 | <h2>1.0 Artifact Names</h2> |
| 39 | |
| 40 | Each artifact in the repository is named by a hash of its content. |
| 41 | No prefixes, suffixes, or other information is added to an artifact before |
| 42 | the hash is computed. The artifact name is just the (lower-case |
| 43 | hexadecimal) hash of the raw artifact. |
| 44 | |
| 45 | Fossil supports multiple hash algorithms including SHA1 and various |
| 46 | lengths of SHA3. Because an artifact can be hashed using multiple algorithms, |
| 47 | a single artifact can have multiple names. Usually, Fossil knows |
| 48 | each artifact by just a single name called the "display name". But it is |
| 49 | possible for Fossil to know an artifact by multiple names from different |
| 50 | hashes. In that case, Fossil uses the display name for output, but continues |
| 51 | to accept the alternative names as command-line arguments or as parameters to |
| 52 | webpage URLs. |
| 53 | |
| 54 | When referring to artifacts in using tty commands or webpage URLs, it is |
| 55 | sufficient to specify a unique prefix for the artifact name. If the input |
| 56 | prefix is not unique, Fossil will show an error. Within a structural |
| 57 | artifact, however, all references to other artifacts must be the complete |
| 58 | hash. |
| 59 | |
| 60 | Prior to Fossil version 2.0, all names were formed from the SHA1 hash of |
| 61 | the artifact. The key innovation in Fossil 2.0 was adding support for |
| 62 | alternative hash algorithms. |
| 63 | |
| 64 | <a name="structural"></a> |
| 65 | <h2>2.0 Structural Artifacts</h2> |
| 66 | |
| 67 | A structural artifact is an artifact that has a particular format and |
| 68 | that is used to define the relationships between other artifacts in the |
| 69 | repository. |
| 70 | Fossil recognizes the following kinds of structural |
| 71 | artifacts: |
| 72 | |
| 73 | <ul> |
| 74 | <li> [#manifest | Manifests] </li> |
| 75 | <li> [#cluster | Clusters] </li> |
| @@ -56,11 +78,23 @@ | |
| 78 | <li> [#tktchng | Ticket Changes] </li> |
| 79 | <li> [#attachment | Attachments] </li> |
| 80 | <li> [#event | TechNotes] </li> |
| 81 | </ul> |
| 82 | |
| 83 | These seven structural artifact types are described in subsections below. |
| 84 | |
| 85 | Structural artifacts are ASCII text. The artifact may be PGP clearsigned. |
| 86 | After removal of the PGP clearsign header and suffix (if any) a structural |
| 87 | artifact consists of one or more "cards" separated by a single newline |
| 88 | (ASCII: 0x0a) character. Each card begins with a single |
| 89 | character "card type". Zero or more arguments may follow |
| 90 | the card type. All arguments are separated from each other |
| 91 | and from the card-type character by a single space |
| 92 | character. There is no surplus white space between arguments |
| 93 | and no leading or trailing whitespace except for the newline |
| 94 | character that acts as the card separator. All cards must be in strict |
| 95 | lexicographical order. There may not be any duplicate cards. |
| 96 | |
| 97 | In the current implementation (as of 2017-02-27) the artifacts that |
| 98 | make up a fossil repository are stored as delta- and zlib-compressed |
| 99 | blobs in an <a href="http://www.sqlite.org/">SQLite</a> database. This |
| 100 | is an implementation detail and might change in a future release. For |
| @@ -68,44 +102,21 @@ | |
| 102 | not how the artifacts are stored on disk. It is the artifact format that |
| 103 | is intended to be enduring. The specifics of how artifacts are stored on |
| 104 | disk, though stable, is not intended to live as long as the |
| 105 | artifact format. |
| 106 | |
| 107 | <a name="manifest"></a> |
| 108 | <h3>2.1 The Manifest</h3> |
| 109 | |
| 110 | A manifest defines a check-in. |
| 111 | A manifest contains a list of artifacts for |
| 112 | each file in the project and the corresponding filenames, as |
| 113 | well as information such as parent check-ins, the username of the |
| 114 | programmer who created the check-in, the date and time when |
| 115 | the check-in was created, and any check-in comments associated |
| 116 | with the check-in. |
| 117 | |
| 118 | Allowed cards in the manifest are as follows: |
| 119 | |
| 120 | <blockquote> |
| 121 | <b>B</b> <i>baseline-manifest</i><br> |
| 122 | <b>C</b> <i>checkin-comment</i><br> |
| @@ -239,41 +250,27 @@ | |
| 250 | check-in comment argument to the C-card. |
| 251 | |
| 252 | A manifest must have a single Z-card as its last line. The argument |
| 253 | to the Z-card is a 32-character lowercase hexadecimal MD5 hash |
| 254 | of all prior lines of the manifest up to and including the newline |
| 255 | character that immediately precedes the "Z", excluding any PGP |
| 256 | clear-signing prefix. The Z-card is |
| 257 | a sanity check to prove that the manifest is well-formed and |
| 258 | consistent. |
| 259 | |
| 260 | A sample manifest from Fossil itself can be seen |
| 261 | [/artifact/28987096ac | here]. |
| 262 | |
| 263 | <a name="cluster"></a> |
| 264 | <h3>2.2 Clusters</h3> |
| 265 | |
| 266 | A cluster is an artifact that declares the existence of other artifacts. |
| 267 | Clusters are used during repository synchronization to help |
| 268 | reduce network traffic. As such, clusters are an optimization and |
| 269 | may be removed from a repository without loss or damage to the |
| 270 | underlying project code. |
| 271 | |
| 272 | Allowed cards in the cluster are as follows: |
| 273 | |
| 274 | <blockquote> |
| 275 | <b>M</b> <i>artifact-id</i><br /> |
| 276 | <b>Z</b> <i>checksum</i> |
| @@ -288,20 +285,14 @@ | |
| 285 | |
| 286 | An example cluster from Fossil can be seen |
| 287 | [/artifact/d03dbdd73a2a8 | here]. |
| 288 | |
| 289 | <a name="ctrl"></a> |
| 290 | <h3>2.3 Control Artifacts</h3> |
| 291 | |
| 292 | Control artifacts are used to assign properties to other artifacts |
| 293 | within the repository. |
| 294 | Allowed cards in a control artifact are as follows: |
| 295 | |
| 296 | <blockquote> |
| 297 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 298 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br /> |
| @@ -348,16 +339,15 @@ | |
| 339 | |
| 340 | An example control artifacts can be seen [/info/9d302ccda8 | here]. |
| 341 | |
| 342 | |
| 343 | <a name="wikichng"></a> |
| 344 | <h3>2.4 Wiki Pages</h3> |
| 345 | |
| 346 | A wiki artifact defines a single version of a |
| 347 | single wiki page. |
| 348 | Wiki artifacts accept |
| 349 | the following card types: |
| 350 | |
| 351 | <blockquote> |
| 352 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 353 | <b>L</b> <i>wiki-title</i><br /> |
| @@ -385,11 +375,11 @@ | |
| 375 | |
| 376 | An example wiki artifact can be seen |
| 377 | [/artifact?name=7b2f5fd0e0&txt=1 | here]. |
| 378 | |
| 379 | <a name="tktchng"></a> |
| 380 | <h3>2.5 Ticket Changes</h3> |
| 381 | |
| 382 | A ticket-change artifact represents a change to a trouble ticket. |
| 383 | The following cards are allowed on a ticket change artifact: |
| 384 | |
| 385 | <blockquote> |
| @@ -431,11 +421,11 @@ | |
| 421 | |
| 422 | An example ticket-change artifact can be seen |
| 423 | [/artifact/91f1ec6af053 | here]. |
| 424 | |
| 425 | <a name="attachment"></a> |
| 426 | <h3>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). |
| @@ -473,11 +463,11 @@ | |
| 463 | The Z card is the usual checksum over the rest of the attachment artifact. |
| 464 | The Z card is required. |
| 465 | |
| 466 | |
| 467 | <a name="event"></a> |
| 468 | <h3>2.7 Technical Notes</h3> |
| 469 | |
| 470 | A technical note or "technote" artifact (formerly known as an "event" artifact) |
| 471 | associates a timeline comment and a page of text |
| 472 | (similar to a wiki page) with a point in time. Technotes can be used |
| 473 | to record project milestones, release notes, blog entries, process |
| @@ -542,11 +532,11 @@ | |
| 532 | |
| 533 | The Z card is the required checksum over the rest of the artifact. |
| 534 | |
| 535 | |
| 536 | <a name="summary"></a> |
| 537 | <h2>3.0 Card Summary</h2> |
| 538 | |
| 539 | The following table summarizes the various kinds of cards that appear |
| 540 | on Fossil artifacts. A blank entry means that combination of card and |
| 541 | artifact is not legal. A number or range of numbers indicates the number |
| 542 | of times a card may (or must) appear in the corresponding artifact type. |
| @@ -749,16 +739,16 @@ | |
| 739 | </tr> |
| 740 | </table> |
| 741 | |
| 742 | |
| 743 | <a name="addenda"></a> |
| 744 | <h2>4.0 Addenda</h2> |
| 745 | |
| 746 | This section contains additional information which may be useful when |
| 747 | implementing algorithms described above. |
| 748 | |
| 749 | <h3>4.1 R-Card Hash Calculation</h3> |
| 750 | |
| 751 | Given a manifest file named <tt>MF</tt>, the following Bash shell code |
| 752 | demonstrates how to compute the value of the R card in that manifest. |
| 753 | This example uses manifest [28987096ac]. Lines starting with <tt>#</tt> are |
| 754 | shell input and other lines are output. This demonstration assumes that the |
| 755 |