Fossil File Formats

The global state of a fossil repository is determined by an unordered set of content files. Each of these files has a format which is defined by this document.

1.0 General Formatting Rules

Fossil content files consist of a header, a blank line, and optional content.

The header is divided into "properties" by newline ('\n', 0x0a) characters. Each header property is divided into tokens by space (' ', 0x20) characters. The first token of each property is the property name. Subsequent tokens (if any) are arguments to the property.

The blank line that separates the header from the content can be thought of as a property line that contains no tokens. Everything that follows the newline character that terminates the blank line is content. The blank line is always present but the content is optional.

All tokens in a property line are encoded to escape special characters. The encoding is as follows:

Input Character	Encoded As
space (0x20)	\s
newline (0x0A)	\n
carriage return (0x0D)	\r
tab (0x09)	\t
vertical tab (0x0B)	\v
formfeed (0x0C)	\f
nul (0x00)	\0
backslash (0x5C)	\\

Characters other than the ones shown in the table above are passed through the encoder without change.

All properties names are unpunctuated lower-case ASCII strings. The properties appear in the header in sorted order (using memcpy() as the comparision function) except for the "signature" property which always occurs first.

2.0 Common Properties

Every content file has a "time" property. The argument to the time property is an integer which is the number of seconds since 1970 UTC when the content file was created. For example:

time 1181404746

Every content file has a "type" property. The argument to the type property defines the purpose of the content file. The argument can be strings like "version", "folder", "file", or "user".

The first property of a content file is the digital signature. The name of the signature property is "signature". There are two arguments. The first argument is the SHA256 hash of the content file that defines the user who signed this file. User records themselves are self-signed and so the first argument is simply "*" for user records. The second argument is the digital signature of an SHA256 hash of the entire file (header and content) except for the signature line itself.