d87ca60c58 2008-05-15   stephan: <h1>Principles Of Operation</h1>
d87ca60c58 2008-05-15   stephan: 
d87ca60c58 2008-05-15   stephan: <p>
d87ca60c58 2008-05-15   stephan: This page attempts to define the foundational principals upon
d87ca60c58 2008-05-15   stephan: which Fossil is built.
d87ca60c58 2008-05-15   stephan: </p>
d87ca60c58 2008-05-15   stephan: 
d87ca60c58 2008-05-15   stephan: <ul>
d87ca60c58 2008-05-15   stephan: <li><p>A project consists of source files, wiki pages, and
d87ca60c58 2008-05-15   stephan: trouble tickets, and control files (collectively "artifacts").
d87ca60c58 2008-05-15   stephan: All historical copies of all artifacts
d87ca60c58 2008-05-15   stephan: are saved.  The project maintains an audit
d87ca60c58 2008-05-15   stephan: trail.</p></li>
d87ca60c58 2008-05-15   stephan: 
d87ca60c58 2008-05-15   stephan: <li><p>A project resides in one or more repositories.  Each
d87ca60c58 2008-05-15   stephan: repository is administered and operates independently
d87ca60c58 2008-05-15   stephan: of the others.</p></li>
d87ca60c58 2008-05-15   stephan: 
d87ca60c58 2008-05-15   stephan: <li><p>Each repository has both global and local state.  The
d87ca60c58 2008-05-15   stephan: global state is common to all repositories (or at least
d87ca60c58 2008-05-15   stephan: has the potential to be shared in common when the
d87ca60c58 2008-05-15   stephan: repositories are fully synchronized).  The local state
d87ca60c58 2008-05-15   stephan: for each repository is private to that repository.
d87ca60c58 2008-05-15   stephan: The global state represents the content of the project.
d87ca60c58 2008-05-15   stephan: The local state identifies the authorized users and
d87ca60c58 2008-05-15   stephan: access policies for a particular repository.</p></li>
d87ca60c58 2008-05-15   stephan: 
d87ca60c58 2008-05-15   stephan: <li><p>The global state of a repository is an unordered
d87ca60c58 2008-05-15   stephan: collection of artifacts.  Each artifact is named by
d87ca60c58 2008-05-15   stephan: its SHA1 hash encoded in lowercase hexadecimal.
d87ca60c58 2008-05-15   stephan: In many contexts, the name can be
d87ca60c58 2008-05-15   stephan: abbreviated to a unique prefix.  A five- or six-character
d87ca60c58 2008-05-15   stephan: prefix usually suffices to uniquely identify a file.</p></li>
d87ca60c58 2008-05-15   stephan: 
d87ca60c58 2008-05-15   stephan: <li><p>Because artifacts are named by their SHA1 hash, all artifacts
d87ca60c58 2008-05-15   stephan: are immutable.  Any change to the content of a artifact also
d87ca60c58 2008-05-15   stephan: changes the hash that forms the artifacts name, thus
d87ca60c58 2008-05-15   stephan: creating a new artifact.  Both the old original version of the
d87ca60c58 2008-05-15   stephan: artifact and the new change are preserved under different names.</p></li>
d87ca60c58 2008-05-15   stephan: 
d87ca60c58 2008-05-15   stephan: <li><p>It is theoretically possible for two artifacts with different
d87ca60c58 2008-05-15   stephan: content to share the same hash.  But finding two such
d87ca60c58 2008-05-15   stephan: artifacts is so incredibly difficult and unlikely that we
d87ca60c58 2008-05-15   stephan: consider it to be an impossibility.</p></li>
d87ca60c58 2008-05-15   stephan: 
d87ca60c58 2008-05-15   stephan: <li><p>The signature of an artifact is the SHA1 hash of the
d87ca60c58 2008-05-15   stephan: artifact itself, exactly as it would appear in a disk file.  No prefix
d87ca60c58 2008-05-15   stephan: or meta-information about the artifact is added before computing
d87ca60c58 2008-05-15   stephan: the hash.  So you can
d87ca60c58 2008-05-15   stephan: always find the SHA1 signature of a file by using the
d87ca60c58 2008-05-15   stephan: "sha1sum" command-line utility.</p></li>
d87ca60c58 2008-05-15   stephan: 
d87ca60c58 2008-05-15   stephan: <li><p>The artifacts that comprise the global state of a repository
d87ca60c58 2008-05-15   stephan: are the complete global state of that repository.  The SQLite
d87ca60c58 2008-05-15   stephan: database that holds the repository contains additional information
d87ca60c58 2008-05-15   stephan: about linkages between artifacts, but all of that added information
d87ca60c58 2008-05-15   stephan: can be discarded and reconstructed by rescanning the content
d87ca60c58 2008-05-15   stephan: artifacts.</p></li>
d87ca60c58 2008-05-15   stephan: 
d87ca60c58 2008-05-15   stephan: <li><p>Two repositories for the same project can synchronize
d87ca60c58 2008-05-15   stephan: their global states simply by sharing artifacts.  The local
d87ca60c58 2008-05-15   stephan: state of repositories is not normally synchronized or
d87ca60c58 2008-05-15   stephan: shared.</p></li>
d87ca60c58 2008-05-15   stephan: 
904ee40b93 2009-01-23       drh: <li><p>Every check-in has a special file at the top-level
d87ca60c58 2008-05-15   stephan: named "manifest" which is an index of all other files in
904ee40b93 2009-01-23       drh: that check-in.  The manifest is automatically created and
d87ca60c58 2008-05-15   stephan: maintained by the system.</p></li>
d87ca60c58 2008-05-15   stephan: 
16094f7ebc 2008-05-16       drh: <li><p>The <a href="fileformat.wiki">file formats</a>
d87ca60c58 2008-05-15   stephan: used by Fossil are all very simple so that with access
d87ca60c58 2008-05-15   stephan: to the original content files, one can easily reconstruct
904ee40b93 2009-01-23       drh: the content of a check-in without the need for any
d87ca60c58 2008-05-15   stephan: special tools or software.</p></li>