Fossil

Check-in [522824b2]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Documentation updates, including a big rework of the homepage.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 522824b26a27a5985f77be163368fc75d2ff06eb
User & Date: drh 2009-08-28 16:05:03
Context
2009-08-28
17:19
Add three new variations on the logo GIF. check-in: 1cbae4e7 user: drh tags: trunk
16:05
Documentation updates, including a big rework of the homepage. check-in: 522824b2 user: drh tags: trunk
2009-08-27
20:14
Add the ability to view diffs of wiki changes. check-in: 8e3b7fab user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/build.wiki.

1
2
3
4
5
6
7
8
9
10
<title>Fossil Documentation</title>
<nowiki>
<h1>Installing Fossil</h1>

<p>This page describes how to build and install Fossil.  The
whole process is designed to be very easy.</p>

<h2>0.0 Using A Pre-compiled Binary</h2>

<p>You can skip steps 1.0 and 2.0 below by downloading
|

<







1
2

3
4
5
6
7
8
9
<title>Building and Installing Fossil</title>
<nowiki>


<p>This page describes how to build and install Fossil.  The
whole process is designed to be very easy.</p>

<h2>0.0 Using A Pre-compiled Binary</h2>

<p>You can skip steps 1.0 and 2.0 below by downloading

Changes to www/concepts.wiki.

1
2
3
4
5
6

7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118




119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
...
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208

209
210
211
212
213

214
215


216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337

338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357






358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407

408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
<title>Fossil Concepts</title>
<nowiki>
<h1 align="center">Fossil Concepts</h1>

<h2>1.0 Introduction</h2>
<p>

<a href="index.html">Fossil</a> is a
<a href="http://en.wikipedia.org/wiki/Software_configuration_management">
software configuration management</a> system.
Fossil is software that is designed to control and track the
development of a software project and to record the history
of the project.
There are many such systems in use today.  Fossil strives to
distinguish itself from the others by being extremely simple
to setup and operate.</p>

<p>This document is intended as a quick introduction to the concepts
behind fossil.</p>

<h2>2.0 Composition Of A Project</h2>
<img src="concept1.gif" align="right" hspace="10">

<p>A software project normally consists of a "source tree".
A source tree is a hierarchy of files that are used to generate
the end product.  The source tree changes over time as the
software grows and expands and as features are added and bugs
are fixed.  A snapshot of the source tree at any point in time
is called a "version" or "revision" or a "baseline" of the product.
In fossil, we use the name "check-in".</p>

<p>A "repository" is a database that contains copies of all historical
check-ins for a project.  Check-ins are normally stored in the
repository in a highly space-efficient compressed format (delta encoding).
But that is an implementation detail that you the user need not worry over.
Think of the repository as a safe place where all your old check-ins are
securely stored away and available for retrieval whenever you need
them.</p>

<p>A repository in fossil is a single file on your disk.  This file
might be rather large (dozens or hundreds of megabytes for a large
or long running project) but it is nevertheless just a file.  You
can move it around, rename it, write it out to a memory stick, or
do anything else you normally do with files.</p>

<p>Each source tree that is controlled by fossil is associated with
a single repository on the local disk drive.  You can tie two or more
source trees to a single repository if you want (though one
tree per repository is the most common configuration.)  So a
single repository can be associated with many source trees, but
each source tree is associated with only one repository.</p>

<p>Fossil source trees may not overlap.  A fossil source tree is identified
by a file named "_FOSSIL_" in the root directory of the source tree.  Every
file that is a sibling of _FOSSIL_ and every file in every subfolder is
considered potentially a part of the source tree.  The _FOSSIL_ file
contains (among other things) the pathname of the repository with which
the source tree is associated.  On the other hand, the repository has
no record of its source trees.  So you are free to delete a source tree
or move it around without consequence.  But if you move or rename or
delete a repository, then any source trees associated with that repository
will no longer be able to locate their repository and will stop working.</p>

<p>When multiple developers are working on the same project, each
developer typically has his or her own local repository and an associated
source tree in which to work.  Developers share their work by
"syncing" the content of their local repositories either directly
or through a central server.  Changes can "push" from the local
repository into a remote repository.  Or changes can "pull" from a
remote repository into a local repository.  Or one can do a "sync"
which is a shortcut for doing both a push and a pull at the same time.
Fossil also has the concept of "cloning".  A "clone" is like a "pull",
except that instead of beginning with an existing local repository,
a clone begins with nothing and creates a new local repository that
is a duplicate of a remote repository.</p>

<p>Communication between repositories is via HTTP.  Remote
repositories are identified by URL.  You can also point a web browser
at a repository and get human-readable status, history, and tracking
information about the project.</p>

<h3>2.1 Identification Of Artifacts</h3>

<p>A particular version of a particular file is called an "artifact".
Each artifact has a universally unique name which is the
<a href="http://en.wikipedia.org/wiki/SHA">SHA1</a> hash of the content
of that file expressed as 40 characters of lower-case hexadecimal.  Such
a hash is referred to as the Artifact Identifier or Artifact ID
for the artifact.  The SHA1 algorithm is created with the purpose of
providing a highly forgery-resistant identifier for a file.  Given any
file it is simple to find the artifact ID for that file.  But given a
artifact ID it is computationally intractable to generate a file that will
have that Artifact ID.</p>


<p>Artifact IDs look something like this:</p>

<blockquote><b>
6089f0b563a9db0a6d90682fe47fd7161ff867c8<br>
59712614a1b3ccfd84078a37fa5b606e28434326<br>
19dbf73078be9779edd6a0156195e610f81c94f9<br>
b4104959a67175f02d6b415480be22a239f1f077<br>
997c9d6ae03ad114b2b57f04e9eeef17dcb82788
</b></blockquote>

<p>When referring to an artifact using fossil, you can use a unique
prefix of the artifact ID that is four characters or longer.  This saves
a lot of typing.  When displaying artifact IDs, fossil will usually only
show the first 10 digits since that is normally enough to uniquely
identify a file.</p>

<p>Changing (or adding or removing) a single byte in a file results
in a completely different artifact ID.  And since the artifact ID is the name of
the artifact, making any change to a file results in a new artifact.
In this way, artifacts are immutable.</p>

<p>A repository is really just an unordered collection of
artifacts.  New artifacts can be added to the repository, but
existing artifacts can never be removed.  Fossil is designed in




such a way that it can be handed a set of artifacts in any
order and it can figure out the relationship between those
artifacts and reconstruct the complete development history of
a software project.</p>

<h3>2.2 Manifests</h3>

