|
26abbe3…
|
andygoth
|
1 |
<title>Principles Of Operation</title> |
|
f94f7e5…
|
drh
|
2 |
|
|
f94f7e5…
|
drh
|
3 |
This page attempts to define the foundational principals upon |
|
f94f7e5…
|
drh
|
4 |
which Fossil is built. |
|
1fd407f…
|
wyoung
|
5 |
|
|
1fd407f…
|
wyoung
|
6 |
* A project consists of source files, wiki pages, and |
|
1fd407f…
|
wyoung
|
7 |
trouble tickets, and control files (collectively "artifacts"). |
|
1fd407f…
|
wyoung
|
8 |
All historical copies of all artifacts |
|
1fd407f…
|
wyoung
|
9 |
are saved. The project maintains an audit |
|
1fd407f…
|
wyoung
|
10 |
trail. |
|
1fd407f…
|
wyoung
|
11 |
|
|
1fd407f…
|
wyoung
|
12 |
* A project resides in one or more repositories. Each |
|
1fd407f…
|
wyoung
|
13 |
repository is administered and operates independently |
|
1fd407f…
|
wyoung
|
14 |
of the others. |
|
1fd407f…
|
wyoung
|
15 |
|
|
1fd407f…
|
wyoung
|
16 |
* Each repository has both global and local state. The |
|
1fd407f…
|
wyoung
|
17 |
global state is common to all repositories (or at least |
|
1fd407f…
|
wyoung
|
18 |
has the potential to be shared in common when the |
|
1fd407f…
|
wyoung
|
19 |
repositories are fully synchronized). The local state |
|
1fd407f…
|
wyoung
|
20 |
for each repository is private to that repository. |
|
1fd407f…
|
wyoung
|
21 |
The global state represents the content of the project. |
|
1fd407f…
|
wyoung
|
22 |
The local state identifies the authorized users and |
|
1fd407f…
|
wyoung
|
23 |
access policies for a particular repository. |
|
1fd407f…
|
wyoung
|
24 |
|
|
1fd407f…
|
wyoung
|
25 |
* The global state of a repository is an unordered |
|
1fd407f…
|
wyoung
|
26 |
collection of artifacts. Each artifact is named by a |
|
1fd407f…
|
wyoung
|
27 |
cryptographic hash (SHA1 or SHA3-256) encoded in |
|
1fd407f…
|
wyoung
|
28 |
lowercase hexadecimal. |
|
1fd407f…
|
wyoung
|
29 |
In many contexts, the name can be |
|
1fd407f…
|
wyoung
|
30 |
abbreviated to a unique prefix. A five- or six-character |
|
1fd407f…
|
wyoung
|
31 |
prefix usually suffices to uniquely identify a file. |
|
1fd407f…
|
wyoung
|
32 |
|
|
1fd407f…
|
wyoung
|
33 |
* Because artifacts are named by a cryptographic hash, all artifacts |
|
1fd407f…
|
wyoung
|
34 |
are immutable. Any change to the content of an artifact also |
|
1fd407f…
|
wyoung
|
35 |
changes the hash that forms the artifacts name, thus |
|
1fd407f…
|
wyoung
|
36 |
creating a new artifact. Both the old original version of the |
|
1fd407f…
|
wyoung
|
37 |
artifact and the new change are preserved under different names. |
|
1fd407f…
|
wyoung
|
38 |
|
|
1fd407f…
|
wyoung
|
39 |
* It is theoretically possible for two artifacts with different |
|
1fd407f…
|
wyoung
|
40 |
content to share the same hash. But finding two such |
|
1fd407f…
|
wyoung
|
41 |
artifacts is so incredibly difficult and unlikely that we |
|
1fd407f…
|
wyoung
|
42 |
consider it to be an impossibility. |
|
1fd407f…
|
wyoung
|
43 |
|
|
1fd407f…
|
wyoung
|
44 |
* The signature of an artifact is the cryptographic hash of the |
|
1fd407f…
|
wyoung
|
45 |
artifact itself, exactly as it would appear in a disk file. No prefix |
|
1fd407f…
|
wyoung
|
46 |
or meta-information about the artifact is added before computing |
|
1fd407f…
|
wyoung
|
47 |
the hash. So you can |
|
1fd407f…
|
wyoung
|
48 |
always find the signature of a file by using the |
|
1fd407f…
|
wyoung
|
49 |
"sha1sum" or "sha3sum" or similar command-line utilities. |
|
1fd407f…
|
wyoung
|
50 |
|
|
1fd407f…
|
wyoung
|
51 |
* The artifacts that comprise the global state of a repository |
|
1fd407f…
|
wyoung
|
52 |
are the complete global state of that repository. The SQLite |
|
1fd407f…
|
wyoung
|
53 |
database that holds the repository contains additional information |
|
1fd407f…
|
wyoung
|
54 |
about linkages between artifacts, but all of that added information |
|
1fd407f…
|
wyoung
|
55 |
can be discarded and reconstructed by rescanning the content |
|
1fd407f…
|
wyoung
|
56 |
artifacts. |
|
1fd407f…
|
wyoung
|
57 |
|
|
1fd407f…
|
wyoung
|
58 |
* Two repositories for the same project can synchronize |
|
1fd407f…
|
wyoung
|
59 |
their global states simply by sharing artifacts. The local |
|
1fd407f…
|
wyoung
|
60 |
state of repositories is not normally synchronized or |
|
1fd407f…
|
wyoung
|
61 |
shared. |
|
1fd407f…
|
wyoung
|
62 |
|
|
1fd407f…
|
wyoung
|
63 |
* Every check-in has a special file at the top-level |
|
1fd407f…
|
wyoung
|
64 |
named "manifest" which is an index of all other files in |
|
1fd407f…
|
wyoung
|
65 |
that check-in. The manifest is automatically created and |
|
1fd407f…
|
wyoung
|
66 |
maintained by the system. |
|
1fd407f…
|
wyoung
|
67 |
|
|
1fd407f…
|
wyoung
|
68 |
* The <a href="fileformat.wiki">file formats</a> |
|
1fd407f…
|
wyoung
|
69 |
used by Fossil are all very simple so that with access |
|
1fd407f…
|
wyoung
|
70 |
to the original content files, one can easily reconstruct |
|
1fd407f…
|
wyoung
|
71 |
the content of a check-in without the need for any |
|
1fd407f…
|
wyoung
|
72 |
special tools or software. |