Fossil

  @ 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>.

<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

<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

<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>
since 2007-07-21 on
<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>

    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

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>

<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