<p>At the root of a source tree is a special file called the
"manifest".  The manifest is a listing of all other files in
that source tree.  The manifest contains the (complete) artifact ID 
of the file and the name of the file as it appears on disk,
and thus serves as a mapping from artifact ID to disk name.  The artifact ID
of the manifest is the identifier for the entire check-in.  When
you look at a "timeline" of changes in fossil, the ID associated
with each check-in or commit is really just the artifact ID of the
manifest for that check-in.</p>

<p>Fossil automatically generates a manifest whenever you "commit" 
a new check-in.  So this is not something that you, the developer,
need to worry with.  The format of a manifest is intentionally
designed to be simple to parse, so that if
you want to read and interpret a manifest, either by hand or
with a script, that is easy to do.  But you will probably never
................................................................................
<li>Fossil automatically generates a <b>manifest</b> file that identifies
    every artifact in a check-in.</li>
<li>The artifact ID of the manifest is the identifier of the check-in.</li>
</ul>

<h2>3.0 Fossil - The Program</h2>

<p>Fossil is software.  The implementation of fossil is in the form
of a single executable named "fossil".  To install fossil on your system,
all you have to do is obtain a copy of this one executable file (either
by downloading a pre-compiled version or compiling it yourself) and then
putting that file somewhere on your PATH.</p>

<p>Fossil is completely self-contained.  It is not necessary to
install any other software in order to use fossil.  You do <u>not</u> need
CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, apache, PostgreSQL, MySQL,
SQLite, patch, or any similar software on your system in order to use
fossil effectively.  You will want to have some kind of text editor
for entering check-in comments.  Fossil will use whatever text editor
is identified by your VISUAL environment variable.  Fossil will also
use GPG to clearsign your manifests if you happen to have it installed,
but fossil will skip that step if GPG missing from your system.
You can optionally set up fossil to use external "diff" programs, 
though fossil has an excellent built-in "diff" algorithm that works
fine for most people.</p>

<p>To uninstall fossil, simply delete the executable.</p>

<p>To upgrade an older version of fossil to a newer version, just
replace the old executable with the new one.  You might need to 
run a one-time command to restructure your repositories after
an upgrade.  Check the instructions that come with the upgrade
for details.</p>

<p>To use fossil, simply type the name of the executable in your
shell, followed by one of the various built-in commands and
arguments appropriate for that command.  For example:</p>

<blockquote><b>
fossil help
</b></blockquote>

<p>In the next section, when we say things like "use the <b>help</b>
command" we mean to use the command name "help" as the first
token after the name of the fossil executable, as shown above.</p>


<h2>4.0 Workflow</h2>

<img src="concept2.gif" align="right" hspace="10">

<p>Fossil has two modes of operation: "autosync" and "non-autosync".

Autosync mode works something like CVS or SVN in that it automatically
keeps your work in sync with the central server.  Non-autosync is


more like GIT or Bitkeeper in that your local repository develops
independently of your coworkers and you share your changes manually.
An interesting feature of fossil is that it supports both autosync
and non-autosync work flows.</p>

<p>The default setting for fossil is to be in autosync mode.  You
can change the autosync setting or check the current autosync
setting using commands like:</p>

<blockquote>
<b>fossil setting autosync on<br>
fossil setting autosync off<br>
<b>fossil settings</b>
</blockquote>

<p>By default, fossil runs with autosync mode turned on.  The
authors find that projects run more smoothly when autosync is only
disabled when off-network.</p>




<h3>4.1 Autosync Workflow</h3>

<ol>
<li><p>
Establish a local repository using either the <b>new</b> command
to start a new project, or the <b>clone</b> command to make a clone
of a repository for an existing project. 
</p></li>

<li><p>
Establish one or more source trees by changing your working directory
to where you want the root of the source tree to be, then issuing
the <b>open</b> command with the name of the repository file as its
argument.
</p></li>

<li><p>
The <b>open</b> command in the previous step populates your local source
tree with a copy of the latest check-in.  Usually this is what you want.
In the rare cases where it is not, use the <b>update</b> command to
switch to a new check-in.  Use the <b>timeline</b> or <b>leaves</b> commands
to identify alternative check-ins to switch to.
</p></li>

<li><p>
Edit the code.  Add new files to the source tree using the <b>add</b>
command.  Omit files from future check-ins using the <b>rm</b> command.
(Even when you remove files from future check-ins, those files continue
to exist in historical check-ins.)  Test your changes.
</p></li>

<li><p>
Create a new check-in using the <b>commit</b> command.  You will be prompted
for a check-in comment and also for your GPG key if you have GPG installed.
The commit copies the edits you have made in your local source
tree into your local repository.  After your commit completes, fossil will
automatically <b>push</b> your changes back to the server
you cloned from or whatever server you most recently synced with.
</p></li>

<li><p>
When your coworkers make their own changes, you can merge those changes
into your local local source tree using the <b>update</b> command.  
In autosync mode, <b>update</b> will first go back to the server you
cloned from or with which you most recently synced, and pull down all
recent changes into your local repository.  Then it will merge recent
changes into your local source tree.  If you do an <b>update</b> and
find that it messes something up in your source tree (perhaps a co-worker
checked in incompatible changes) you can use the <b>undo</b> command 
to back out the changes.
</p></li>

<li><p>
Repeat all of the above until you have generated great software.
</p></li>
</ol>

<h3>4.2 Non-Autosync Workflow</h3>

<p>When autosync is disabled, the <b>commit</b> command is decoupled from
<b>push</b> and the <b>update</b> command is decoupled from <b>pull</b>.
That means you have to do a few extra steps in order to accomplish the
<b>push</b> and <b>pull</b> tasks manually.</p>

<ol>
<li><p>
Establish a local repository using either the <b>new</b> command
to start a new project, or the <b>clone</b> command to make a clone
of a repository for an existing project.   The default setting for
a new repository is with autosync on, so you will need to turn it off
using the <b>setting autosync off</b> command with a <b>-R</b> option
to specify the repository.
</p></li>

<li><p>
Establish one or more source trees by changing your working directory
to where you want the root of the source tree to be, then issuing
the <b>open</b> command with the name of the repository file as its
argument.
</p></li>

<li><p>
The <b>open</b> command in the previous step populates your local source
tree with a copy of the latest check-in.  Usually this is what you want.
In the rare cases where it is not, use the <b>update</b> command to
switch to a new check-in.  Use the <b>timeline</b> or <b>leaves</b> commands
to identify alternative check-ins to switch to.
</p></li>

<li><p>
Edit the code.  Add new files to the source tree using the <b>add</b>
command.  Omit files from future check-ins using the <b>rm</b> command.
(Even when you remove files from future check-ins, those files continue
to exist in historical check-ins.)  Test your changes.
</p></li>

