Principles Of Operation

This page attempts to define the foundational principals upon which Fossil is built.

• A project consists of source files, wiki pages, and trouble tickets. All historical copies of all these entities are saved. The project maintains an audit trail.

• A project resides in one or more repositories. Each repository is administered and operates independently of the others.

• Each repository has both global and local state. The global state is common to all repositories (or at least has the potential to be shared in common when the repositories are fully synchronized). The local state for each repository is private to that repository. The global state represents the content of the project. The local state identifies the authorized users and access policies for a particular repository.

• The global state of a repository is an mostly unordered collection of files. Each file is named by its SHA256 hash. The name is encoded as a 52-digit base-32 number. In many contexts, the name can be abbreviated to a unique prefix. A five- or six-character prefix usually suffices to uniquely identify a file.

• Because files are named by their SHA256 hash, all files are immutable. Any change to the content of a file also changes the hash that forms the files name, thus creating a new file. Both the old original version of the file and the new change are preserved under different names.

• It is theoretically possible for two files with different content to share the same hash. But finding two such files is so incredibly difficult and unlikely that we consider it to be an impossibility.

• The files that comprise the global state of a repository consist of a header followed by optional content. Every file contains an RSA signature in the header. And every file contains a "file type" designator in the header. Additional information is also found in the header depending on the file type.

• The file that comprise the global state of a repository are the complete global state of that repository. The SQLite database that holds the repository contains additional information about linkages between files, but all of that added information can be discarded and reconstructed by scanning the content files.

• Two repositories for the same project can synchronize their global states simply by sharing files. The local state of repositories is not normally synchronized or shared.

• The name of a file is its SHA256 hash in a base-32 encoding. The digits of the base-32 encode are as follows:

  0123456789abcdefghjkmnpqrstuvwxy

  The letters "o", "i", and "l" are omitted from the encoding character set to avoid confusion with the digits "0" and "1". On input, upper and lower case letters are treated the same, the letter "o" is interpreted as a zero ("0") and the letters "i" and "l" are interpreted as a one ("1"). The full name of a file is 52 characters long. The first 4 bits of the SHA256 has are repeated onto the end of the hash so that the last digit in the base-32 encoding will contain a full 5 bits. For convenience, files may often be abbreviated to a unique prefix and the repository will automatically expand the name to its full 52 characters. In practice, 5 or 6 characters are usually sufficient to give a unique name prefix to files even in the largest of projects.