Fossil

Check-in [c8893c69]
Login

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

Overview
Comment:Documentation updates.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:c8893c69ac8ffda38d4891e9b13c4d6eef22f4fb
User & Date: drh 2008-10-05 01:03:25
Context
2008-10-05
12:34
Get cloning working for local files without the use of network I/O. Ticket [b3482d580e]. check-in: 9236f0c0 user: drh tags: trunk
01:03
Documentation updates. check-in: c8893c69 user: drh tags: trunk
2008-10-04
20:40
The "configuration" command will now sync ticket report formats, shunned UUIDs, and user information (but not user passwords). Added the "config merge" method. Fix an initialization bug that was given Admin privilege to anonymous by default. check-in: bf75ea98 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/wiki.c.

541
542
543
544
545
546
547
548

549
550
551
552
553
554
555
  @ by a tab.  The number is significant and becomes the number shown
  @ in the rendered enumeration item.  Only a single level of enumeration
  @ list is supported by wiki.  For nested enumerations or for
  @ enumerations that count using letters or roman numerials, use HTML.</p>
  @ <li> <p><b>Indented Paragraphs</b>.
  @ Any paragraph that begins with two or more spaces or a tab and
  @ which is not a bullet or enumeration list item is rendered 
  @ indented.  Only a single level of indentation is supported by</p>

  @ <li> <p><b>Hyperlinks</b>.
  @ Text within square brackets ("[...]") becomes a hyperlink.  The
  @ target can be a wiki page name, the UUID of a check-in or ticket,
  @ the name of an image, or a URL.  By default, the target is displayed
  @ as the text of the hyperlink.  But you can specify alternative text
  @ after the target name separated by a "|" character.</p>
  @ <li> <p><b>HTML</b>.







|
>







541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
  @ by a tab.  The number is significant and becomes the number shown
  @ in the rendered enumeration item.  Only a single level of enumeration
  @ list is supported by wiki.  For nested enumerations or for
  @ enumerations that count using letters or roman numerials, use HTML.</p>
  @ <li> <p><b>Indented Paragraphs</b>.
  @ Any paragraph that begins with two or more spaces or a tab and
  @ which is not a bullet or enumeration list item is rendered 
  @ indented.  Only a single level of indentation is supported by wiki; use
  @ HTML for deeper indentation.</p>
  @ <li> <p><b>Hyperlinks</b>.
  @ Text within square brackets ("[...]") becomes a hyperlink.  The
  @ target can be a wiki page name, the UUID of a check-in or ticket,
  @ the name of an image, or a URL.  By default, the target is displayed
  @ as the text of the hyperlink.  But you can specify alternative text
  @ after the target name separated by a "|" character.</p>
  @ <li> <p><b>HTML</b>.

Changes to www/embeddeddoc.wiki.

1
2

3
4
5
6
7
8
9
10
..
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
<h1>Managing Project Documentation</h1>


Fossil provides a built-in [/wiki | wiki] that can be used to store the
documentation for a project.  This is sufficient for many projects.
If your project is well-served by wiki documentation, then you
need read no further.

But fossil also supports embedding project documentation as
files in the source tree.  There are several potential advantages
to this approach:
................................................................................
editing looks like before you check it in.

Finally, the <i>&lt;filename&gt;</i> element of the URL is the full
pathname of the documentation file starting from the root of the source
tree.

The mimetype (and thus the rendering) of documentation files is 
determined by the file suffix.  Fossil currently understands the
following file suffixes or embedded documents:

  *  .css
  *  .gif
  *  .htm
  *  .html
  *  .jpg
  *  .jpeg
  *  .png
  *  .txt
  *  .wiki


Documentation files whose names end in ".wiki" use the 
[/wiki_rules | same markup as wiki pages] -
a safe subset of HTML together with some rules for paragraph
breaks, lists, and hyperlinks.  The ".wiki" and ".txt" pages
are rendered with the standard fossil header and footer added.
All other mimetypes are delivered directly to the requesting
web browser without interpretation, additions, or changes.

The list of allowed suffixes for embedded documents is likely to
grow and become user-configurable in future releases of fossil.

<h2>Examples</h2>

This file that you are currently reading is an example of
embedded documentation.  The name of this file in the fossil
source tree is "<b>www/embeddeddoc.wiki</b>".
You are perhaps looking at this
file using the URL:  