<li><p>
Create a new check-in using the <b>commit</b> command.  You will be prompted
for a check-in comment and also for your GPG key if you have GPG installed.
The commit copies the edits you have made in your local source
tree into your local repository.
</p></li>


<li><p>Use the <b>push</b> command to push your changes out to a server
where your co-workers can access them.
</p></li>

<li><p>
When co-workers make their own changes, use the <b>pull</b> command
to pull those changes into your local repository.  Note that <b>pull</b>
does not move the changes into your local source tree, only into your
local repository.
</p></li>

<li><p>
Once changes are in your local repository, use
use the <b>update</b> command to merge them to your local source tree.
If you merge in some changes and find that the changes do not work out
or are not to your liking, you can back out the changes using the
<b>undo</b> command.
</p></li>

<li><p>






Repeat all of the above until you have generated great software.
</p></li>
</ol>

<h2>5.0 Setting Up A Fossil Server</h2>

<p>With other configuration management software, setting up a server is
a lot of work and normally takes time, patience, and a lot of system
knowledge.  Fossil is designed to avoid this frustration.  Setting up
a server with fossil is ridiculously easy.  You have three options:</p>

<ol>
<li><p><b><a name="saserv">S</a>etting up a stand-alone server</b></p>

<p>From within your source tree just use the <b>server</b> command and
fossil will start listening for incoming requests on TCP port 8080.
You can point your web browser at <a href="http://localhost:8080/">
http://localhost:8080/</a> and begin exploring.  Or your coworkers
can do pushes or pulls against your server.  Use the <b>--port</b>
option to the server command to specify a different TCP port.  If
you do not have a local source tree, use the <b>-R</b> command-line
option to specify the repository file.</p>

<p>A stand-alone server is a great way to set of transient connections
between coworkers for doing quick pushes or pulls.  But you can also
set up a permanent stand-alone server if you prefer.  Just make
arrangements for fossil to be launched with appropriate arguments
after every reboot.</p>

<p>If you just want a server to browse the built-in fossil website
locally, use the <b>ui</b> command in place of <b>server</b>.  The
<b>ui</b> command starts up a local server too, but it also takes
the additional step of automatically launching your webbrowser and
pointing at the new server.</p>
</li>

<li><p><b>Setting up a CGI server</b></p>

<p>If you have a webserver running on your machine already, you can
set up fossil to be run from CGI.  Simply create an executable script
that looks something like this:</p>

<blockquote><pre>
#!/usr/local/bin/fossil
repository: /home/me/bigproject.fossil
</pre></blockquote>

<p>Edit this script to use whatever pathnames are appropriate for
your project.  Then point your web browser at the script and off you
go.</p></li>


<li><p><b>Setting up an inetd server</b></p>

<p>If you have inetd or xinetd running on your system, you can set
those services up to launch fossil to deal with inbound TCP/IP connections
on whatever port you want.  Set up inetd or xinetd to launch fossil
like this:</p>

<blockquote><pre>
/usr/local/bin/fossil http /home/me/bigproject.fossil
</pre></blockquote>

<p>As before, change the filenames to whatever is appropriate for
your system.  You can have fossil run as any user that has write
permission on the repository and on the directory that contains the
repository.  But it is safer to run fossil as root.  When fossil
sees that it is running as root, it automatically puts itself into
a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> and
drops all privileges prior to reading any information from the client.
Since fossil is a stand-alone program, you do not need to put anything
in the chroot jail with fossil in order for it to do its job.</p>
</li>
</ol>

<h2>6.0 Review Of Key Concepts</h2>

<ul>
<li>The <b>fossil</b> program is a self-contained stand-alone executable.

<



<
>
|
|
<





|

|
|




|





|

|





|

|



|

|




|

|








|

|










|

|


|



|








|

<
|









|



|

|


|

|

|
>
>
>
>



|



|







|







 







|



|

|










|

|

|

|
|
|

|

|





|

|

>




|
>
|
<
>
>
|
|

|

|

|







|
|
|
>
>
>




|



|

|




|

|





|

|




|

|






|

|









|

|

|


|

|


|


|






|

|




|

|





|

|




|

|




|

>
|

|

|




|

|





|

|
>
>
>
>
>
>

|




|





|

|






|

|



|

|



|


|

|

|






|

|
>

|

|


|





|







|







1

2
3
4

5
6
7

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
...
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217

218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
<title>Fossil Concepts</title>

<h1 align="center">Fossil Concepts</h1>

<h2>1.0 Introduction</h2>


