A Technical Overview
Of The Design And Implementation
Of Fossil

1.0 Introduction

At its lowest level, a Fossil repository consists of an unordered set of immutable "artifacts". Think of these artifacts as "files", since in many cases the artifacts do indeed exactly correspond to source code files that are stored in the Fossil repostory. But other "control artifacts" are also included in the mix. These control artifacts define the relationships between artifacts - which files go together to form a particular version of the project, who checked in that version and when, what was the check-in comment, what wiki pages are included with the project, what are the edit histories of each wiki page, what bug reports or tickets are included, who contributed to the evolution of each ticket, and so forth, and so on. This low-level file format is called the "global state" of the repository, since this is the information that is synced to peer repositories using push and pull operations. the low-level file format is also called "enduring" since it is intended to last for generations. The details of the low-level, enduring, global file format are [./fileformat.wiki | described separately]. This article is about how Fossil is currently implemented. Instead of dealing with vague abstractions of "enduring file formats" as the [./fileformat.wiki | that other document] does, this article provides some detail on how Fossil actually stores information on disk.

2.0 Three Databases

Fossil stores state information in [http://www.sqlite.org/ | SQLite] database files. SQLite stores an entire relational database, including multiple tables and indices, in a single disk file. The SQLite library allows the database files to be efficiently queried and updated using the industry-standard SQL language. And SQLite makes updates to these database files atomic, even in the face of system crashes and power failures, meaning that even a power loss in the middle of a commit will not damage the Fossil repository content. Fossil uses three separate SQLite databases:
  1. The configuration database
  2. Repository databases
  3. Checkout databases
The configuration database is a one-per-user database that holds global configuration information used by Fossil. There is one repository database per project. The repository database is the file that people are normally referring to when they say "a Fossil repository". The checkout database is found in the working checkout for a project and contains state information that is unique to that working checkout. The chart below provides a quick summary of how each of these database files are used by Fossil, with detailed discussion following.

Configuration Database
"~/.fossil"

  • Global [/help/setting |settings]
  • List of active repositories used by the [/help/all | all] command

Repository Database
"project.fossil"

  • [./fileformat.wiki | Global state of the project] encoded using delta-compression
  • Local [/help/setting|settings]
  • Web interface display preferences
  • User credentials and permissions
  • Meta-data about the global state to facilitate rapid queries

Checkout Database
"_FOSSIL_"

  • The version currently checked out
  • Other versions [/help/merge | merged] in but not yet [/help/commit | committed]
  • Changes from the [/help/add | add], [/help/delete | delete], and [/help/rename | rename] commands that have not yet been committed
  • "mtime" values and other information used to efficiently detect local edits
  • The "[/help/stash | stash]"
  • Information needed to "[/help/undo|undo]" or "[/help/redo|redo]"

2.1 The Configuration Database

2.2 Repository Databases

2.3 Checkout Databases