Artifact 30a64c40a71b9fe5b72a112de050d59ec89230aa7932951dd134e06ccbc94cb9:

File www/pop.wiki — part of check-in [1fd407f61a] at 2023-05-10 17:02:02 on branch trunk — In an effort to make www/* source documents read as cleanly as their rendered counterparts, replaced nearly all use of HTML "p" tags, relying instead on the Wiki and Markdown markup features to achieve the same appearance. The only uses remaining are: * in Markdown nested lists, where blank lines should render the list items as separate paragraphs just as at the list's top level; since it does not, if you want a line break, you either have to wrap the item in "p" tags or do the double-br hack. * in Wiki where blank lines within a list give you a separate list in the HTML output; this is fine for bullet lists, but with numbered lists it causes the numbering to restart unless you do the same sort of manual HTML workaround as with the prior item * in plain HTML docs and wiki docs between "nowiki" tags In many places, this cleanup gets rid of pointless stray "p" tags, placating HTML verifiers. (user: wyoung size: 3367) [more...]

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, and control files (collectively "artifacts"). All historical copies of all artifacts 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 unordered collection of artifacts. Each artifact is named by a cryptographic hash (SHA1 or SHA3-256) encoded in lowercase hexadecimal. 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 artifacts are named by a cryptographic hash, all artifacts are immutable. Any change to the content of an artifact also changes the hash that forms the artifacts name, thus creating a new artifact. Both the old original version of the artifact and the new change are preserved under different names.

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

The signature of an artifact is the cryptographic hash of the artifact itself, exactly as it would appear in a disk file. No prefix or meta-information about the artifact is added before computing the hash. So you can always find the signature of a file by using the "sha1sum" or "sha3sum" or similar command-line utilities.

The artifacts 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 artifacts, but all of that added information can be discarded and reconstructed by rescanning the content artifacts.

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

Every check-in has a special file at the top-level named "manifest" which is an index of all other files in that check-in. The manifest is automatically created and maintained by the system.

The file formats used by Fossil are all very simple so that with access to the original content files, one can easily reconstruct the content of a check-in without the need for any special tools or software.