[./index.wiki | Fossil] is a
[http://en.wikipedia.org/wiki/Software_configuration_management | software configuration management] system.

Fossil is software that is designed to control and track the
development of a software project and to record the history
of the project.
There are many such systems in use today.  Fossil strives to
distinguish itself from the others by being extremely simple
to setup and operate.

This document is intended as a quick introduction to the concepts
behind fossil.

<h2>2.0 Composition Of A Project</h2>
<img src="concept1.gif" align="right" hspace="10">

A software project normally consists of a "source tree".
A source tree is a hierarchy of files that are used to generate
the end product.  The source tree changes over time as the
software grows and expands and as features are added and bugs
are fixed.  A snapshot of the source tree at any point in time
is called a "version" or "revision" or a "baseline" of the product.
In fossil, we use the name "check-in".

A "repository" is a database that contains copies of all historical
check-ins for a project.  Check-ins are normally stored in the
repository in a highly space-efficient compressed format (delta encoding).
But that is an implementation detail that you the user need not worry over.
Think of the repository as a safe place where all your old check-ins are
securely stored away and available for retrieval whenever you need
them.

A repository in fossil is a single file on your disk.  This file
might be rather large (dozens or hundreds of megabytes for a large
or long running project) but it is nevertheless just a file.  You
can move it around, rename it, write it out to a memory stick, or
do anything else you normally do with files.

Each source tree that is controlled by fossil is associated with
a single repository on the local disk drive.  You can tie two or more
source trees to a single repository if you want (though one
tree per repository is the most common configuration.)  So a
single repository can be associated with many source trees, but
each source tree is associated with only one repository.

Fossil source trees may not overlap.  A fossil source tree is identified
by a file named "_FOSSIL_" in the root directory of the source tree.  Every
file that is a sibling of _FOSSIL_ and every file in every subfolder is
considered potentially a part of the source tree.  The _FOSSIL_ file
contains (among other things) the pathname of the repository with which
the source tree is associated.  On the other hand, the repository has
no record of its source trees.  So you are free to delete a source tree
or move it around without consequence.  But if you move or rename or
delete a repository, then any source trees associated with that repository
will no longer be able to locate their repository and will stop working.

When multiple developers are working on the same project, each
developer typically has his or her own local repository and an associated
source tree in which to work.  Developers share their work by
"syncing" the content of their local repositories either directly
or through a central server.  Changes can "push" from the local
repository into a remote repository.  Or changes can "pull" from a
remote repository into a local repository.  Or one can do a "sync"
which is a shortcut for doing both a push and a pull at the same time.
Fossil also has the concept of "cloning".  A "clone" is like a "pull",
except that instead of beginning with an existing local repository,
a clone begins with nothing and creates a new local repository that
is a duplicate of a remote repository.

Communication between repositories is via HTTP.  Remote
repositories are identified by URL.  You can also point a web browser
at a repository and get human-readable status, history, and tracking
information about the project.

<h3>2.1 Identification Of Artifacts</h3>

A particular version of a particular file is called an "artifact".
Each artifact has a universally unique name which is the
<a href="http://en.wikipedia.org/wiki/SHA">SHA1</a> hash of the content
of that file expressed as 40 characters of lower-case hexadecimal.  Such
a hash is referred to as the Artifact Identifier or Artifact ID
for the artifact.  The SHA1 algorithm is created with the purpose of
providing a highly forgery-resistant identifier for a file.  Given any
file it is simple to find the artifact ID for that file.  But given a
artifact ID it is computationally intractable to generate a file that will
have that Artifact ID.


Artifact IDs look something like this:

<blockquote><b>
6089f0b563a9db0a6d90682fe47fd7161ff867c8<br>
59712614a1b3ccfd84078a37fa5b606e28434326<br>
19dbf73078be9779edd6a0156195e610f81c94f9<br>
b4104959a67175f02d6b415480be22a239f1f077<br>
997c9d6ae03ad114b2b57f04e9eeef17dcb82788
</b></blockquote>

When referring to an artifact using fossil, you can use a unique
prefix of the artifact ID that is four characters or longer.  This saves
a lot of typing.  When displaying artifact IDs, fossil will usually only
show the first 10 digits since that is normally enough to uniquely
identify a file.

Changing (or adding or removing) a single byte in a file results
in a completely different artifact ID.  And since the artifact ID is the name of
the artifact, making any change to a file results in a new artifact.
In this way, artifacts are immutable.

A repository is really just an unordered collection of
artifacts.  New artifacts can be added to the repository, but
existing artifacts can never be removed.  (Well, almost never. There
is a [./shunning.wiki | "shunning"] mechanism that allows spam or other
inappropriate content to be removed if absolutely necessary, but such
removal is discouraged.)
Fossil is designed in
such a way that it can be handed a set of artifacts in any
order and it can figure out the relationship between those
artifacts and reconstruct the complete development history of
a software project.

<h3>2.2 Manifests</h3>

At the root of a source tree is a special file called the
"manifest".  The manifest is a listing of all other files in
that source tree.  The manifest contains the (complete) artifact ID 
of the file and the name of the file as it appears on disk,
and thus serves as a mapping from artifact ID to disk name.  The artifact ID
of the manifest is the identifier for the entire check-in.  When
you look at a "timeline" of changes in fossil, the ID associated
with each check-in or commit is really just the artifact ID of the
manifest for that check-in.

<p>Fossil automatically generates a manifest whenever you "commit" 
a new check-in.  So this is not something that you, the developer,
need to worry with.  The format of a manifest is intentionally
designed to be simple to parse, so that if
you want to read and interpret a manifest, either by hand or
with a script, that is easy to do.  But you will probably never
................................................................................
<li>Fossil automatically generates a <b>manifest</b> file that identifies
    every artifact in a check-in.</li>
<li>The artifact ID of the manifest is the identifier of the check-in.</li>
</ul>

<h2>3.0 Fossil - The Program</h2>

Fossil is software.  The implementation of fossil is in the form
of a single executable named "fossil".  To install fossil on your system,
all you have to do is obtain a copy of this one executable file (either
by downloading a pre-compiled version or compiling it yourself) and then
putting that file somewhere on your PATH.

Fossil is completely self-contained.  It is not necessary to
install any other software in order to use fossil.  You do <u>not</u> need
CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, apache, PostgreSQL, MySQL,
SQLite, patch, or any similar software on your system in order to use
fossil effectively.  You will want to have some kind of text editor
for entering check-in comments.  Fossil will use whatever text editor
is identified by your VISUAL environment variable.  Fossil will also
use GPG to clearsign your manifests if you happen to have it installed,
but fossil will skip that step if GPG missing from your system.
You can optionally set up fossil to use external "diff" programs, 
though fossil has an excellent built-in "diff" algorithm that works
fine for most people.

To uninstall fossil, simply delete the executable.

To upgrade an older version of fossil to a newer version, just
replace the old executable with the new one.  You might need to 
run "<b>fossil all rebuild</b>" to restructure your repositories after
an upgrade.  Running "all rebuild" never hurts, so when upgrading it
is a good policy to run it even if it is not strictly necessary.

To use fossil, simply type the name of the executable in your
shell, followed by one of the various built-in commands and
arguments appropriate for that command.  For example:

<blockquote><b>
fossil help
</b></blockquote>

In the next section, when we say things like "use the <b>help</b>
command" we mean to use the command name "help" as the first
token after the name of the fossil executable, as shown above.

<a name="workflow">
<h2>4.0 Workflow</h2>

<img src="concept2.gif" align="right" hspace="10">

Fossil has two modes of operation: <i>"autosync"</i> and
<i>"manual-merge"</i>
Autosync mode is reminiscent of CVS or SVN in that it automatically

keeps your changes in synchronization with your co-workers through
the use of a central server.  The manual-merge mode is the standard workflow
for GIT or Mercurial in that your local repository develops
independently of your coworkers and you share and merge your changes manually.
An interesting feature of fossil is that it supports both autosync
and manual-merge work flows.

The default setting for fossil is to be in autosync mode.  You
can change the autosync setting or check the current autosync
setting using commands like:

<blockquote>
<b>fossil setting autosync on<br>
fossil setting autosync off<br>
<b>fossil settings</b>
</blockquote>

By default, fossil runs with autosync mode turned on.  The
authors finds that projects run more smoothly in autosync mode since
autosync helps to prevent pointless forking and merge and helps keeps
all collaborators working on exactly the same code rather than on their
own personal forks of the code.  In the author's view, manual-merge mode
should be reserved for disconnected operation.

<h3>4.1 Autosync Workflow</h3>

<ol>
<li>
Establish a local repository using either the <b>new</b> command
to start a new project, or the <b>clone</b> command to make a clone
of a repository for an existing project. 
</li>

<li>
Establish one or more source trees by changing your working directory
to where you want the root of the source tree to be, then issuing
the <b>open</b> command with the name of the repository file as its
argument.
</li>

<li>
The <b>open</b> command in the previous step populates your local source
tree with a copy of the latest check-in.  Usually this is what you want.
In the rare cases where it is not, use the <b>update</b> command to
switch to a new check-in.  Use the <b>timeline</b> or <b>leaves</b> commands
to identify alternative check-ins to switch to.
</li>

<li>
Edit the code.  Add new files to the source tree using the <b>add</b>
command.  Omit files from future check-ins using the <b>rm</b> command.
(Even when you remove files from future check-ins, those files continue
to exist in historical check-ins.)  Test your changes.
</li>

<li>
Create a new check-in using the <b>commit</b> command.  You will be prompted
for a check-in comment and also for your GPG key if you have GPG installed.
The commit copies the edits you have made in your local source
tree into your local repository.  After your commit completes, fossil will
automatically <b>push</b> your changes back to the server
you cloned from or whatever server you most recently synced with.
</li>

<li>
When your coworkers make their own changes, you can merge those changes
into your local local source tree using the <b>update</b> command.  
In autosync mode, <b>update</b> will first go back to the server you
cloned from or with which you most recently synced, and pull down all
recent changes into your local repository.  Then it will merge recent
changes into your local source tree.  If you do an <b>update</b> and
find that it messes something up in your source tree (perhaps a co-worker
checked in incompatible changes) you can use the <b>undo</b> command 
to back out the changes.
</li>

<li>
Repeat all of the above until you have generated great software.
</li>
</ol>

<h3>4.2 Manual-Merge Workflow</h3>

When autosync is disabled, the <b>commit</b> command is decoupled from
<b>push</b> and the <b>update</b> command is decoupled from <b>pull</b>.
That means you have to do a few extra steps in order to accomplish the
<b>push</b> and <b>pull</b> tasks manually.

<ol>
<li>
Establish a local repository using either the <b>new</b> command
to start a new project, or the <b>clone</b> command to make a clone
of a repository for an existing project.   The default setting for
a new repository is with autosync on, so you will need to turn it off
using the <b>setting autosync off</b> command with a <b>-R</b> option
to specify the repository.
</li>

<li>
Establish one or more source trees by changing your working directory
to where you want the root of the source tree to be, then issuing
the <b>open</b> command with the name of the repository file as its
argument.
</li>

<li>
The <b>open</b> command in the previous step populates your local source
tree with a copy of the latest check-in.  Usually this is what you want.
In the rare cases where it is not, use the <b>update</b> command to
switch to a new check-in.  Use the <b>timeline</b> or <b>leaves</b> commands
to identify alternative check-ins to switch to.
</li>

<li>
Edit the code.  Add new files to the source tree using the <b>add</b>
command.  Omit files from future check-ins using the <b>rm</b> command.
(Even when you remove files from future check-ins, those files continue
to exist in historical check-ins.)  Test your changes.
</li>

<li>
Create a new check-in using the <b>commit</b> command.  You will be prompted
for a check-in comment and also for your GPG key if you have GPG installed.
The commit copies the edits you have made in your local source
tree into your local repository.
</li>

<li>
Use the <b>push</b> command to push your changes out to a server
where your co-workers can access them.
</li>

<li>
When co-workers make their own changes, use the <b>pull</b> command
to pull those changes into your local repository.  Note that <b>pull</b>
does not move the changes into your local source tree, only into your
local repository.
</li>

<li>
Once changes are in your local repository, use
use the <b>update</b> command to merge them to your local source tree.
If you merge in some changes and find that the changes do not work out
or are not to your liking, you can back out the changes using the
<b>undo</b> command.
</li>

<li>
If two or more people ran "commit" against the same baseline, this will
result in a [./branching.wiki | fork] which you may want to resolve by
running <b>merge</b> followed by another <b>commit</b>.
</li>

<li>
Repeat all of the above until you have generated great software.
</li>
</ol>

<h2>5.0 Setting Up A Fossil Server</h2>

With other configuration management software, setting up a server is
a lot of work and normally takes time, patience, and a lot of system
knowledge.  Fossil is designed to avoid this frustration.  Setting up
a server with fossil is ridiculously easy.  You have three options:</p>

<ol>
<li><b><a name="saserv">S</a>etting up a stand-alone server</b>

From within your source tree just use the <b>server</b> command and
fossil will start listening for incoming requests on TCP port 8080.
You can point your web browser at <a href="http://localhost:8080/">
http://localhost:8080/</a> and begin exploring.  Or your coworkers
can do pushes or pulls against your server.  Use the <b>--port</b>
option to the server command to specify a different TCP port.  If
you do not have a local source tree, use the <b>-R</b> command-line
option to specify the repository file.

A stand-alone server is a great way to set of transient connections
between coworkers for doing quick pushes or pulls.  But you can also
set up a permanent stand-alone server if you prefer.  Just make
arrangements for fossil to be launched with appropriate arguments
after every reboot.

If you just want a server to browse the built-in fossil website
locally, use the <b>ui</b> command in place of <b>server</b>.  The
<b>ui</b> command starts up a local server too, but it also takes
the additional step of automatically launching your webbrowser and
pointing at the new server.
</li>

<li><b>Setting up a CGI server</b>

If you have a web-server running on your machine already, you can
set up fossil to be run from CGI.  Simply create an executable script
that looks something like this:

<blockquote><pre>
#!/usr/local/bin/fossil
repository: /home/me/bigproject.fossil
</pre></blockquote>

Edit this script to use whatever pathnames are appropriate for
your project.  Then point your web browser at the script and off you
go.  The [./selfhost.wiki | self-hosting fossil repositories] are
all set up this way.</li>

<li><b>Setting up an inetd server</b>

If you have inetd or xinetd running on your system, you can set
those services up to launch fossil to deal with inbound TCP/IP connections
on whatever port you want.  Set up inetd or xinetd to launch fossil
like this:

<blockquote><pre>
/usr/local/bin/fossil http /home/me/bigproject.fossil
</pre></blockquote>

As before, change the filenames to whatever is appropriate for
your system.  You can have fossil run as any user that has write
permission on the repository and on the directory that contains the
repository.  But it is safer to run fossil as root.  When fossil
sees that it is running as root, it automatically puts itself into
a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> and
drops all privileges prior to reading any information from the client.
Since fossil is a stand-alone program, you do not need to put anything
in the chroot jail with fossil in order for it to do its job.
</li>
</ol>

<h2>6.0 Review Of Key Concepts</h2>

<ul>
<li>The <b>fossil</b> program is a self-contained stand-alone executable.

Changes to www/faq.tcl.

95
96
97
98
99
100
101

102
103
104
105
106
107
108
}



