dbda8d6ce9 2007-07-21 drh: <html> dbda8d6ce9 2007-07-21 drh: <head> b807acf62e 2007-07-24 drh: <title>Fossil File Format</title> dbda8d6ce9 2007-07-21 drh: </head> dbda8d6ce9 2007-07-21 drh: <body bgcolor="white"> 469002ccdf 2007-09-12 aku: <p>[ <a href="index.html">Index</a> ]</p> 469002ccdf 2007-09-12 aku: <hr> dbda8d6ce9 2007-07-21 drh: <h1 align="center"> dbda8d6ce9 2007-07-21 drh: Fossil File Formats dbda8d6ce9 2007-07-21 drh: </h1> dbda8d6ce9 2007-07-21 drh: dbda8d6ce9 2007-07-21 drh: <p> dbda8d6ce9 2007-07-21 drh: The global state of a fossil repository is determined by an unordered 0cd202a86e 2007-08-23 drh: set of files. Some files are used to represent wiki pages, trouble tickets, b807acf62e 2007-07-24 drh: and the special "manifest" file has a specific and well-defined format. 0cd202a86e 2007-08-23 drh: Other files are just data. Files can be text or binary. b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> b807acf62e 2007-07-24 drh: Each file in the repository is named by its SHA1 hash. 0cd202a86e 2007-08-23 drh: No prefixes or meta information is added to a file before 0cd202a86e 2007-08-23 drh: its hash is computed. The name of a file in the repository 0cd202a86e 2007-08-23 drh: is exactly the same SHA1 hash that is computed by sha1sum 0cd202a86e 2007-08-23 drh: on the file as it exists in your source tree.</p> 0cd202a86e 2007-08-23 drh: 0cd202a86e 2007-08-23 drh: <p> b807acf62e 2007-07-24 drh: Some files have a particular format which qualifies them b807acf62e 2007-07-24 drh: as "manifests". A manifest assigns filenames to a subset b807acf62e 2007-07-24 drh: of the files in the repository, in order to provide a b807acf62e 2007-07-24 drh: snapshot of the state of the project at a point in time. b807acf62e 2007-07-24 drh: Each manifest file corresponds to a version or baseline b807acf62e 2007-07-24 drh: of the project. b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <h2>1.0 The Manifest File</h2> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> b807acf62e 2007-07-24 drh: Any file in the repository that follows the syntactic rules b807acf62e 2007-07-24 drh: of a manifest is a manifest. Note that a manifest can b807acf62e 2007-07-24 drh: be both a real manifest and also a content file, though this b807acf62e 2007-07-24 drh: is rare. b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> b807acf62e 2007-07-24 drh: A manifest is a line-oriented text file. Newline characters b807acf62e 2007-07-24 drh: (ASCII 0x0a) separate lines. Each line begins with a single b807acf62e 2007-07-24 drh: character "line type". Zero or more arguments may follow b807acf62e 2007-07-24 drh: the line type. All arguments are separated from each other b807acf62e 2007-07-24 drh: and from the line-type character by a single space b807acf62e 2007-07-24 drh: character. There is no surplus white space between arguments b807acf62e 2007-07-24 drh: and no leading or trailing whitespace except for the newline b807acf62e 2007-07-24 drh: character that acts as the line separator. b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> 63564202fd 2007-08-28 aku: All lines of the manifest occur in strict sorted lexicographical order. b807acf62e 2007-07-24 drh: No line may be duplicated. b807acf62e 2007-07-24 drh: The entire manifest file may be PGP clear-signed, but otherwise it b807acf62e 2007-07-24 drh: may contain no additional text or data beyond what is described here. b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> b807acf62e 2007-07-24 drh: Allowed lines in the manifest are as follows: b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <blockquote> b807acf62e 2007-07-24 drh: <b>C</b> <i>checkin-comment</i><br> b807acf62e 2007-07-24 drh: <b>D</b> <i>time-and-date-stamp</i><br> b807acf62e 2007-07-24 drh: <b>F</b> <i>filename</i> <i>SHA1-hash</i><br> b807acf62e 2007-07-24 drh: <b>P</b> <i>SHA1-hash</i>+<br> b807acf62e 2007-07-24 drh: <b>R</b> <i>repository-checksum</i><br> b807acf62e 2007-07-24 drh: <b>U</b> <i>user-login</i><br> b807acf62e 2007-07-24 drh: <b>Z</b> <i>manifest-checksum</i> b807acf62e 2007-07-24 drh: </blockquote> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> b807acf62e 2007-07-24 drh: A manifest must have exactly one C-line. The sole argument to b807acf62e 2007-07-24 drh: the C-line is a check-in comment that describes the baseline that b807acf62e 2007-07-24 drh: the manifest defines. The check-in comment is text. The following b807acf62e 2007-07-24 drh: escape sequences are applied to the text: b807acf62e 2007-07-24 drh: A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A b807acf62e 2007-07-24 drh: newline (ASCII 0x0a) is "\n" (ASCII 0x6C, x6E). A backslash b807acf62e 2007-07-24 drh: (ASCII 0x5C) is represented as two backslashes "\\". Apart from b807acf62e 2007-07-24 drh: space and newline, no other whitespace characters are allowed in b807acf62e 2007-07-24 drh: the check-in comment. Nor are any unprintable characters allowed b807acf62e 2007-07-24 drh: in the comment. dbda8d6ce9 2007-07-21 drh: </p> dbda8d6ce9 2007-07-21 drh: dbda8d6ce9 2007-07-21 drh: <p> b807acf62e 2007-07-24 drh: A manifest must have exactly one D-line. The sole argument to b807acf62e 2007-07-24 drh: the D-line is a date-time stamp in the ISO8601 format. The b807acf62e 2007-07-24 drh: date and time should be in coordinated universal time (UTC). b807acf62e 2007-07-24 drh: The format is: dbda8d6ce9 2007-07-21 drh: </p> dbda8d6ce9 2007-07-21 drh: dbda8d6ce9 2007-07-21 drh: <blockquote> b807acf62e 2007-07-24 drh: <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> dbda8d6ce9 2007-07-21 drh: </blockquote> dbda8d6ce9 2007-07-21 drh: dbda8d6ce9 2007-07-21 drh: <p> b807acf62e 2007-07-24 drh: A manifest has zero or more F-lines. Each F-line defines a file b807acf62e 2007-07-24 drh: (other than the manifest itself) which is part of the baseline that b807acf62e 2007-07-24 drh: the manifest defines. There are two arguments. The first argment b807acf62e 2007-07-24 drh: is the pathname of the file in the baseline relative to the root b807acf62e 2007-07-24 drh: of the project file hierarchy. No ".." or "." directories are allowed b807acf62e 2007-07-24 drh: within the filename. Space characters are escaped as in C-line b807acf62e 2007-07-24 drh: comment text. Backslash characters and newlines are not allowed b807acf62e 2007-07-24 drh: within filenames. The directory separator character is a forward b807acf62e 2007-07-24 drh: slash (ASCII 0x2F). The second argument to the F-line is the b807acf62e 2007-07-24 drh: full 40-character hexadecimal SHA1 hash of the file content. b807acf62e 2007-07-24 drh: Upper-case letters ABCDEF are used for the higher digits of the b807acf62e 2007-07-24 drh: hexadecimal. b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> b807acf62e 2007-07-24 drh: A manifest has zero or one P-lines. Most manifests have one P-line. b807acf62e 2007-07-24 drh: The P-line has a varying number of arguments that b807acf62e 2007-07-24 drh: defines other manifests from which the current manifest 01e7596a98 2007-07-24 drh: is derived. Each argument is an 40-character lowercase b807acf62e 2007-07-24 drh: hexadecimal SHA1 of the predecessor manifest. All arguments b807acf62e 2007-07-24 drh: to the P-line must be unique to that line. b807acf62e 2007-07-24 drh: The first predecessor is the manifests direct ancestor. b807acf62e 2007-07-24 drh: Other arguments define manifests with which the first was b807acf62e 2007-07-24 drh: merged to yield the current manifest. Most manifests have b807acf62e 2007-07-24 drh: a P-line with a single argument. The first manifest in the b807acf62e 2007-07-24 drh: project has no ancestors and thus has no P-line. b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> b807acf62e 2007-07-24 drh: A manifest may optionally have a single R-line. The R-line has b807acf62e 2007-07-24 drh: a single argument which is the MD5 checksum of all files in b807acf62e 2007-07-24 drh: the baseline except the manifest itself. The checksum is expressed 01e7596a98 2007-07-24 drh: as 32-characters of lowercase hexadecimal. The checksum is b807acf62e 2007-07-24 drh: computed as follows: For each file in the baseline (except for 63564202fd 2007-08-28 aku: the manifest itself) in strict sorted lexicographical order, b807acf62e 2007-07-24 drh: take the pathname of the file relative to the root of the b807acf62e 2007-07-24 drh: repository, append a single space (ASCII 0x20), the b807acf62e 2007-07-24 drh: size of the file in ASCII decimal, a single newline b807acf62e 2007-07-24 drh: character (ASCII 0x0A), and the complete text of the file. b807acf62e 2007-07-24 drh: Compute the MD5 checksum of the the result. b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> b807acf62e 2007-07-24 drh: Each manifest has a single U-line. The argument to the U-line is b807acf62e 2007-07-24 drh: the login of the user who created the manifest. The login name b807acf62e 2007-07-24 drh: is encoded using the same character escapes as is used for the b807acf62e 2007-07-24 drh: check-in comment argument to the C-line. b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> b807acf62e 2007-07-24 drh: A manifest has an option Z-line as its last line. The argument 01e7596a98 2007-07-24 drh: to the Z-line is a 32-character lowercase hexadecimal MD5 hash b807acf62e 2007-07-24 drh: of all prior lines of the manifest up to and including the newline b807acf62e 2007-07-24 drh: character that immediately preceeds the "Z". The Z-line is just b807acf62e 2007-07-24 drh: a sanity check to prove that the manifest is well-formed and b807acf62e 2007-07-24 drh: consistent. b807acf62e 2007-07-24 drh: </p> b807acf62e 2007-07-24 drh: 2bc0e2c565 2007-09-21 drh: <h2>2.0 Clusters</h2> 2bc0e2c565 2007-09-21 drh: 2bc0e2c565 2007-09-21 drh: <p> 2bc0e2c565 2007-09-21 drh: A cluster is a file that states the existance of other files. 2bc0e2c565 2007-09-21 drh: Clusters are used during repository synchronization to help 2bc0e2c565 2007-09-21 drh: reduce network traffic. 2bc0e2c565 2007-09-21 drh: </p> 2bc0e2c565 2007-09-21 drh: 2bc0e2c565 2007-09-21 drh: <p> 2bc0e2c565 2007-09-21 drh: Clusters follow a syntax that is very similar to manifests. 2bc0e2c565 2007-09-21 drh: A Cluster is a line-oriented text file. Newline characters 2bc0e2c565 2007-09-21 drh: (ASCII 0x0a) separate lines. Each line begins with a single 2bc0e2c565 2007-09-21 drh: character "line type". Zero or more arguments may follow 2bc0e2c565 2007-09-21 drh: the line type. All arguments are separated from each other 2bc0e2c565 2007-09-21 drh: and from the line-type character by a single space 2bc0e2c565 2007-09-21 drh: character. There is no surplus white space between arguments 2bc0e2c565 2007-09-21 drh: and no leading or trailing whitespace except for the newline 2bc0e2c565 2007-09-21 drh: character that acts as the line separator. 2bc0e2c565 2007-09-21 drh: All lines of a cluter occur in strict sorted lexicographical order. 2bc0e2c565 2007-09-21 drh: No line may be duplicated. 2bc0e2c565 2007-09-21 drh: The cluster may not contain additional text or data beyond 2bc0e2c565 2007-09-21 drh: what is described here. dbda8d6ce9 2007-07-21 drh: </p> dbda8d6ce9 2007-07-21 drh: dbda8d6ce9 2007-07-21 drh: <p> 2bc0e2c565 2007-09-21 drh: Allowed lines in the cluster are as follows: dbda8d6ce9 2007-07-21 drh: </p> dbda8d6ce9 2007-07-21 drh: dbda8d6ce9 2007-07-21 drh: <blockquote> 2bc0e2c565 2007-09-21 drh: <b>M</b> <i>uuid</i> 2bc0e2c565 2007-09-21 drh: <b>Z</b> <i>manifest-checksum</i> dbda8d6ce9 2007-07-21 drh: </blockquote> dbda8d6ce9 2007-07-21 drh: dbda8d6ce9 2007-07-21 drh: <p> 2bc0e2c565 2007-09-21 drh: A cluster contains one or more "M" lines followed by a single "Z" 2bc0e2c565 2007-09-21 drh: line. Each M line has a single argument which is the UUID of 2bc0e2c565 2007-09-21 drh: another record in the repository. The Z line work exactly like 2bc0e2c565 2007-09-21 drh: the Z line of a manifest. The argument to the Z line is the 2bc0e2c565 2007-09-21 drh: lower-case hexadecimal representation of the MD5 checksum of all 2bc0e2c565 2007-09-21 drh: prior lines in the cluster. 2bc0e2c565 2007-09-21 drh: </p> 2bc0e2c565 2007-09-21 drh: 2bc0e2c565 2007-09-21 drh: 2bc0e2c565 2007-09-21 drh: <h2>3.0 Trouble Tickets</h2> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <p> b807acf62e 2007-07-24 drh: Each trouble ticket is a file in the repository and appears in b807acf62e 2007-07-24 drh: a manifest for every baseline in which the ticket exists. b807acf62e 2007-07-24 drh: Trouble tickets occur in a specific subdirectory of the file b807acf62e 2007-07-24 drh: heirarchy. The name of the subdirectory that contains tickets b807acf62e 2007-07-24 drh: is part of the local state of each repository. The filename b807acf62e 2007-07-24 drh: of each trouble ticket has a ".tkt" suffix. The trouble ticket b807acf62e 2007-07-24 drh: has a particular file format defined below. dbda8d6ce9 2007-07-21 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <i>To be continued...</i> b807acf62e 2007-07-24 drh: 2bc0e2c565 2007-09-21 drh: <h2>4.0 Wiki Pages</h2> dbda8d6ce9 2007-07-21 drh: dbda8d6ce9 2007-07-21 drh: <p> b807acf62e 2007-07-24 drh: Each wiki is a file in the repository and appears in b807acf62e 2007-07-24 drh: a manifest for every baseline in which that wiki page exists. b807acf62e 2007-07-24 drh: Wiki pages occur in a specific subdirectory of the file b807acf62e 2007-07-24 drh: heirarchy. The name of the subdirectory that contains wiki pages b807acf62e 2007-07-24 drh: is part of the local state of each repository. The filename b807acf62e 2007-07-24 drh: of each wiki page has a ".wiki" suffix. The base name of b807acf62e 2007-07-24 drh: the file is the name of the wiki page. The wiki pages b807acf62e 2007-07-24 drh: have a particular file format defined below. dbda8d6ce9 2007-07-21 drh: </p> b807acf62e 2007-07-24 drh: b807acf62e 2007-07-24 drh: <i>To be continued...</i>
File Annotation