Fossil: Artifact Content

Artifact bf75283289b41b2624c0496fa6de304fdf470da2

File www/pop.html part of check-in [dbda8d6ce9] - Initial check-in of m1 sources. by drh on 2007-07-21 14:10:57.
<html>
<head>
<title>Fossil - Principles of Operation</title>
</head>
<body bgcolor="white">
<h1>Principles Of Operation</h1>

<p>
This page attempts to define the foundational principals upon
which Fossil is built.
</p>

<ul>
<li><p>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.</p></li>

<li><p>A project resides in one or more repositories.  Each
repository is administered and operates independently 
of the others.</p></li>

<li><p>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.</p></li>

<li><p>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.</p></li>

<li><p>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.</p></li>

<li><p>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.</p></li>

<li><p>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.</p></li>

<li><p>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.</p></li>

<li><p>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.</p></li>

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

<blockquote><b>
    0123456789abcdefghjkmnpqrstuvwxy
</b></blockquote>

<p>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.</p></li>
</ul>

</body>
</html>