#############################################################################
# Code to actually generate the FAQ
#

puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n"
puts "<p>Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n"

puts {<ol>}
for {set i 1} {$i<$cnt} {incr i} {
  puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>"
}







>







95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
}



#############################################################################
# Code to actually generate the FAQ
#
puts "<title>Fossil FAQ</title>"
puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n"
puts "<p>Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n"

puts {<ol>}
for {set i 1} {$i<$cnt} {incr i} {
  puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>"
}

Changes to www/faq.wiki.


1
2
3
4
5
6
7

<h1 align="center">Frequently Asked Questions</h1>

<p>Note: See also <a href="qandc.wiki">Questions and Criticisms</a>.

<ol>
<li><a href="#q1">What GUIs are available for fossil?</a></li>
<li><a href="#q2">What is the difference between a "branch" and a "fork"?</a></li>
>







1
2
3
4
5
6
7
8
<title>Fossil FAQ</title>
<h1 align="center">Frequently Asked Questions</h1>

<p>Note: See also <a href="qandc.wiki">Questions and Criticisms</a>.

<ol>
<li><a href="#q1">What GUIs are available for fossil?</a></li>
<li><a href="#q2">What is the difference between a "branch" and a "fork"?</a></li>

Changes to www/index.wiki.

3
4
5
6
7
8
9

