Artifact 78644886eb214bb07c704f7613dd473efa5f8e95:

• File www/tech_overview.wiki — part of check-in [0e1447a6ea] at 2010-12-26 00:43:43 on branch trunk — Update the quick-start guide documentation to provide hyperlinks to the command-line help in the web interface. Add the beginning of a technical overview article, but as that article is still incomplete, do not hyperlink to it. (user: drh size: 4161)

Technical Overview

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 described separately.

This article is about how Fossil is currently implemented. Instead of dealing with vague abstractions of "enduring file formats" as the 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 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.

2.1 The Configuration Database

2.2 Repository Databases

2.3 Checkout Databases