Fossil

  db_begin_transaction();
  db_initial_setup(1, 1);
  db_end_transaction(0);
  printf("project-id: %s\n", db_get("project-code", 0));
  printf("server-id:  %s\n", db_get("server-code", 0));
  zPassword = db_text(0, "SELECT pw FROM user WHERE login=%Q", g.zLogin);
  printf("admin-user: %s (initial password is \"%s\")\n", g.zLogin, zPassword);
  printf("baseline:   %s\n", db_text(0, "SELECT uuid FROM blob"));
}

/*
** SQL functions for debugging.
**
** The print() function writes its arguments on stdout, but only
** if the -sqlprint command-line option is turned on.

<h1>Bug-Tracking In <a href="index.wiki">Fossil</a></h1>

A bug-report in fossil is called a "ticket".  Tickets are tracked
separately from code check-ins (baselines).

Some other distributed bug-tracking systems store tickets as files within
the source tree and thereby leverage the syncing and merging capabilities
of the versioning system to sync and merge tickets.  This approach is
rejected in fossil for three reasons:

  1.  Check-ins (a.k.a. "baselines") in fossil are immutable.  So if
      tickets were part of the check-in, then there would be no way to add
      new tickets to a check-in as new bugs are discovered.

  2.  Any project of reasonable size and complexity will generate thousands
      and thousands of tickets, and we do not want all those ticket files
      cluttering the source tree.

<code>update</code>, on the other hand, <em>merges</em> edits into the
version you choose (if you choose one; you can default the version.)

Since a version is required, and <b>fossil</b>'s artifact IDs are
fairly long, there are two good ways to refer to the version.  You can
use a unique proper prefix of the version (six or eight characters is
more than enough in most cases) <em>or</em> you can [./cmd_tag.wiki |
tag] your baselines and use the tags for checkouts, reverting,
branching (tags are the best way to branch) and so forth.  Both
methods work throughout fossil.

See also [./cmd_tag.wiki | fossil tag],
[./cmd_revert.wiki | fossil revert],
[./cmd_update.wiki | fossil update],
[./cmd_push.wiki | fossil push],

<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 "baseline".</p>

<p>A "repository" is a database that contains copies of all historical
versions or baselines for a project.  Baselines 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 baselines 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

<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 baseline.  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 baseline.</p>

<p>Fossil automatically generates a manifest whenever you "commit" 
a new baseline.  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
need to do so.</p>

<p>In addition to identifying all files in the baseline, a
manifest also contains a check-in comment, the date and time
when the baseline was established, who created the baseline,
and links to other baselines from which the current baseline
is derived.  There is also a couple of checksums used to verify
the integrity of the baseline.  And the whole manifest might
be PGP clearsigned.</p>

<h3>2.3 Key concepts</h3>

<ul>
<li>A <b>baseline</b> is a set of files arranged
    in a hierarchy.</li>
<li>A <b>repository</b> keeps a record of historical baselines.</li>
<li>Repositories share their changes using <b>push</b>, <b>pull</b>,
    <b>sync</b>, and <b>clone</b>.</li>
<li>A particular version of a particular file is an <b>artifact</b>
    that is identified by an <b>artifact ID</b>.</li>
<li>Artifacts tracked by fossil are inherently immutable.</li>
<li>Fossil automatically generates a <b>manifest</b> file that identifies
    every artifact in a baseline.</li>
<li>The artifact ID of the manifest is the identifier of the baseline.</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

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 baseline.  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 baseline.  Use the <b>timeline</b> or <b>leaves</b> commands
to identify alternative baselines 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 baselines using the <b>rm</b> command.
(Even when you remove files from future baselines, those files continue
to exist in historical baselines.)  Test your changes.
</p></li>

<li><p>
Create a new baseline 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>

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 baseline.  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 baseline.  Use the <b>timeline</b> or <b>leaves</b> commands
to identify alternative baselines 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 baselines using the <b>rm</b> command.
(Even when you remove files from future baselines, those files continue
to exist in historical baselines.)  Test your changes.
</p></li>

<li><p>
Create a new baseline 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.

<ul>
<li>The <b>fossil</b> program is a self-contained stand-alone executable.
    Just put it somewhere on your PATH to install it.</li>
<li>Use the <b>clone</b> or <b>new</b> commands to create a new repository.</li>
<li>Use the <b>open</b> command to create a new source tree.</li>
<li>Use the <b>add</b> and <b>rm</b> or <b>delete</b> commands to add and
    remove files from the local source tree.</li>
<li>Use the <b>commit</b> command to create a new baseline.</li>
<li>Use the <b>update</b> command to merge in changes from others.</li>
<li>The <b>push</b> and <b>pull</b> commands can be used to share changes
    manually, but these things happen automatically in the default
    autosync mode.</li>
</ul>

For example, the <i>&lt;baseurl&gt;</i> for the fossil project itself is
either <b>http://www.fossil-scm.org/fossil</b> or
<b>http://www.hwaci.com/cgi-bin/fossil</b>.
If you launch the web server using the "<b>fossil server</b>" command line,
then the <i>&lt;baseurl&gt;</i> is usually
<b>http://localhost:8080/</b>.

The <i>&lt;version&gt;</i> is any unique prefix of the baseline ID for 
the baseline containing the documentation you want to access.
Or <i>&lt;version&gt;</i> can be one of the keywords "<b>tip</b>" or
"<b>ckout</b>".  The "<b>tip</b>" keyword means to use the most recently
checked-in baseline.  This is useful if you want to see the very latest
version of the documentation.  The "<b>ckout</b>" keywords means to
pull the documentation file from the local source tree on disk, not
from the any versioned baseline.  The "<b>ckout</b>" keyword normally
only works when you start your server using the "<b>fossil server</b>"
or "<b>fossil ui</b>"
command line and is indented to show what the documentation you are currently
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

repository: /fossil/fossil.fossil
</pre></blockquote>

This is one of three ways to set up a 
<a href="quickstart.wiki#serversetup">fossil web server</a>.

The "<b>/tip/</b>" part of the URL tells fossil to use
the documentation files from the baseline that was checked in most
recently.  This file is stored in the fossil source tree under
the name "<b>www/embeddeddoc.wiki</b>" and so that name forms the
last part of the URL.

As I sit writing this documentation file, I am testing my work by
running the "<b>fossil server</b>" command line and viewing
<b>http://localhost:8080/doc/ckout/www/embeddeddoc.wiki</b> in
Firefox.  I am doing this even though I have not yet checked in
the "<b>www/embeddeddoc.wiki</b>" file for the first time.  Using
the special "<b>ckout</b>" version identifier on the "<b>/doc</b>" page
it is easy to make multiple changes to multiple files and see how they all
look together before committing anything to the repository.

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
programmer who created the baseline, the date and time when
the baseline was created, and any check-in comments associated
with the baseline.</p>

<p>
Any artifact in the repository that follows the syntactic rules
of a manifest is a manifest.  Note that a manifest can
be both a real manifest and also a content file, though this
is rare.
</p>

<blockquote>
<i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i>
</blockquote>

<p>
A manifest has zero or more F-cards.  Each F-card defines a file
(other than the manifest itself) which is part of the baseline that
the manifest defines.  There are two, three, or three arguments.
The first argument
is the pathname of the file in the baseline relative to the root
of the project file hierarchy.  No ".." or "." directories are allowed
within the filename.  Space characters are escaped as in C-card
comment text.  Backslash characters and newlines are not allowed
within filenames.  The directory separator character is a forward
slash (ASCII 0x2F).  The second argument to the F-card is the
full 40-character lower-case hexadecimal SHA1 hash of the content
artifact.  The optional 3rd argument defines any special access 
permissions associated with the file.  The only special code currently
defined is "x" which means that the file is executable.  All files are
always readable and writable.  This can be expressed by "w" permission
if desired but is optional.
The optional 4th argument is the name of the same file as it existed in
the parent baseline.  If the name of the file is unchanged from its
parent, then the 4th argument is omitted.
</p>

<p>
A manifest has zero or more N-cards.  Each N card records a name changes
to one of the files in the manifest.  The first argument to the N code is
the name of the file in the parent baseline.  The second argument is the
name of the file in the baseline defined by the manifest.
</p>

<p>
A manifest has zero or one P-cards.  Most manifests have one P-card.
The P-card has a varying number of arguments that
defines other manifests from which the current manifest
is derived.  Each argument is an 40-character lowercase 
hexadecimal SHA1 of the predecessor manifest.  All arguments
to the P-card must be unique to that line.
The first predecessor is the direct ancestor of the manifest.
Other arguments define manifests with which the first was
merged to yield the current manifest.  Most manifests have
a P-card with a single argument.  The first manifest in the
project has no ancestors and thus has no P-card.
</p>

<p>
A manifest may optionally have a single R-card.  The R-card has
a single argument which is the MD5 checksum of all files in 
the baseline except the manifest itself.  The checksum is expressed
as 32-characters of lowercase hexadecimal.   The checksum is
computed as follows:  For each file in the baseline (except for
the manifest itself) in strict sorted lexicographical order, 
take the pathname of the file relative to the root of the
repository, append a single space (ASCII 0x20), the
size of the file in ASCII decimal, a single newline
character (ASCII 0x0A), and the complete text of the file.
Compute the MD5 checksum of the the result.
</p>

without a value is a boolean.</p>

<p>When two or more tags with the same name are applied to the
same artifact, the tag with the latest (most recent) date is
used.</p>

<p>Some tags have special meaning.  The "comment" tag when applied
to a baseline will override the check-in comment of that baseline
for display purposes.</p>

<a name="wikichng"></a>
<h2>4.0 Wiki Pages</h2>

<p>A wiki page is an artifact with a format similar to manifests,
clusters, and control artifacts.  The artifact is divided into

The first thing we need to do is create a fossil repository file:

<verbatim>
stephan@ludo:~/fossil$ fossil new demo.fossil
project-id: 9d8ccff5671796ee04e60af6932aa7788f0a990a
server-id:  145fe7d71e3b513ac37ac283979d73e12ca04bfe
admin-user: stephan (no password set yet!)
baseline:   84e81a150535f031722f815d59c0c5e96ab7f122
</verbatim>

The numbers it spits out are unimportant (they are version
numbers).

Now we have an empty repository file named <tt>demo.fossil</tt>.
There is nothing magical about the extension <tt>.fossil</tt> - it's

artifacts.</p></li>

<li><p>Two repositories for the same project can synchronize
their global states simply by sharing artifacts.  The local
state of repositories is not normally synchronized or
shared.</p></li>

<li><p>Every baseline has a special file at the top-level
named "manifest" which is an index of all other files in
that baseline.  The manifest is automatically created and
maintained by the system.</p></li>

<li><p>The <a href="fileformat.wiki">file formats</a>
used by Fossil are all very simple so that with access
to the original content files, one can easily reconstruct
the content of a baseline without the need for any
special tools or software.</p></li>

    local tree, use <b>update</b>:</p>

    <blockquote>
    <b>fossil update</b> <i>AID</i>
    </blockquote>

    <p>The <i>AID</i> is some unique abbreviation to the 40-character
    artifact identifier (AID) for a particular baseline.  If you omit
    the <i>AID</i> fossil moves you to the
    leaf version of the branch your are currently on.  If your branch
    has multiple leaves, you get an error - you'll have to specify the
    leaf you want using a <i>AID</i> argument.</p>

</blockquote><h2>Branching And Merging</h2><blockquote>

    remaining 38 characters.

<hr><a href="#tof">&#710;</a>
    <a name="rm">Usage: </a><a href="cmd_rm.wiki">fossil rm</a> FILE...    or: fossil del FILE...
    Remove one or more files from the tree.

<hr><a href="#tof">&#710;</a>
    <a name="descendants">Usage: </a><a href="cmd_descendants.wiki">fossil descendants</a> ?BASELINE-ID?
    Find all leaf descendants of the baseline specified or if the argument
    is omitted, of the baseline currently checked out.

<hr><a href="#tof">&#710;</a>
    <a name="diff">Usage: </a><a href="cmd_diff.wiki">fossil diff</a>|gdiff ?-i? ?-r REVISION? FILE...
    Show the difference between the current version of a file (as it
    exists on disk) and that same file as it was checked out.

    diff will show a textual diff while gdiff will attempt to run a

    associated with the named file(s) but otherwise leave the update
    or merge undone.

    A single level of undo/redo is supported.  The undo/redo stack
    is cleared by the commit and checkout commands.

<hr><a href="#tof">&#710;</a>
    <a name="revert">Usage: </a><a href="cmd_revert.wiki">fossil revert</a> ?--yes? ?-r REVISION? FILE
    Revert to the current repository version of FILE, or to
    the version associated with baseline REVISION if the -r flag
    appears.  This command will confirm your operation unless the
    file is missing or the --yes option is used.

<hr><a href="#tof">&#710;</a>
    <a name="server">Usage: </a><a href="cmd_server.wiki">fossil server</a> ?-P|--port TCPPORT? ?REPOSITORY?    Or: fossil ui ?-P|--port TCPPORT? ?REPOSITORY?

    Open a socket and begin listening and responding to HTTP requests on

    the equivalent of running both "push" and "pull" at the same time.
    See the "pull" command for additional information.

<hr><a href="#tof">&#710;</a>
    <a name="tag">Usage: </a><a href="cmd_tag.wiki">fossil tag</a> SUBCOMMAND ...
    Run various subcommands to control tags and properties

    fossil tag add ?--raw? TAGNAME BASELINE ?VALUE?

    Add a new tag or property to BASELINE. The tag will
    be usable instead of a BASELINE in commands such as
    update and merge.

    fossil tag branch ?--raw? ?--nofork? TAGNAME BASELINE ?VALUE?

    A fork will be created so that the new checkin
    is a sibling of BASELINE and identical to it except
    for a generated comment. Then the new tag will
    be added to the new checkin and propagated to
    all direct children.  Additionally all symbolic
    tags of that checkin inherited from BASELINE will
    be cancelled.

    However, if the option --nofork is given, no
    fork will be created and the tag/property will be
    added to BASELINE directly. No tags will be canceled.

    fossil tag cancel ?--raw? TAGNAME BASELINE

    Remove the tag TAGNAME from BASELINE, and also remove
    the propagation of the tag to any descendants.

    fossil tag find ?--raw? TAGNAME

    List all baselines that use TAGNAME

    fossil tag list ?--raw? ?BASELINE?

    List all tags, or if BASELINE is supplied, list
    all tags and their values for BASELINE.

    The option --raw allows the manipulation of all types of
    tags used for various internal purposes in fossil. You
    should not use this option to make changes unless you are
    sure what you are doing.

    If you need to use a tagname that might be confused with
    a hexadecimal baseline or artifact ID, you can explicitly
    disambiguate it by prefixing it with "tag:". For instance:

    fossil update decaf

    will be taken as an artifact or baseline ID and fossil will
    probably complain that no such revision was found. However

    fossil update tag:decaf

    will assume that "decaf" is a tag/branch name.

<hr><a href="#tof">&#710;</a>
    <a name="timeline">Usage: </a><a href="cmd_timeline.wiki">fossil timeline</a> ?WHEN? ?BASELINE|DATETIME? ?-n|--count N?
    Print a summary of activity going backwards in date and time
    specified or from the current date and time if no arguments
    are given.  Show as many as N (default 20) check-ins.  The
    WHEN argument can be any unique abbreviation of one of these
    keywords:

    before
    after
    descendants | children
    ancestors | parents

    The BASELINE can be any unique prefix of 4 characters or more.
    The DATETIME should be in the ISO8601 format.  For
    examples: "2007-08-18 07:21:21".  You can also say "current"
    for the current version or "now" for the current time.

<hr><a href="#tof">&#710;</a>
    <a name="undo">Usage: </a><a href="cmd_undo.wiki">fossil undo</a> ?FILENAME...?
    Undo the most recent update or merge operation.  If FILENAME is

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 Baseline</h2>

<p>
Manifest artifacts that define a baseline 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 baseline
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>

      there is nothing new to learn.  And, though cumbersome, the HTML
      does not need to be used very often so need not be a burden.


<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
page 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