10
11
12
13
14
15
16
..
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64






















65
66
67
68
69
70
71
72



73
74
75
76
77
78
79
..
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
<table border="1" align="right" cellpadding="10">
<tr><td>
<h2>Quick Links</h2>
<ul>
<li> [./quickstart.wiki | Quick Start]
<li> [http://www.fossil-scm.org/download.html | Download]
<li> [./build.wiki | Install]

<li> [/timeline | Recent changes]
<li> [./faq.wiki | FAQ]
</ul>
<center><img src="fossil.gif"></center>
</td></tr>
</table>

................................................................................

<center>
<font size=5><b>Fossil:</b><i>
Simple, high-reliability, distributed software configuration management
</i></font>
</center>

<h3>Feature Summary:</h3>
  *  [./concepts.wiki | Distributed version control]
  *  Integrated, [./bugtheory.wiki | distributed bug tracking] and 
     [./wikitheory.wiki | distributed wiki].
  *  Built-in [./webui.wiki | web interface] that supports deep
     archaeological digs through the project history.
  *  All network communication via HTTP with 
     [./quickstart.wiki#proxy | proxy support]
     so that everything works from behind restrictive firewalls.
     Communication is [./stats.wiki | bandwidth-efficient].
  *  Everything (client, server, and utilities) is included in a 
     single self-contained executable - [./build.wiki | trivial to install].
  *  Server runs as [./quickstart.wiki#cgiserver | CGI], using
     [./quickstart.wiki#inetdserver | inetd/xinetd]
     or using its own 
     [./quickstart.wiki#serversetup | built-in, stand alone web server].
  *  Flexible workflow:<ul>
    <li>Disconnected, distributed development like
      <a href="http://kerneltrap.org/node/4982">git</a>,
      <a href="http://www.monotone.ca/">monotone</a>,
      <a href="http://www.selenic.com/mercurial/wiki/index.cgi">mercurial</a>,
      and <a href="http://www.bitkeeper.com/">bitkeeper</a>
    <li>Or, client/server operation like 
      <a href="http://www.nongnu.org/cvs/">CVS</a> and
      <a href="http://subversion.tigris.org/">subversion</a>,
    <li>Or, operations on local repositories,
    <li>Or, all of the above at the same time</ul>
  *  [./selfhost.wiki | Self-hosting] since 2007-07-21.
  *  An entire project contained in single 
     [./stats.wiki | compact] disk file
     (an [http://www.sqlite.org/ | SQLite] database.)
  *  Uses an [./fileformat.wiki | enduring file format] that is 
     designed to be readable, searchable, and extensible by people
     not yet born.
  *  Automatic [./selfcheck.wiki | self-check]
     on repository changes makes it exceedingly
     unlikely that data will ever be lost because of a software bug.
  *  License: [../COPYRIGHT-GPL2.txt | GPL]

<h3>User Links:</h3>























  *  [./faq.wiki | FAQ]
  *  The [./concepts.wiki | concepts] behind fossil
  *  [./quickstart.wiki | Quick Start] guide to using fossil
  *  [./reviews.wiki | Testimonials] from fossil users.
  *  [./qandc.wiki | Questions &amp; Criticisms] directed at fossil.
  *  [./build.wiki | Building And Installing]
  *  Fossil supports [./embeddeddoc.wiki | embedded documentation]
     that is versioned along with project source code.



  *  A tutorial on [./branching.wiki | branching], what it means and how
     to do it using fossil.
  *  The [./selfcheck.wiki | automatic self-check] mechanism
     helps insure project integrity.
  *  Fossil contains a [./wikitheory.wiki | built-in wiki].
  *  There is a
    [http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users | mailing list]
................................................................................
     available for discussing fossil issues.
  *  [./stats.wiki | Performance statistics] taken from real-world projects
     hosted on fossil.
  *  How to [./shunning.wiki | delete content] from a fossil repository.
  *  Some (unfinished but expanding) extended
      [./reference.wiki | reference documentation] for the fossil command line.

<h3>Developer Links:</h3>

  *  [./pop.wiki | Principles Of Operation]
  *  The [./fileformat.wiki | file format] used by every content
     file stored in the repository.
  *  The [./delta_format.wiki | format of deltas] used to
     efficiently store changes between file revisions.
  *  The [./delta_encoder_algorithm.wiki | encoder algorithm] used to
     efficiently generate deltas.
  *  The [./sync.wiki | synchronization protocol].







>







 







|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>



<




>
>
>







 







|









3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
..
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

91
92
93
94
95
96
97
98
99
100
101
102
103
104
...
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
<table border="1" align="right" cellpadding="10">
<tr><td>
<h2>Quick Links</h2>
<ul>
<li> [./quickstart.wiki | Quick Start]
<li> [http://www.fossil-scm.org/download.html | Download]
<li> [./build.wiki | Install]
<li> [../COPYRIGHT-GPL2.txt | License]
<li> [/timeline | Recent changes]
<li> [./faq.wiki | FAQ]
</ul>
<center><img src="fossil.gif"></center>
</td></tr>
</table>

................................................................................

<center>
<font size=5><b>Fossil:</b><i>
Simple, high-reliability, distributed software configuration management
</i></font>
</center>

<h3>Why Use Fossil?</h3>

There are plenty of open-source version control systems available on the
internet these days. What makes Fossil worthy of attention?

  1.  <b>Bug Tracking And Wiki</b> -
      In addition to doing [./concepts.wiki | distributed version control]
      like Git and Mercurial,
      Fossil also supports [./bugtheory.wiki | distributed bug tracking] and
      [./wikitheory.wiki | distributed wiki] all in a single
      integrated package.

  2.  <b>Web Interface</b> - 
      Fossil has a built-in and easy-to-use [./webui.wiki | web interface]
      that simplifies project tracking and promotes situational awareness.
      Simply type "fossil&nbsp;ui" from within any check-out and Fossil
      automatically opens your web browser in a page that gives detailed
      history and status information on that project.

  3.  <b>Autosync</b> -
      Fossil supports [./concepts.wiki#workflow | "autosync" mode]
      which helps to keep projects moving
      forward by reducing the amount of needless 
      [./branching.wiki | forking and merging] often
      associated distributed projects.

  4.  <b>Self-Contained</b> -
      Fossil is a single stand-alone executable that contains everything
      needed to do configuration management.
      Installation is trivial: simply download a 
      <a href="http://www.fossil-scm.org/download.html">precompiled binary</a>
      for Linux, Mac, or Windows and put it on your $PATH.
      [./build.wiki | Easy-to-compile source code] is available for
      users on other platforms.  Fossil sources are also mostly self-contained,
      requiring only the "zlib" library and the standard C library to build.

  5.  <b>Simple Networking</b> -
      Fossil uses plain old HTTP (with
      [./quickstart.wiki#proxy | proxy support])
      for all network communications, meaning that it works fine from behind
      restrictive firewalls.  The protocol is
      [./stats.wiki | bandwidth efficient] to the point that Fossil can be
      used comfortably over a dial-up internet connection.

  6.  <b>CGI Enabled</b> -
      No server is required to use fossil.  But a
      server does make collaboration easier.  Fossil supports three different
      yet simple [./quickstart.wiki#serversetup | server configurations].
      The most popular is a 2-line CGI script.  This is the approach
      used by the [./selfhost.wiki | self-hosting fossil repositories].

  7.  <b>Robust &amp; Reliable</b> -
      Fossil stores content in an SQLite database so that transactions are
      atomic even if interrupted by a power loss or system crash.  Furthermore,
      automatic [./selfcheck.wiki | self-checks] verify that all aspects of
      the repository are consistent prior to each commit.  In over two years
      of operation, no work has ever been lost after having been committed to
      a Fossil repository.

<hr>
<h3>Links For Fossil Users:</h3>

  *  [./reviews.wiki | Testimonials] from satisfied fossil users.
  *  [./faq.wiki | FAQ]
  *  The [./concepts.wiki | concepts] behind fossil
  *  [./quickstart.wiki | Quick Start] guide to using fossil

  *  [./qandc.wiki | Questions &amp; Criticisms] directed at fossil.
  *  [./build.wiki | Building And Installing]
  *  Fossil supports [./embeddeddoc.wiki | embedded documentation]
     that is versioned along with project source code.
  *  Fossil uses an [./fileformat.wiki | enduring file format] that is 
     designed to be readable, searchable, and extensible by people
     not yet born.
  *  A tutorial on [./branching.wiki | branching], what it means and how
     to do it using fossil.
  *  The [./selfcheck.wiki | automatic self-check] mechanism
     helps insure project integrity.
  *  Fossil contains a [./wikitheory.wiki | built-in wiki].
  *  There is a
    [http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users | mailing list]
................................................................................
     available for discussing fossil issues.
  *  [./stats.wiki | Performance statistics] taken from real-world projects
     hosted on fossil.
  *  How to [./shunning.wiki | delete content] from a fossil repository.
  *  Some (unfinished but expanding) extended
      [./reference.wiki | reference documentation] for the fossil command line.

<h3>Links For Fossil Developer:</h3>

  *  [./pop.wiki | Principles Of Operation]
  *  The [./fileformat.wiki | file format] used by every content
     file stored in the repository.
  *  The [./delta_format.wiki | format of deltas] used to
     efficiently store changes between file revisions.
  *  The [./delta_encoder_algorithm.wiki | encoder algorithm] used to
     efficiently generate deltas.
  *  The [./sync.wiki | synchronization protocol].

Changes to www/selfcheck.wiki.

1
2
3
4
5
6
7


8
9

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
..
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94




























<nowiki>
<h1 align="center">
Fossil Repository Integrity Self-Checks
</h1>

<p>
Even though fossil is a relatively new project and still contains


many bugs, it is designed with features to give it a high level
of integrity so that you can have confidence that you will not

lose your files.  This note describes the defensive measures that
fossil uses to help prevent file loss due to bugs.
</p>

<p><i>Follow-up as of 2007-11-24:</i>
<i>Reiterated on 2008-05-16 and again on 2008-10-04:</i>
Fossil has been hosting itself and many other projects for
months now.  Many bugs have been encountered.  But, thanks in large
part to the defensive measures described here, no data has been
lost.  The integrity checks are doing their job well.</p>

<h2>Atomic Check-ins With Rollback</h2>

<p>
The fossil repository is an
<a href="http://www.sqlite.org/">SQLite version 3</a> database file.  
SQLite is very mature and stable and has been in wide-spread use for many
years, so we are confident it will not cause repository
corruption.  SQLite
databases do not corrupt even if a program or system crash or power
failure occurs in the middle of the update.  If some kind of crash
does occur in the middle of a change, then all the changes are rolled
back the next time that the database is accessed.
</p>

<p>
A check-in operation in fossil makes many changes to the repository
database.  But all these changes happen within a single transaction.
If something goes wrong in the middle of the commit, then the transaction
is rolled back and the database is unchanged.
</p>

<h2>Verification Of Delta Encodings Prior To Transaction Commit</h2>

<p>
The content files that comprise the global state of a fossil respository
are stored in the repository as a tree.  The leaves of the tree are
stored as zlib-compressed BLOBs.  Interior nodes are deltas from their
decendants.  A lot of encoding is going on.  There is
zlib-compression which is relatively well-tested but still might
cause corruption if used improperly.  And there is the relatively
new delta-encoding mechanism designed expressly for fossil.  We want
to make sure that bugs in these encoding mechanisms do not lead to
loss of data.
</p>

<p>
To increase our confidence that everything in the repository is
recoverable, fossil makes sure it can extract an exact replicate
of every content file that it changes just prior to transaction
commit.  So during the course of check-in (or other repository
operation) many different files
in the repository might be modified.  Some files are simply
compressed.  Other files are delta encoded and then compressed.
................................................................................
While all this is going on, fossil makes a record of every file
that is encoded and the SHA1 hash of the original content of that
file.  Then just before transaction commit, fossil re-extracts
the original content of all files that were written, computes
the SHA1 checksum again, and verifies that the checksums match.
If anything does not match up, an error
message is printed and the transaction rolls back.
</p>

<p>
So, in other words, fossil always checks to make sure it can
re-extract a file before it commits a change to that file.
Hence bugs in fossil are unlikely to corrupt the repository in
a way that prevents us from extracting historical versions of 
files.
</p>

<h2>Checksum Over All Files In A Check-in</h2>

<p>
Manifest artifacts that define a check-in have two fields (the
R-card and Z-card) that record MD5 hashs of the manifest itself
and of all other files in the manifest.  Prior to any check-in
commit, these checksums are verified to ensure that the check-in
checked in agrees exactly with what is on disk.  Similarly,
the repository checksum is verified after a checkout to make
sure that the entire repository was checked out correctly.
Note that these added checks use a different hash (MD5 instead
of SHA1) in order to avoid common-mode failures in the hash
algorithm implementation.
</p>




























<
<
|
<

<
<
>
>
|
|
>
|
|
<

<
<

|





<









<

<




<



<









<

<







 







<

<





<



<










<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>


1

2


3
4
5
6
7
8
9

10


11
12
13
14
15
16
17

18
19
20
21
22
23
24
25
26

27

28
29
30
31

32
33
34

35
36
37
38
39
40
41
42
43

44

45
46
47
48
49
50
51
..
52
53
54
55
56
57
58

59

60
61
62
63
64

65
66
67

68
69
70
71
72
73
74
75
76
77

78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105


<title>Fossil Repository Integrity Self-Checks</title>




<h1 align="center">Fossil Repository Integrity Self-Checks</h1>

Fossil is designed with features to give it a high level
of integrity so that users can have confidence that content will
never be mangled or lost by Fossil.
This note describes the defensive measures that
Fossil uses to help prevent information loss due to bugs.




Fossil has been hosting itself and many other projects for
years now.  Many bugs have been encountered.  But, thanks in large
part to the defensive measures described here, no data has been
lost.  The integrity checks are doing their job well.</p>

<h2>Atomic Check-ins With Rollback</h2>


The fossil repository is an
<a href="http://www.sqlite.org/">SQLite version 3</a> database file.  
SQLite is very mature and stable and has been in wide-spread use for many
years, so we are confident it will not cause repository
corruption.  SQLite
databases do not corrupt even if a program or system crash or power
failure occurs in the middle of the update.  If some kind of crash
does occur in the middle of a change, then all the changes are rolled
back the next time that the database is accessed.



A check-in operation in fossil makes many changes to the repository
database.  But all these changes happen within a single transaction.
If something goes wrong in the middle of the commit, then the transaction
is rolled back and the database is unchanged.


<h2>Verification Of Delta Encodings Prior To Transaction Commit</h2>


The content files that comprise the global state of a fossil respository
are stored in the repository as a tree.  The leaves of the tree are
stored as zlib-compressed BLOBs.  Interior nodes are deltas from their
decendants.  A lot of encoding is going on.  There is
zlib-compression which is relatively well-tested but still might
cause corruption if used improperly.  And there is the relatively
new delta-encoding mechanism designed expressly for fossil.  We want
to make sure that bugs in these encoding mechanisms do not lead to
loss of data.



To increase our confidence that everything in the repository is
recoverable, fossil makes sure it can extract an exact replicate
of every content file that it changes just prior to transaction
commit.  So during the course of check-in (or other repository
operation) many different files
in the repository might be modified.  Some files are simply
compressed.  Other files are delta encoded and then compressed.
................................................................................
While all this is going on, fossil makes a record of every file
that is encoded and the SHA1 hash of the original content of that
file.  Then just before transaction commit, fossil re-extracts
the original content of all files that were written, computes
the SHA1 checksum again, and verifies that the checksums match.
If anything does not match up, an error
message is printed and the transaction rolls back.



So, in other words, fossil always checks to make sure it can
re-extract a file before it commits a change to that file.
Hence bugs in fossil are unlikely to corrupt the repository in
a way that prevents us from extracting historical versions of 
files.


<h2>Checksum Over All Files In A Check-in</h2>


Manifest artifacts that define a check-in have two fields (the
R-card and Z-card) that record MD5 hashs of the manifest itself
and of all other files in the manifest.  Prior to any check-in
commit, these checksums are verified to ensure that the check-in
checked in agrees exactly with what is on disk.  Similarly,
the repository checksum is verified after a checkout to make
sure that the entire repository was checked out correctly.
Note that these added checks use a different hash (MD5 instead
of SHA1) in order to avoid common-mode failures in the hash
algorithm implementation.



<h2>Checksums On Control Artifacts And Deltas</h2>

Every [./fileformat.wiki | control artifact] in a fossil repository
contains a "Z-card" bearing an MD5 checksum over the rest of the
artifact.  Any mismatch causes the control artifact to be ignored.

The [./delta_format.wiki | file delta format] includes a 32-bit
checksum of the target file.  Whenever a file is reconstructed from
a delta, that checksum is verified to make sure the reconstruction
was done correctly.

<h2>Reliability Versus Performance</h2>

Some version control systems make a big deal out of being "high performance"
or the "fastest version control system".  Fossil makes no such claims and has
no such ambition.  Indeed, profiling indicates that fossil bears a
substantial performance cost for
doing all of the checksumming and verification outlined above.
Fossil takes the philosophy of the
<a href="http://en.wikipedia.org/wiki/The_Tortoise_and_the_Hare">tortoise</a>:
reliability is more important than raw speed.  The developers of
fossil see no merit in getting the wrong answer quickly.

Fossil may not be the fastest versioning system, but it is "fast enough".
Fossil runs quickly enough to stay out of the developers way.  
Most operations complete in under a second.

Changes to www/stats.wiki.


1
2
3
4
5
6
7

<h1 align="center">Performance Statistics</h1>

The questions will inevitably arise:  How does Fossil perform? 
Does it use a lot of disk space or bandwidth?  Is it scalable?

In an attempt to answers these questions, this report looks at five
projects that use fossil for configuration management and examines how
>







1
2
3
4
5
6
7
8
<title>Fossil Performance</title>
<h1 align="center">Performance Statistics</h1>

The questions will inevitably arise:  How does Fossil perform? 
Does it use a lot of disk space or bandwidth?  Is it scalable?

In an attempt to answers these questions, this report looks at five
projects that use fossil for configuration management and examines how