[http://www.fossil-scm.org/index.html/doc/tip/www/embeddeddoc.wiki].

The first part of this path, the "[http://www.fossil-scm.org/index.html]",
is the base URL.  You might have originally typed:
[http://www.fossil-scm.org/].  The web server at the www.fossil-scm.org
site automatically redirects such links by appending "index.html".  The
"index.html" file on www.fossil-scm.org is really a CGI script
(do not be mislead by the name) which runs the fossil web service in


>
|







 







|
|
<
<
<
<
<
<
<
<
<
<
>









<
<
<






|
>
|







1
2
3
4
5
6
7
8
9
10
11
..
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
<h1>Managing Project Documentation</h1>

Fossil provides a built-in <a href="wikitheory.wiki">wiki</a>
that can be used to store the
documentation for a project.  This is sufficient for many projects.
If your project is well-served by wiki documentation, then you
need read no further.

But fossil also supports embedding project documentation as
files in the source tree.  There are several potential advantages
to this approach:
................................................................................
editing looks like before you check it in.

Finally, the <i>&lt;filename&gt;</i> element of the URL is the full
pathname of the documentation file starting from the root of the source
tree.

The mimetype (and thus the rendering) of documentation files is 
determined by the file suffix.  Fossil currently understands 192
different file suffixes, including all the popular ones such as










".css", ".gif", ".htm", ".html", ".jpg", ".jpeg", ".png", and ".txt".

Documentation files whose names end in ".wiki" use the 
[/wiki_rules | same markup as wiki pages] -
a safe subset of HTML together with some rules for paragraph
breaks, lists, and hyperlinks.  The ".wiki" and ".txt" pages
are rendered with the standard fossil header and footer added.
All other mimetypes are delivered directly to the requesting
web browser without interpretation, additions, or changes.




<h2>Examples</h2>

This file that you are currently reading is an example of
embedded documentation.  The name of this file in the fossil
source tree is "<b>www/embeddeddoc.wiki</b>".
You are perhaps looking at this
file using the URL:

   [http://www.fossil-scm.org/index.html/doc/tip/www/embeddeddoc.wiki].

The first part of this path, the "[http://www.fossil-scm.org/index.html]",
is the base URL.  You might have originally typed:
[http://www.fossil-scm.org/].  The web server at the www.fossil-scm.org
site automatically redirects such links by appending "index.html".  The
"index.html" file on www.fossil-scm.org is really a CGI script
(do not be mislead by the name) which runs the fossil web service in

Changes to www/fileformat.wiki.

33
34
35
36
37
38
39










40
41
42
43
44
45
46
<li> Clusters </li>
<li> Control Artifacts </li>
<li> Wiki Pages </li>
<li> Ticket Changes </li>
</ul>

<p>These five artifact types are described in the sequel.</p>











<h2>1.0 The Manifest</h2>

<p>A manifest defines a baseline or version of the project
source tree.  The manifest contains a list of artifacts for
each file in the project and the corresponding filenames, as
well as information such as parent baselines, the name of the







>
>
>
>
>
>
>
>
>
>







33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
<li> Clusters </li>
<li> Control Artifacts </li>
<li> Wiki Pages </li>
<li> Ticket Changes </li>
</ul>

<p>These five artifact types are described in the sequel.</p>

<p>In the current implementation (as of 2008-10-04) the artifacts that
make up a fossil repository are stored in in as delta- and zlib-compressed
blobs in an <a href="http://www.sqlite.org/">SQLite</a> database.  This
is an implementation detail and might change in a future release.  For
the purpose of this article "file format" means the format of the artifacts,
not how the artifacts are stored on disk.  It is the artifact format that
is intended to be enduring.  The specifics of how artifacts are stored on
disk, though stable, is not intended to have as long a lifespan as the
artifact format.</p>

<h2>1.0 The Manifest</h2>

<p>A manifest defines a baseline or version of the project
source tree.  The manifest contains a list of artifacts for
each file in the project and the corresponding filenames, as
well as information such as parent baselines, the name of the

Changes to www/index.wiki.

1
2
3
4
5
6
7
8
9
10
11
..
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
<h1>Fossil: Distributed Revision Control, Wiki, and Bug-Tracking</h1>

<p>
Fossil is a new 
<a href="http://en.wikipedia.org/wiki/Revision_control">
distributed software revision control system</a> that includes an integrated
<a href="wikitheory.wiki">wiki</a> and an integrated
<a href="bugtheory.wiki">bug-tracking system</a> all in a single, 
easy-to-use, stand-alone executable.
Fossil is
<a href="http://www.fossil-scm.org/fossil/timeline">self-hosting</a>
................................................................................
<a href="http://www.hwaci.com/cgi-bin/fossil/timeline">two separate servers</a>.
You can download the <a href="../../../timeline">lastest sources</a> and
<a href="build.wiki">compile it yourself</a>.
Or you can grab
<a href="http://www.fossil-scm.org/download.html">precompiled binaries</a>.
</p>

<p>Features Of Fossil:</p>

<ul>

<li>Supports 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>, or
<a href="http://www.bitkeeper.com/">bitkeeper</a>)
or client/server operation (like 
<a href="http://www.nongnu.org/cvs/">CVS</a> or
<a href="http://subversion.tigris.org/">subversion</a>),
or operations on local repositories,
or all three at the same time</li>

<li>Integrated <a href="bugtheory.wiki">bug tracking</a> and 
<a href="wikitheory.wiki">wiki</a>, inspired by
<a href="http://www.cvstrac.org/">CVSTrac</a> and
<a href="http://www.edgewall.com/trac/">Trac</a> but enhanced to
support distributed, disconnected operation.</li>
<li>Built-in web interface that supports deep archaeological digs through
the project history.</li>
<li>All network communication via 
<a href="http://en.wikipedia.org/wiki/HTTP">HTTP</a> with 
<a href="quickstart.wiki#proxy">proxy support</a>
so that everything works from behind restrictive firewalls.</li>
<li>Everything (client, server, and utilities) is included in a 
single self-contained executable - trivial to install</li>
<li>Server runs as <a href="http://www.w3.org/CGI/">CGI</a>, using
<a href="http://en.wikipedia.org/wiki/inetd">inetd</a>/<a
 href="http://www.xinetd.org/">xinetd</a>, or using its own built-in,
standalone web server.</li>
<li>An entire project contained in single disk file (which also
happens to be an <a href="http://www.sqlite.org/">SQLite</a> database.)</li>
<li>Trivial to setup and administer</li>
<li>Files and versions are identified by their
<a href="http://en.wikipedia.org/wiki/SHA-1">SHA1</a> signature.</a>
Any unique prefix is sufficient to identify a file
or version - usually the first 4 or 5 characters suffice.</li>
<li>The <a href="fileformat.wiki">file format</a> designed to be enduring.
It is deliberately kept simple, requiring nothing more complex
than a text editor and an SHA1 checksum generator to encode or decode.</li>
<li>Automatic <a href="selfcheck.wiki">self-check</a>
on repository changes makes it exceedingly
unlikely that data will ever be lost because of a software bug.</li>
</ul>

<p>Objectives Of Fossil:</p>

<ul>
<li>Fossil should be ridiculously easy to 
<a href="build.wiki">install</a> and 
<a href="quickstart.wiki">operate</a>.</li>
<li>With fossil, it should be possible (and 
<a href="quickstart.wiki#serversetup">easy</a>) to set up a project
on an inexpensive shared-hosting ISP
(example: <a href="http://www.he.net/hosting.html">Hurricane Electric</a>)
that provides nothing more than web space and CGI capability.
Here is <a href="http://www.hwaci.com/cgi-bin/fossil/timeline">a demo</a>.</li>
<li>Fossil should provide in-depth historical and status information about the
project through a web interface</li>
<li>Fossil should provide an historical record of a project that endures
for decades or centuries and across multiple generations of hardward 
and software.</li>
<li>Fossil should be easily adaptable to different workflows.  Fossil
implements mechanism, not policy.</li>
</ul>

<p>User Links:</p>

<ul>
<li>The <a href="concepts.wiki">concepts</b> behind fossil</li>
<li><a href="build.wiki">Building And Installing</a></li>



|







 







|


>
|
|
|
|
|
|
|
|
|
<
>
|
|
<
<
<








|
|
|
|
|
|
|
|
<
<
<
<
<
<



<
<
<
<
<
|


<
<
<
<
<
<
<
<
<
<
<
<
<







1
2
3
4
5
6
7
8
9
10
11
..
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
<h1>Fossil: Distributed Revision Control, Wiki, and Bug-Tracking</h1>

<p>
Fossil is a
<a href="http://en.wikipedia.org/wiki/Revision_control">
distributed software revision control system</a> that includes an integrated
<a href="wikitheory.wiki">wiki</a> and an integrated
<a href="bugtheory.wiki">bug-tracking system</a> all in a single, 
easy-to-use, stand-alone executable.
Fossil is
<a href="http://www.fossil-scm.org/fossil/timeline">self-hosting</a>
................................................................................
<a href="http://www.hwaci.com/cgi-bin/fossil/timeline">two separate servers</a>.
You can download the <a href="../../../timeline">lastest sources</a> and
<a href="build.wiki">compile it yourself</a>.
Or you can grab
<a href="http://www.fossil-scm.org/download.html">precompiled binaries</a>.
</p>

<p>Feature Summary:</p>

<ul>
<li>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></li>
<li>Integrated, distributed <a href="bugtheory.wiki">bug tracking</a> and 
<a href="wikitheory.wiki">wiki</a>.</li>



<li>Built-in web interface that supports deep archaeological digs through
the project history.</li>
<li>All network communication via 
<a href="http://en.wikipedia.org/wiki/HTTP">HTTP</a> with 
<a href="quickstart.wiki#proxy">proxy support</a>
so that everything works from behind restrictive firewalls.</li>
<li>Everything (client, server, and utilities) is included in a 
single self-contained executable - trivial to install</li>
<li>Server runs as <a href="quickstart.wiki#cgiserver">CGI</a>, using
<a href="quickstart.wiki#inetdserver">inetd/xinetd</a>
or using its own 
<a href="quickstart.wiki#serversetup">built-in, standalone web server</a>.</li>
<li>An entire project contained in single disk file
(an <a href="http://www.sqlite.org/">SQLite</a> database.)</li>
<li>Uses an <a href="fileformat.wiki">enduring file format</a> that is 
designed to be readable, searchable, and extensible by people not yet born.</li>






<li>Automatic <a href="selfcheck.wiki">self-check</a>
on repository changes makes it exceedingly
unlikely that data will ever be lost because of a software bug.</li>





<li>Ridiculously easy to 
<a href="build.wiki">install</a> and 
<a href="quickstart.wiki">operate</a>.</li>













</ul>

<p>User Links:</p>

<ul>
<li>The <a href="concepts.wiki">concepts</b> behind fossil</li>
<li><a href="build.wiki">Building And Installing</a></li>

Changes to www/quickstart.wiki.

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
    You can omit the <i>repository-filename</i> if you are within
    a checked-out local tree.  This server uses port 8080 by default
    but you can specify a different port using the <b>-port</b> command.</p>

    <p>Command-line servers like this are useful when two people want
    to share a repository on temporary or ad-hoc basis.  For a more
    permanent installation, you should use either the CGI server or the


    inetd server.  To use the CGI server, create a CGI script that
    looks something like this:</p>

    <blockquote><b>
    #!/usr/local/bin/fossil<br>
    repository: /home/proj1/repos1.fossil
    </b></blockquote>

    <p>Adjust the paths in this CGI script to match your installation
    and make sure that repository file at the directory that contains it
    are both readable and writable by the user that CGI scripts run as.
    Then point clients at the CGI script.  That's all there is to it!</p>


    <p>You can also run fossil off of inetd or xinetd.  For an inetd
    installation, make an entry in /etc/inetd.conf that looks something
    like this:</p>

    <blockquote><b>
    80 stream tcp nowait.1000 root /usr/bin/fossil \<br>
        /usr/bin/fossil http /home/proj1/repos1.fossil







>
>
|












>







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
    You can omit the <i>repository-filename</i> if you are within
    a checked-out local tree.  This server uses port 8080 by default
    but you can specify a different port using the <b>-port</b> command.</p>

    <p>Command-line servers like this are useful when two people want
    to share a repository on temporary or ad-hoc basis.  For a more
    permanent installation, you should use either the CGI server or the
    inetd server.
    <a name="cgiserver"></a>
    To use the CGI server, create a CGI script that
    looks something like this:</p>

    <blockquote><b>
    #!/usr/local/bin/fossil<br>
    repository: /home/proj1/repos1.fossil
    </b></blockquote>

    <p>Adjust the paths in this CGI script to match your installation
    and make sure that repository file at the directory that contains it
    are both readable and writable by the user that CGI scripts run as.
    Then point clients at the CGI script.  That's all there is to it!</p>

    <a name="inetdserver"></a>
    <p>You can also run fossil off of inetd or xinetd.  For an inetd
    installation, make an entry in /etc/inetd.conf that looks something
    like this:</p>

    <blockquote><b>
    80 stream tcp nowait.1000 root /usr/bin/fossil \<br>
        /usr/bin/fossil http /home/proj1/repos1.fossil

Changes to www/selfcheck.wiki.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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:</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>








|







8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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>

Changes to www/wikitheory.wiki.

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

<h2>Stand-alone Wiki Pages</h2>

Each wiki page has its own revision history which is independent of
the sequence of baselines (check-ins).  Wiki pages can branch and merge
just like baselines, though as of this writing (2008-07-29) there is
no mechanism in the user interface to support branching and merging.
The currently implementation of the wiki shows the version of the wiki
pages that has the most recent timestamp.

In other words, if two users make unrelated changes to the same wiki
page on separate repositories, then those repositories are synced,
the wiki page will fork.  The web interface will display whichever edit
was checked in last.  The other edit can be found in the history.  The
file format will support merging the branches back together, but there







|







17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

<h2>Stand-alone Wiki Pages</h2>

Each wiki page has its own revision history which is independent of
the sequence of baselines (check-ins).  Wiki pages can branch and merge
just like baselines, though as of this writing (2008-07-29) there is
no mechanism in the user interface to support branching and merging.
The current implementation of the wiki shows the version of the wiki
pages that has the most recent timestamp.

In other words, if two users make unrelated changes to the same wiki
page on separate repositories, then those repositories are synced,
the wiki page will fork.  The web interface will display whichever edit
was checked in last.  The other edit can be found in the history.  The
file format will support merging the branches back together, but there