Fossil

<title>How CGI Works In Fossil</title>

<h2>Introduction</h2><blockquote>

CGI or "Common Gateway Interface" is a venerable yet reliable technique for
generating dynamic web content.  This article gives a quick background on how
CGI works and describes how Fossil can act as a CGI service.

This is a "how it works" guide.  This document provides background
information on the CGI protocol so that you can better understand what
is going on behind the scenes.  If you just want to set up Fossil
as a CGI server, see the [./server/ | Fossil Server Setup] page.  Or
if you want to development CGI-based extensions to Fossil, see
the [./serverext.wiki|CGI Server Extensions] page.
</blockquote>
<h2>A Quick Review Of CGI</h2><blockquote>

An HTTP request is a block of text that is sent by a client application
(usually a web browser) and arrives at the web server over a network
connection.  The HTTP request contains a URL that describes the information
being requested.  The URL in the HTTP request is typically the same URL
that appears in the URL bar at the top of the web browser that is making
the request.  The URL might contain a "?" character followed
query parameters.  The HTTP will usually also contain other information
such as the name of the application that made the request, whether or
not the requesting application can accept a compressed reply, POST
parameters from forms, and so forth.

The job of the web server is to interpret the HTTP request and formulate
an appropriate reply.
The web server is free to interpret the HTTP request in any way it wants.
But most web servers follow a similar pattern, described below.
(Note: details may vary from one web server to another.)

Suppose the filename component of the URL in the HTTP request looks like this:

<blockquote><b>/one/two/timeline/four</b></blockquote>

Most web servers will search their content area for files that match
some prefix of the URL.  The search starts with <b>/one</b>, then goes to
<b>/one/two</b>, then <b>/one/two/timeline</b>, and finally
<b>/one/two/timeline/four</b> is checked.  The search stops at the first
match.

Suppose the first match is <b>/one/two</b>.  If <b>/one/two</b> is an
ordinary file in the content area, then that file is returned as static
content.  The "<b>/timeline/four</b>" suffix is silently ignored.

If <b>/one/two</b> is a CGI script (or program), then the web server
executes the <b>/one/two</b> script.  The output generated by
the script is collected and repackaged as the HTTP reply.

Before executing the CGI script, the web server will set up various
environment variables with information useful to the CGI script:
<table border=1 cellpadding=5>
<tr><th>Environment<br>Variable<th>Meaning
<tr><td>GATEWAY_INTERFACE<td>Always set to "CGI/1.0"
<tr><td>REQUEST_URI
    <td>The input URL from the HTTP request.
<tr><td>SCRIPT_NAME
    <td>The prefix of the input URL that matches the CGI script name.
    In this example: "/one/two".
<tr><td>PATH_INFO

The CGI script exits as soon as it generates a single reply.
The web server will (usually) persist and handle multiple HTTP requests,
but a CGI script handles just one HTTP request and then exits.

The above is a rough outline of how CGI works.
There are many details omitted from this brief discussion.
See other on-line CGI tutorials for further information.
</blockquote>
<h2>How Fossil Acts As A CGI Program</h2>
<blockquote>
An appropriate CGI script for running Fossil will look something
like the following:

<blockquote><pre>
#!/usr/bin/fossil
repository: /home/www/repos/project.fossil
</pre></blockquote>

The first line of the script is a
"[https://en.wikipedia.org/wiki/Shebang_%28Unix%29|shebang]"
that tells the operating system what program to use as the interpreter
for this script.  On unix, when you execute a script that starts with
a shebang, the operating system runs the program identified by the
shebang with a single argument that is the full pathname of the script
itself.

With Fossil, terms of PATH_INFO beyond the webpage name are converted into
the "name" query parameter.  Hence, the following two URLs mean
exactly the same thing to Fossil:
<ol type='A'>
<li> [https://fossil-scm.org/home/info/c14ecc43]
<li> [https://fossil-scm.org/home/info?name=c14ecc43]
</ol>

In both cases, the CGI script is called "/fossil".  For case (A),
the PATH_INFO variable will be "info/c14ecc43" and so the
"[/help?cmd=/info|/info]" webpage will be generated and the suffix of
PATH_INFO will be converted into the "name" query parameter, which
identifies the artifact about which information is requested.
In case (B), the PATH_INFO is just "info", but the same "name"
query parameter is set explicitly by the URL itself.
</blockquote>
<h2>Serving Multiple Fossil Repositories From One CGI Script</h2>
<blockquote>
The previous example showed how to serve a single Fossil repository
using a single CGI script.
On a website that wants to serve multiple repositories, one could
simply create multiple CGI scripts, one script for each repository.
But it is also possible to serve multiple Fossil repositories from
a single CGI script.

If the CGI script for Fossil contains a "directory:" line instead of
a "repository:" line, then the argument to "directory:" is the name
of a directory that contains multiple repository files, each ending
with ".fossil".  For example:

<blockquote><pre>
#!/usr/bin/fossil
directory: /home/www/repos
</pre></blockquote>

Suppose the /home/www/repos directory contains files named
<b>one.fossil</b>, <b>two.fossil</b>, and <b>subdir/three.fossil</b>.
Further suppose that the name of the CGI script (relative to the root
of the webserver document area) is "cgis/example2".  Then to
see the timeline for the "three.fossil" repository, the URL would be:
<blockquote>

<b>http://example.com/cgis/example2/subdir/three/timeline</b>

</blockquote>
Here is what happens:
<ol>
<li> The input URI on the HTTP request is
     <b>/cgis/example2/subdir/three/timeline</b>
<li> The web server searches prefixes of the input URI until it finds
     the "cgis/example2" script.  The web server then sets
     PATH_INFO to the "subdir/three/timeline" suffix and invokes the
     "cgis/example2" script.
<li> Fossil runs and sees the "directory:" line pointing to
     "/home/www/repos".  Fossil then starts pulling terms off the
     front of the PATH_INFO looking for a repository.  It first looks
     at "/home/www/resps/subdir.fossil" but there is no such repository.
     So then it looks at "/home/www/repos/subdir/three.fossil" and finds
     a repository.  The PATH_INFO is shortened by removing
     "subdir/three/" leaving it at just "timeline".
<li> Fossil looks at the rest of PATH_INFO to see that the webpage
     requested is "timeline".
</ol>
<a id="cgivar"></a>

The web server sets many environment variables in step 2 in addition
to just PATH_INFO.  The following diagram shows a few of these variables
and their relationship to the request URL:

<pre>
                                       REQUEST_URI
                         ___________________|_______________________
                        /                                           \
      http://example.com/cgis/example2/subdir/three/timeline?c=55d7e1
             \_________/\____________/\____________________/ \______/
                  |            |                 |               |
              HTTP_HOST   SCRIPT_NAME        PATH_INFO      QUERY_STRING
</pre>
</blockquote>
<h2>Additional CGI Script Options</h2>
<blockquote>

The CGI script can have additional options used to fine-tune
Fossil's behavior.  See the [./cgi.wiki|CGI script documentation]
for details.

</blockquote>
<h2>Additional Observations</h2>
<blockquote><ol type="I">
<li><p>
Fossil does not distinguish between the various HTTP methods (GET, PUT,
DELETE, etc).  Fossil figures out what it needs to do purely from the
webpage term of the URI.</p></li>
<li><p>
Fossil does not distinguish between query parameters that are part of the
URI, application/x-www-form-urlencoded or multipart/form-data encoded

converted into CGI, then Fossil creates a separate child Fossil
process to handle each CGI request.</p></li>
<li><p>
Fossil is itself often launched using CGI.  But Fossil can also then
turn around and launch [./serverext.wiki|sub-CGI scripts to implement
extensions].</p></li>
</ol>
</blockquote>

branches identified only by the commit ID currently at its tip, being a
long string of hex digits.  Therefore, Fossil conflates two concepts:
branching as intentional forking and the naming of forks as branches.
They are in fact separate concepts, but since Fossil is intended to be
used primarily by humans, we combine them in Fossil's human user
interfaces.

<blockquote>
<b>Key Distinction:</b> A branch is a <i>named, intentional</i> fork.
</blockquote>

Unnamed forks <i>may</i> be intentional, but most of the time, they're
accidental and left unnamed.

Fossil offers two primary ways to create named, intentional forks,
a.k.a. branches. First:

bad, which is why [./concepts.wiki#workflow|Fossil tries so hard to avoid them], why it warns you
about it when they do occur, and why it makes it relatively [#fix|quick and
painless to fix them] when they do occur.


<h2>Review Of Terminology</h2>

<blockquote><dl>
<dt><b>Branch</b></dt>
<dd><p>A branch is a set of check-ins with the same value for their
"branch" property.</p></dd>
<dt><b>Leaf</b></dt>
<dd><p>A leaf is a check-in with no children in the same branch.</p></dd>
<dt><b>Closed Leaf</b></dt>
<dd><p>A closed leaf is any leaf with the <b>closed</b> tag.  These leaves
are intended to never be extended with descendants and hence are omitted
from lists of leaves in the command-line and web interface.</p></dd>
<dt><b>Open Leaf</b></dt>
<dd><p>A open leaf is a leaf that is not closed.</p></dd>
<dt><b>Fork</b></dt>
<dd><p>A fork is when a check-in has two or more direct (non-merge)
children in the same branch.</p></dd>
<dt><b>Branch Point</b></dt>
<dd><p>A branch point occurs when a check-in has two or more direct (non-merge)
children in different branches.  A branch point is similar to a fork,
except that the children are in different branches.</p></dd>
</dl></blockquote>

Check-in 4 of Figure 3 is not a leaf because it has a child (check-in 5)
in the same branch.  Check-in 9 of Figure 5 also has a child (check-in 10)
but that child is in a different branch, so check-in 9 is a leaf.  Because
of the <b>closed</b> tag on check-in 9, it is a closed leaf.

Check-in 2 of Figure 3 is considered a "fork"

those options.

<h1>CGI Script Options</h1>

The CGI script used to launch a Fossil server will usually look something
like this:

<blockquote><verbatim>
#!/usr/bin/fossil
repository: /home/www/fossils/myproject.fossil
</verbatim></blockquote>

Of course, pathnames will likely be different.  The first line 
(the "[wikipedia:/wiki/Shebang_(Unix)|shebang]")
always gives the name of the Fossil executable.  Subsequent lines are of
the form "<b>property:&nbsp;argument&nbsp;...</b>".
The remainder of this document describes the available properties and
their arguments.

<title>Check-in Names</title>

<table align="right" width="33%">
<tr><td>
<h3>Quick Reference</h3>
<ul>
<li> Hash prefix
<li> Branch name
<li> Tag name
<li> Timestamp:  <i>YYYY-MM-DD HH:MM:SS</i>
<li> <i>tag-name</i> <big><b>:</b></big> <i>timestamp</i>
<li> <b>root <big>:</big></b> <i>branchname</i>
<li> <b>start <big>:</big></b> <i>branchname</i>
<li> <b>merge-in <big>:</big></b> <i>branchname</i>
<li> Special names:
<ul>
<li> <b>tip</b>
<li> <b>current</b>
<li> <b>next</b>
<li> <b>previous</b> or <b>prev</b>
<li> <b>ckout</b> (<a href='./embeddeddoc.wiki'>embedded docs</a> only)
</ul>
</ul>
</td></tr>
</table>

Many Fossil [/help|commands] and [./webui.wiki | web interface] URLs accept
check-in names as an argument.  For example, the "[/help/info|info]" command
accepts an optional check-in name to identify the specific check-in
about which information is desired:

<blockquote>
<tt>fossil info</tt> <i>checkin-name</i>
</blockquote>

You are perhaps reading this page from the following URL:

<blockquote>
https://fossil-scm.org/home/doc/<b>trunk</b>/www/checkin_names.wiki
</blockquote>

The URL above is an example of an [./embeddeddoc.wiki | embedded documentation]
page in Fossil.  The bold term of the pathname is a check-in name that

determines which version of the documentation to display.

Fossil provides a variety of ways to specify a check-in.  This
document describes the various methods.

<h2 id="canonical">Canonical Check-in Name</h2>

The canonical name of a check-in is the hash of its
[./fileformat.wiki#manifest | manifest] expressed as a
[./hashes.md | long lowercase hexadecimal number].  For example:

<blockquote><pre>
fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9
</pre></blockquote>

The full 40 or 64 character hash is unwieldy to remember and type, though,
so Fossil also accepts a unique prefix of the hash, using any combination
of upper and lower case letters, as long as the prefix is at least 4
characters long.  Hence the following commands all
accomplish the same thing as the above:

<blockquote><pre>
fossil info e5a734a19a9
fossil info E5a734A
fossil info e5a7
</blockquote>

Many web interface screens identify check-ins by 10- or 16-character
prefix of canonical name.


<h2 id="tags">Tags And Branch Names</h2>

Using a tag or branch name where a check-in name is expected causes
Fossil to choose the most recent check-in with that tag or branch name.
So for example, the most recent check-in that
is tagged with "release" as of this writing is [b98ce23d4fc].
The command:

<blockquote><pre>
fossil info release
</pre></blockquote>

…results in the following output:

<blockquote><pre>
hash:         b98ce23d4fc3b734cdc058ee8a67e6dad675ca13 2020-08-20 13:27:04 UTC
parent:       40feec329163103293d98dfcc2d119d1a16b227a 2020-08-20 13:01:51 UTC
tags:         release, branch-2.12, version-2.12.1
comment:      Version 2.12.1 (user: drh)
</pre></blockquote>

There are multiple check-ins that are tagged with "release" but
(as of this writing) the [b98ce23d4fc]
check-in is the most recent so it is the one that is selected.

Note that unlike some other version control systems, a "branch" in Fossil
is not anything special: it is simply a sequence of check-ins that
share a common tag, so the same mechanism that resolves tag names
also resolves branch names.

<a id="tagpfx"></a>
Note also that there can — in theory, if rarely in practice — be an ambiguity
between tag names and canonical names.  Suppose, for example, you had a
check-in with the canonical name deed28aa99… and you
also happened to have tagged a different check-in with "deed2".  If
you use the "deed2" name, does it choose the canonical name or the tag
name?  In such cases, you can prefix the tag name with "tag:".
For example:

<blockquote><tt>
fossil info tag:deed2
</tt></blockquote>

The "tag:deed2" name will refer to the most recent check-in
tagged with "deed2" rather than the
check-in whose canonical name begins with "deed2".

<h2 id="whole-branches">Whole Branches</h2>

repo could have release tags like “2020-04-01”, the date the release was
cut, but you could force Fossil to interpret that string as a date
rather than as a tag by passing “date:2020-04-01”.

For an example of how timestamps are useful,
consider the homepage for the Fossil website itself:

<blockquote>
https://fossil-scm.org/home/doc/<b>trunk</b>/www/index.wiki
</blockquote>

The bold component of that URL is a check-in name.  To see the stored content
of the Fossil website repository as of January 1, 2009, one has merely to change
the URL to the following:

<blockquote>
https://fossil-scm.org/home/doc/<b>2009-01-01</b>/www/index.wiki
</blockquote>

(Note that this won't roll you back to the <i>skin</i> and other
cosmetic configurations as of that date. It also won't change screens
like the timeline, which has an independent date selector.)

<h2 id="tag-ts">Tag And Timestamp</h2>

A check-in name can also take the form of a tag or branch name followed by
a colon and then a timestamp.  The combination means to take the most
recent check-in with the given tag or branch which is not more recent than
the timestamp.  So, for example:

<blockquote><tt>
fossil update trunk:2010-07-01T14:30
</tt></blockquote>

Would cause Fossil to update the working check-out to be the most recent
check-in on the trunk that is not more recent than 14:30 (UTC) on
July 1, 2010.

<h2 id="root">Root Of A Branch</h2>

A branch name that begins with the "<tt>root:</tt>" prefix refers to the
last check-in on the parent branch prior to the beginning of the branch.
Such a label is useful, for example, in computing all diffs for a single
branch.  The following example will show all changes in the hypothetical
branch "xyzzy":

<blockquote><tt>
fossil diff --from root:xyzzy --to xyzzy
</tt></blockquote>

<a id="merge-in"></a>
That doesn't do what you might expect after you merge the parent
branch's changes into the child branch: the above command will include
changes made on the parent branch as well.

You can solve this by using the prefix "<tt>merge-in:</tt>" instead of
"<tt>root:</tt>" to tell Fossil to find
the most recent merge-in point for that branch.
The resulting diff will then show only the changes in
the branch itself, omitting
any changes that have already been merged in from the parent branch.

<a id="start"></a>
The prefix "<tt>start:</tt>" gives the first check-in of the named branch.

The prefixes "<tt>root:</tt>", "<tt>start:</tt>", and  "<tt>merge-in:</tt>"
can be chained: one can say for example 

<blockquote><tt>
fossil info merge-in:xyzzy:2022-03-01
</tt></blockquote>

to get informations about the most recent merge-in point on the branch 
"xyzzy" that happened on or before March 1, 2022.

<h2 id="special">Special Tags</h2>

The tag "tip" means the most recent check-in.  The "tip" tag is practically
equivalent to the timestamp "9999-12-31".

This special name works anywhere you can pass a "NAME", such as with
<tt>/info</tt> URLs:

<blockquote><pre>
http://localhost:8080/info/tip
</pre></blockquote>

There are several other special names, but they only work from within a
check-out directory because they are relative to the current checked-out
version:

  *  "current": the current checked-out version
  *  "next": the youngest child of the current checked-out version

<h2 id="examples">Additional Examples</h2>

To view the changes in the most recent check-in prior to the version currently
checked out:

<blockquote><pre>
fossil diff --from previous --to current
</pre></blockquote>

Suppose you are of the habit of tagging each release with a "release" tag.
Then to see everything that has changed on the trunk since the last release:

<blockquote><pre>
fossil diff --from release --to trunk
</pre></blockquote>


<h2 id="order">Resolution Order</h2>

Fossil currently resolves name strings to artifact hashes in the
following order:

at the request of the child.

<h2>Creating a Child Project</h2>

To create a new child project, first clone the parent.  Then make manual
SQL changes to the child repository as follows:

<blockquote><verbatim>
UPDATE config SET name='parent-project-code' WHERE name='project-code';
UPDATE config SET name='parent-project-name' WHERE name='project-name';
INSERT INTO config(name,value)
   VALUES('project-code',lower(hex(randomblob(20))));
INSERT INTO config(name,value)
   VALUES('project-name','CHILD-PROJECT-NAME');
</verbatim></blockquote>

Modify the CHILD-PROJECT-NAME in the last statement to be the name of
the child project, of course.

The repository is now a separate project, independent from its parent.
Clone the new project to the developers as needed.

identifier for a blob of data, such as a file. Given any file, it is
simple to find the artifact ID for that file. But given an artifact ID,
it is computationally intractable to generate a file that will have that
same 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.

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.

<h2 id="workflow">4.0 Workflow</h2>

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

<title>Customizing The Ticket System</title>
<nowiki>
<h2>Introduction</h2>

This guide will explain how to add the "assigned_to" and "submitted_by" fields
to the ticket system in Fossil, as well as making the system more useful.  You
must have "admin" access to the repository to implement these instructions.

<h2>First modify the TICKET table</h2>

<blockquote>
Click on the "Admin" menu, then "Tickets", then "Table".  After the other fields
and before the final ")", insert:
<pre>
  ,
  assigned_to TEXT,
  opened_by TEXT
</pre>

And "Apply Changes".  You have just added two more fields to the ticket
database!  NOTE: I won't tell you to "Apply Changes" after each step from here
on out.  Now, how do you use these fields?
</blockquote>

<h2>Next add assignees</h2>

<blockquote>
Back to the "Tickets" admin page, and click "Common".  Add something like this:
<pre>
set assigned_choices {
  unassigned
  tom
  dick
  harriet
}
</pre>

Obviously, choose names corresponding to the logins on your system.  The
'unassigned' entry is important, as it prevents you from having a NULL in that
field (which causes problems later when editing).
</blockquote>

<h2>Now modify the 'new ticket' page</h2>

<blockquote>
Back to the "Tickets" admin page, and click "New Ticket Page".  This is a little
more tricky.  Edit the top part:
<pre>

  if {[info exists submit]} {
     set status Open
     set opened_by $login
	 set assigned_to "unassigned"
     submit_ticket
  }

</pre>
Note the "set opened_by" bit -- that will automatically set the "opened_by"
field to the login name of the bug reporter.  Now, skip to the part with "EMail"
and modify it like so:
<pre>

&lt;th1>enable_output [expr { "$login" eq "anonymous"}]&lt;/th1>
&lt;tr>
&lt;td align="right">EMail:

&lt;input type="text" name="private_contact" value="$&lt;private_contact>" size="30">
&lt;/td>

&lt;td>&lt;u>Not publicly visible&lt;/u>. Used by developers to contact you with
questions.&lt;/td>
&lt;/tr>
&lt;th1>enable_output 1&lt;/th1>

</pre>
This bit of code will get rid of the "email" field entry for logged-in users.
Since we know the user's information, we don't have to ask for it. NOTE: it
might be good to automatically scoop up the user's email and put it here.

You might also want to enable people to actually assign the ticket to a specific
person during creation. For this to work, you need to add the code
for "assigned_to" as shown below under the heading "Modify the 'edit ticket' page".
This will give you an additional combobox where you can choose a person during
ticket creation.
</blockquote>

<h2>Modify the 'view ticket' page</h2>

<blockquote>
Look for the text "Contact:" (about halfway through).  Then insert these lines
after the closing tr tag and before the "enable_output" line:
<pre>
<tr>
  &lt;td align="right">Assigned to:&lt;/td>&lt;td bgcolor="#d0d0d0">
  $&lt;assigned_to>
  &lt;/td>
  &lt;td align="right">Opened by:&lt;/td>&lt;td bgcolor="#d0d0d0">
  $&lt;opened_by>
  &lt;/td>

</pre>
This will add a row which displays these two fields, in the event the user has
<a href="./caps/ref.html#w">ticket "edit" capability</a>.
</blockquote>

<h2>Modify the 'edit ticket' page</h2>

<blockquote>
Before the "Severity:" line, add this:
<pre>


&lt;tr>&lt;td align="right">Assigned to:&lt;/td>&lt;td>

&lt;th1>combobox assigned_to $assigned_choices 1&lt;/th1>
&lt;/td>&lt;/tr>
</pre>


That will give you a drop-down list of assignees. The first argument to the TH1
command 'combobox' is the database field which the combobox is associated to.
The next argument is the list of choices you want to show in the combobox (and
that you specified in the second step above. The last argument should be 1 for a
true combobox (see the <a href="th1.md#combobox">TH1 documentation</a> for
details).

Now, similar to the previous
section, look for "Contact:" and add this:
<pre>


  &lt;tr>&lt;td align="right">Reported by:&lt;/td>&lt;td>

  &lt;input type="text" name="opened_by" size="40"
   value="$&lt;opened_by>">
  &lt;/td>&lt;/tr>
</pre>
</blockquote>

<h2>What next?</h2>

<blockquote>
Now you can add custom reports which select based on the person to whom the
ticket is assigned.  For example, an "Assigned to me" report could be:
<pre>

SELECT
  CASE WHEN status IN ('Open','Verified') THEN '#f2dcdc'
       WHEN status='Review' THEN '#e8e8e8'
       WHEN status='Fixed' THEN '#cfe8bd'
       WHEN status='Tested' THEN '#bde5d6'
       WHEN status='Deferred' THEN '#cacae5'
       ELSE '#c8c8c8' END AS 'bgcolor',
  substr(tkt_uuid,1,10) AS '#',
  datetime(tkt_mtime) AS 'mtime',
  type,
  status,
  subsystem,
  title
FROM ticket
WHERE assigned_to=user()
</pre>
</blockquote>
</nowiki>

The format currently handles only 32 bit integer numbers. They are
written base-64 encoded, MSB first, and without leading
"0"-characters, except if they are significant (i.e. 0 => "0").

The base-64 encoding uses one character for each 6 bits of
the integer to be encoded.  The encoding characters are:

<blockquote><pre>
0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~
</pre></blockquote>

The least significant 6 bits of the integer are encoded by
the first character, followed by
the next 6 bits, and so on until all non-zero bits of the integer
are encoded.  The minimum number of encoding characters is used.
Note that for integers less than 10, the base-64 coding is a
ASCII decimal rendering of the number itself.

<h1>1.0 Fossil Support For Embedded Documentation</h1>

The fossil web interface supports embedded documentation using
the "/doc" page.  To access embedded documentation, one points
a web browser to a fossil URL of the following form:

<blockquote>
<i>&lt;baseurl&gt;</i><big><b>/doc/</b></big><i>&lt;version&gt;</i><big><b>/</b></big><i>&lt;filename&gt;</i>
</blockquote>

The <i>&lt;baseurl&gt;</i> is the main URL used to access the fossil web server.
For example, the <i>&lt;baseurl&gt;</i> for the fossil project itself is
[https://fossil-scm.org/home].
If you launch the web server using the "[/help?cmd=ui|fossil ui]" command line,
then the <i>&lt;baseurl&gt;</i> is usually
<b>http://localhost:8080/</b>.

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:

   [https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki].

The first part of this path, the "[https://fossil-scm.org/home]",
is the base URL.  You might have originally typed:
[https://fossil-scm.org/].  The web server at the fossil-scm.org
site automatically redirects such links by appending "home".  The
"home" file on fossil-scm.org is really a [./server/any/cgi.md|CGI script]
which runs the fossil web service in CGI mode.
The "home" CGI script looks like this:

<blockquote><pre>
#!/usr/bin/fossil
repository: /fossil/fossil.fossil
</pre></blockquote>

This is one of the many ways to set up a
<a href="./server/">Fossil server</a>.

The "<b>/trunk/</b>" part of the URL tells fossil to use
the documentation files from the most recent trunk check-in.
If you wanted to see an historical version of this document,

</ul>

When the symbolic name is a date and time, fossil shows the version
of the document that was most recently checked in as of the date
and time specified.  So, for example, to see what the fossil website
looked like at the beginning of 2010, enter:

<blockquote>
<a href="/doc/2010-01-01/www/index.wiki">
https://fossil-scm.org/home/doc/<b>2010-01-01</b>/www/index.wiki
</a>
</blockquote>

The file that encodes this document 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 for this document.

As I sit writing this documentation file, I am testing my work by
running the "<b>fossil ui</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.

There is a hyperlink under the /wikihelp menu that can be used to create
new technotes.  And there is a submenu hyperlink on technote displays for
editing existing technotes.

Technotes can also be created using the <b>wiki create</b> command:

<blockquote>
<b>
fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen technote.md<br>
<tt>Created new tech note 2021-03-15 13:05:56</tt><br>
</b>
</blockquote>

This command inserts a light green technote in the timeline at 2021-03-15 13:05:56, with 
the contents of file <b>technote.md</b> and comment "TestTechnote". Specifying a different time using
<b>-t DATETIME</b> will insert the technote at the specified timestamp location in the timeline.
Different technotes can have the same timestamp.

The first argument to create, <b>TECHNOTE-COMMENT</b>, is the title text for the technote
that appears in the timeline. 

To view all technotes, use the <b>wiki ls</b> command:

<blockquote>
<b>
fossil wiki ls --technote --show-technote-ids<br>
<tt>z739263a134bf0da1d28e939f4c4367f51ef4c51 2020-12-19 13:20:19</tt><br>
<tt>e15a918a8bed71c2ac091d74dc397b8d3340d5e1 2018-09-22 17:40:10</tt><br>
</b>
</blockquote>

A technote ID is the UUID of the technote.

To view an individual technote, use the <b>wiki export</b> command:

<blockquote>
<b>
fossil wiki export --technote version-2.16<br>
Release Notes 2021-07-02

This note describes changes in the Fossil snapshot for ...
</b>
</blockquote>

The <b>-t|--technote</b> option to the <b>export</b> subcommand takes one of
three identifiers: <b>DATETIME</b>; <b>TECHNOTE-ID</b>; and <b>TAG</b>.
See the [/help?cmd=wiki | wiki help] for specifics.

Users must have check-in privileges (permission "i") in order to
create or edit technotes.  In addition, users must have create-wiki

faq {
  What GUIs are available for fossil?
} {
  The fossil executable comes with a [./webui.wiki | web-based GUI] built in.
  Just run:

  <blockquote>
  <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i>
  </blockquote>

  And your default web browser should pop up and automatically point to
  the fossil interface.  (Hint:  You can omit the <i>REPOSITORY-FILENAME</i>
  if you are within an open check-out.)
}

faq {

  When you are checking in a new change using the <b>[/help/commit|commit]</b>
  command, you can add the option  "--branch <i>BRANCH-NAME</i>" to
  make the new check-in be the first check-in for a new branch.

  If you want to create a new branch whose initial content is the
  same as an existing check-in, use this command:

  <blockquote>
  <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i>
  </blockquote>

  The <i>BRANCH-NAME</i> argument is the name of the new branch and the
  <i>BASIS</i> argument is the name of the check-in that the branch splits
  off from.

  If you already have a fork in your check-in tree and you want to convert
  that fork to a branch, you can do this from the web interface.

  "--tag <i>TAGNAME</i>" command-line option.  You can repeat the --tag
  option to give a check-in multiple tags.  Tags need not be unique.  So,
  for example, it is common to give every released version a "release" tag.

  If you want add a tag to an existing check-in, you can use the
  <b>[/help/tag|tag]</b> command.  For example:

  <blockquote>
  <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i>
  </blockquote>

  The CHECK-IN in the previous line can be any
  [./checkin_names.wiki | valid check-in name format].

  You can also add (and remove) tags from a check-in using the
  [./webui.wiki | web interface].  First locate the check-in that you
  what to tag on the timeline, then click on the link to go the detailed

  See the article on [./shunning.wiki | "shunning"] for details.
}

faq {
  How do I make a clone of the fossil self-hosting repository?
} {
  Any of the following commands should work:

  <blockquote><pre>
  fossil [/help/clone|clone]  https://fossil-scm.org/  fossil.fossil
  fossil [/help/clone|clone]  https://www2.fossil-scm.org/  fossil.fossil
  fossil [/help/clone|clone]  https://www3.fossil-scm.org/site.cgi  fossil.fossil
  </pre></blockquote>

  Once you have the repository cloned, you can open a local check-out
  as follows:

  <blockquote><pre>
  mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil
  </pre></blockquote>

  Thereafter you should be able to keep your local check-out up to date
  with the latest code in the public repository by typing:

  <blockquote><pre>
  fossil [/help/update|update]
  </pre></blockquote>
}

faq {
  How do I import or export content from and to other version control systems?
} {
  Please see [./inout.wiki | Import And Export]
}



#############################################################################
# Code to actually generate the FAQ
#
puts "<title>Fossil FAQ</title>"
puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n"
puts "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>"
}
puts {</ol>}
puts {<hr>}

for {set i 1} {$i<$cnt} {incr i} {
  puts "<p id=\"q$i\"><b>($i) [lindex $faq($i) 0]</b></p>\n"
  set body [lindex $faq($i) 1]
  regsub -all "\n *" [string trim $body] "\n" body
  puts "<blockquote>$body</blockquote></li>\n"
}
puts {</ol>}

<li><a href="#q6">How can I delete inappropriate content from my fossil repository?</a></li>
<li><a href="#q7">How do I make a clone of the fossil self-hosting repository?</a></li>
<li><a href="#q8">How do I import or export content from and to other version control systems?</a></li>
</ol>
<hr>
<p id="q1"><b>(1) What GUIs are available for fossil?</b></p>

<blockquote>The fossil executable comes with a [./webui.wiki | web-based GUI] built in.
Just run:

<blockquote>
<b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i>
</blockquote>

And your default web browser should pop up and automatically point to
the fossil interface.  (Hint:  You can omit the <i>REPOSITORY-FILENAME</i>
if you are within an open check-out.)</blockquote></li>

<p id="q2"><b>(2) What is the difference between a "branch" and a "fork"?</b></p>

<blockquote>This is a big question - too big to answer in a FAQ.  Please
read the <a href="branching.wiki">Branching, Forking, Merging,
and Tagging</a> document.</blockquote></li>

<p id="q3"><b>(3) How do I create a new branch?</b></p>

<blockquote>There are lots of ways:

When you are checking in a new change using the <b>[/help/commit|commit]</b>
command, you can add the option  "--branch <i>BRANCH-NAME</i>" to
make the new check-in be the first check-in for a new branch.

If you want to create a new branch whose initial content is the
same as an existing check-in, use this command:

<blockquote>
<b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i>
</blockquote>

The <i>BRANCH-NAME</i> argument is the name of the new branch and the
<i>BASIS</i> argument is the name of the check-in that the branch splits
off from.

If you already have a fork in your check-in tree and you want to convert
that fork to a branch, you can do this from the web interface.
First locate the check-in that you want to be
the initial check-in of your branch on the timeline and click on its
link so that you are on the <b>ci</b> page.  Then find the "<b>edit</b>"
link (near the "Commands:" label) and click on that.  On the
"Edit Check-in" page, check the box beside "Branching:" and fill in
the name of your new branch to the right and press the "Apply Changes"
button.</blockquote></li>

<p id="q4"><b>(4) How do I tag a check-in?</b></p>

<blockquote>There are several ways:

When you are checking in a new change using the <b>[/help/commit|commit]</b>
command, you can add a tag to that check-in using the
"--tag <i>TAGNAME</i>" command-line option.  You can repeat the --tag
option to give a check-in multiple tags.  Tags need not be unique.  So,
for example, it is common to give every released version a "release" tag.

If you want add a tag to an existing check-in, you can use the
<b>[/help/tag|tag]</b> command.  For example:

<blockquote>
<b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i>
</blockquote>

The CHECK-IN in the previous line can be any
[./checkin_names.wiki | valid check-in name format].

You can also add (and remove) tags from a check-in using the
[./webui.wiki | web interface].  First locate the check-in that you
what to tag on the timeline, then click on the link to go the detailed
information page for that check-in.  Then find the "<b>edit</b>"
link (near the "Commands:" label) and click on that.  There are
controls on the edit page that allow new tags to be added and existing
tags to be removed.</blockquote></li>

<p id="q5"><b>(5) How do I create a private branch that won't get pushed back to the
  main repository.</b></p>

<blockquote>Use the <b>--private</b> command-line option on the
<b>commit</b> command.  The result will be a check-in which exists on
your local repository only and is never pushed to other repositories.
All descendants of a private check-in are also private.

Unless you specify something different using the <b>--branch</b> and/or
<b>--bgcolor</b> options, the new private check-in will be put on a branch
named "private" with an orange background color.

You can merge from the trunk into your private branch in order to keep
your private branch in sync with the latest changes on the trunk.  Once
you have everything in your private branch the way you want it, you can
then merge your private branch back into the trunk and push.  Only the
final merge operation will appear in other repositories.  It will seem
as if all the changes that occurred on your private branch occurred in
a single check-in.
Of course, you can also keep your branch private forever simply
by not merging the changes in the private branch back into the trunk.

[./private.wiki | Additional information]</blockquote></li>

<p id="q6"><b>(6) How can I delete inappropriate content from my fossil repository?</b></p>

<blockquote>See the article on [./shunning.wiki | "shunning"] for details.</blockquote></li>

<p id="q7"><b>(7) How do I make a clone of the fossil self-hosting repository?</b></p>

<blockquote>Any of the following commands should work:

<blockquote><pre>
fossil [/help/clone|clone]  https://fossil-scm.org/  fossil.fossil
fossil [/help/clone|clone]  https://www2.fossil-scm.org/  fossil.fossil
fossil [/help/clone|clone]  https://www3.fossil-scm.org/site.cgi  fossil.fossil
</pre></blockquote>

Once you have the repository cloned, you can open a local check-out
as follows:

<blockquote><pre>
mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil
</pre></blockquote>

Thereafter you should be able to keep your local check-out up to date
with the latest code in the public repository by typing:

<blockquote><pre>
fossil [/help/update|update]
</pre></blockquote></blockquote></li>

<p id="q8"><b>(8) How do I import or export content from and to other version control systems?</b></p>

<blockquote>Please see [./inout.wiki | Import And Export]</blockquote></li>

</ol>

<title>Fossilized Bash Prompt</title>
<h1>2013-02-21</h1>

Dan Kennedy has contributed a
[./fossil_prompt.sh?mimetype=text/plain | bash script]
that manipulates the bash prompt to show the status of
the Fossil repository that the user is currently visiting.
The prompt shows the branch, version, and time stamp for the
current checkout, and the prompt changes colors from blue to
red when there are uncommitted changes.

To try out this script, simply download it from the link above, then
type:

<blockquote><pre>
. fossil_prompt.sh
</pre></blockquote>

For a permanent installation, you can graft the code into your
<tt>.bashrc</tt> file in your home directory.

The code is very simple (only 32 non-comment lines, as of this writing)
and hence easy to customized.

repositories can be overridden using the "--sha1" option to the
"fossil new" command.

If you are still on Fossil 2.1 through 2.9 but you want Fossil to go
ahead and start using SHA3 hashes, change the hash policy to
"sha3" using a command like this:

<blockquote><verbatim>
fossil hash-policy sha3
</verbatim></blockquote>

The next check-in will use a SHA3 hash, so that when that check-in is pushed
to colleagues, their clones will include the new SHA3-named artifact, so
their local Fossil instances will automatically convert their clones to
"sha3" mode as well.

Of course, if some members of your team stubbornly refuse to upgrade past

<title>Import And Export</title>

Fossil has the ability to import and export repositories from and to
[http://git-scm.com/ | Git].  And since most other version control
systems will also import/export from Git, that means that you can
import/export a Fossil repository to most version control systems using
Git as an intermediary.

<h2>Git → Fossil</h2>

To import a Git repository into Fossil, say something like:

<blockquote><pre>
cd git-repo
git fast-export --all | fossil import --git new-repo.fossil
</pre></blockquote>

The 3rd argument to the "fossil import"
command is the name of a new Fossil repository that is created to hold the Git
content.

The --git option is not actually required.  The git-fast-export file format
is currently the only VCS interchange format that Fossil understands.  But

any dependency on the amount of data involved.

<h2>Fossil → Git</h2>

To convert a Fossil repository into a Git repository, run commands like
this:

<blockquote><pre>
git init new-repo
cd new-repo
fossil export --git ../repo.fossil | git fast-import
</pre></blockquote>

In other words, create a new Git repository, then pipe the output from the
"fossil export --git" command into the "git fast-import" command.

Note that the "fossil export --git" command only exports the versioned files.
Tickets and wiki and events are not exported, since Git does not understand
those concepts.

artifacts which are known by both Git and Fossil to exist at a given point in
time.

To illustrate, consider the example of a remote Fossil repository that a
user wants to import into a local Git repository.  First, the user would clone
the remote repository and import it into a new Git repository:

<blockquote><pre>
fossil clone /path/to/remote/repo.fossil repo.fossil
mkdir repo
cd repo
fossil open ../repo.fossil
mkdir ../repo.git
cd ../repo.git
git init .
fossil export --git --export-marks ../repo/fossil.marks  \
       ../repo.fossil | git fast-import                  \
       --export-marks=../repo/git.marks
</pre></blockquote>

Once the import has completed, the user would need to <tt>git checkout
trunk</tt>.  At any point after this, new changes can be imported from the
remote Fossil repository:

<blockquote><pre>
cd ../repo
fossil pull
cd ../repo.git
fossil export --git --import-marks ../repo/fossil.marks  \
       --export-marks ../repo/fossil.marks               \
       ../repo.fossil | git fast-import                  \
       --import-marks=../repo/git.marks                  \
       --export-marks=../repo/git.marks
</pre></blockquote>

Changes in the Git repository can be exported to the Fossil repository and then
pushed to the remote:

<blockquote><pre>
git fast-export --import-marks=../repo/git.marks                  \
    --export-marks=../repo/git.marks --all | fossil import --git  \
    --incremental --import-marks ../repo/fossil.marks             \
    --export-marks ../repo/fossil.marks ../repo.fossil
cd ../repo
fossil push
</pre></blockquote>

The SHA1 hash in the USER.PW field is a hash of a string composed of
the project-code, the user login, and the user cleartext password.
Suppose user "alice" with password "asdfg" had an account on the
Fossil self-hosting repository.  Then the value of USER.PW
for alice would be the SHA1 hash of

<blockquote>
CE59BB9F186226D80E49D1FA2DB29F935CCA0333/alice/asdfg
</blockquote>

Note that by including the project-code and the login as part of the
hash, a different USER.PW value results even if two or more users on
the repository select the same "asdfg" password or if user alice
reuses the same password on multiple projects.

Whenever a password is changed using the web interface or using the
"user" command-line method, the new password is stored using the SHA1
encoding.  Thus, cleartext passwords will gradually migrate to become
SHA1 passwords.  All remaining cleartext passwords can be converted to
SHA1 passwords using the following command:

<blockquote><pre>
fossil test-hash-passwords <i>REPOSITORY-NAME</i>
</pre></blockquote>

Remember that converting from cleartext to SHA1 passwords is an
irreversible operation.

The only way to insert a new cleartext password into the USER table
is to do so manually using SQL commands.  For example:

<blockquote><pre>
UPDATE user SET pw='asdfg' WHERE login='alice';
</pre></blockquote>

Note that an password that is an empty string or NULL will disable
all login for that user.   Thus, to lock a user out of the system,
one has only to set their password to an empty string, using either
the web interface or direct SQL manipulation of the USER table.
Note also that the password field is
essentially ignored for the special users named "anonymous", "developer",

This means that when USER.PW holds a cleartext password, the login card
will work for both older and newer clients.  If the USER.PW on the server
only holds the SHA1 hash of the password, then only newer clients will be
able to authenticate to the server.

The client normally gets the login and password from the "remote URL".

<blockquote><pre>
http://<span style="color:blue">login:password</span>@servername.org/path
</pre></blockquote>

For older clients, the password is used for the shared secret as stated
in the URL and with no encoding.
For newer clients, the shared secret is derived from the password
by transformed the password using the SHA1 hash encoding
described above.  However, if the first character of the password is
"*" (ASCII 0x2a) then the "*" is skipped and the rest of the password
is used directly as the share secret without the SHA1 encoding.

<blockquote><pre>
http://<span style="color:blue">login:*password</span>@servername.org/path
</pre></blockquote>

This *-before-the-password trick can be used by newer clients to
sync against a legacy server that does not understand the new SHA1
password encoding.

<title>What People Are Saying</title>

The following are collected quotes from various forums and blogs about
Fossil, Git, and DVCSes in general.  This collection is put together
by the creator of Fossil, so of course there is selection bias...

<h2>On The Usability Of Git:</h2>

<ol>
<li>Git approaches the usability of iptables, which is to say, utterly
unusable unless you have the manpage tattooed on you arm.

<blockquote>
<i>by mml at [http://news.ycombinator.com/item?id=1433387]</i>
</blockquote>

<li><nowiki>It's simplest to think of the state of your [git] repository
as a point in a high-dimensional "code-space",  in which branches are
represented as n-dimensional membranes, mapping the spatial loci of
successive commits onto the projected manifold of each cloned
repository.</nowiki>

<blockquote>
<i>by Jonathan Hartley at
[https://www.tartley.com/posts/a-guide-to-git-using-spatial-analogies];
<br>Quoted here: [https://lwn.net/Articles/420152/].</i>
</blockquote>

<li>Git is not a Prius. Git is a Model T.
Its plumbing and wiring sticks out all over the place.
You have to be a mechanic to operate it successfully or you'll be
stuck on the side of the road when it breaks down.
And it <b>will</b> break down.

<blockquote>
<i>Nick Farina at [http://nfarina.com/post/9868516270/git-is-simpler]</i>
</blockquote>

<li>Initial revision of "git", The information manager from hell

<blockquote>
<i>Linus Torvalds - 2005-04-07 22:13:13<br>
Commit comment on the very first source-code check-in for git
</blockquote>

<li>I've been experimenting a lot with git at work.
Damn, it's complicated.
It has things to trip you up with that sane people just wouldn't ever both with
including the ability to allow you to commit stuff in such a way that you can't find
it again afterwards (!!!)
Demented workflow complexity on acid?
<p>* dkf really wishes he could use fossil instead</p>
<blockquote>
<i>by Donal K. Fellow (dkf) on the Tcl/Tk chatroom, 2013-04-09.</i>
</blockquote>

<li>&#91;G&#93;it is <i>designed</i> to forget things.

<blockquote>
<i>[http://www.cs.cmu.edu/~davide/howto/git_lose.html]
</blockquote>

<li>&#91;I&#93;n nearly 31 years of using a computer i have, in total, lost more data to git
(while following the instructions!!!) than any other single piece of software.

<blockquote>
<i>Stephan Beal on the [http://www.mail-archive.com/fossil-users@lists.fossil-scm.org/msg17181.html|Fossil mailing list]
   2014-09-01.</i>
</blockquote>

<li>If programmers _really_ wanted to help scientists, they'd build a version control
system that was more usable than Git.

<blockquote>
<i>Tweet by Greg Wilson @gvwilson on 2015-02-22 17:47</i>
</blockquote>

<li><img src='xkcd-git.gif' align='top'>

<blockquote><i>Randall Munroe.  [http://xkcd.com/1597/]</i></blockquote>

</ol>

<h2>On The Usability Of Fossil:</h2>

<ol>
<li value=11>
Fossil mesmerizes me with simplicity especially after I struggled to
get a bug-tracking system to work with mercurial.

<blockquote>
<i>rawjeev at [https://stackoverflow.com/a/2100469/142454]</i>
</blockquote>

<li>Fossil is the best thing to happen
to my development workflow this year, as I am pretty sure that using
Git has resulted in the premature death of too many of my brain cells.
I'm glad to be able to replace Git in every place that I possibly can
with Fossil.

<blockquote>
<i>Joe Prostko at [http://www.mail-archive.com/fossil-users@lists.fossil-scm.org/msg16716.html]
</blockquote>

<li>This is my favourite VCS. I can carry it on a USB. And it's a complete system, with it's own
server, ticketing system, Wiki pages, and a very, very helpful timeline visualization. And
the entire program in a single file!

<blockquote>
<i>thunderbong commenting on hacker news: [https://news.ycombinator.com/item?id=9131619]</i>
</blockquote>


</ol>


<h2>On Git Versus Fossil</h2>

<ol>
<li value=14>
After prolonged exposure to fossil, i tend to get the jitters when I work with git...

<blockquote>
<i>sriku - at [https://news.ycombinator.com/item?id=16104427]</i>
</blockquote>


<li>
Just want to say thanks for fossil making my life easier....
Also <nowiki>[for]</nowiki> not having a misanthropic command line interface.

<blockquote>
<i>Joshua Paine at [http://www.mail-archive.com/fossil-users@lists.fossil-scm.org/msg02736.html]</i>
</blockquote>

<li>We use it at a large university to manage code that small teams write.
The runs everywhere, ease of installation and portability is something that
seems to be a good fit with the environment we have (highly ditrobuted,
sometimes very restrictive firewalls, OSX/Win/Linux).  We are happy with it
and teaching a Msc/Phd student (read complete novice) fossil has just
been a smoother ride than Git was.

<blockquote>
<i>viablepanic at [https://www.reddit.com/r/programming/comments/bxcto/why_not_fossil_scm/c0p30b4?utm_source=share&utm_medium=web2x&context=3]</i>
</blockquote>

<li>In the fossil community - and hence in fossil itself - development history
is pretty much sacrosanct. The very name "fossil" was to chosen to
reflect the unchanging nature of things in that history.
<br><br>
In git (or rather, the git community), the development history is part of
the published aspect of the project, so it provides tools for rearranging
that history so you can present what you "should" have done rather
than what you actually did.

<blockquote>
<i>Mike Meyer on the Fossil mailing list, 2011-10-04</i>
</blockquote>

<li>github is such a pale shadow of what fossil does.

<blockquote>
<i>dkf on the Tcl chatroom, 2013-12-06</i>
</blockquote>

<li>&#91;With fossil&#93; I actually enjoy keeping track of source files again.

<blockquote>
<a href="https://wholesomedonut.prose.sh/using-fossil-not-git">https://wholesomedonut.prose.sh/using-fossil-not-git</a>
</blockquote>
</ol>

<title>Fossil SCGI</title>

To run Fossil using SCGI, start the [/help/server|fossil server] command
with the --scgi command-line option.  You will probably also want to
specific an alternative TCP/IP port using --port.  For example:

<blockquote><pre>
fossil server $REPOSITORY --port 9000 --scgi
</pre></blockquote>

Then configure your SCGI-aware web-server to send SCGI requests to port
9000 on the machine where Fossil is running.  A typical configuration for
this in Nginx is:

<blockquote><pre>
location ~ ^/demo_project/ {
    include scgi_params;
    scgi_pass localhost:9000;
    scgi_param SCRIPT_NAME "/demo_project";
    scgi_param HTTPS "on";
}
</pre></blockquote>

Note that Nginx does not normally send either the PATH_INFO or SCRIPT_NAME
variables via SCGI, but Fossil needs one or the other.  So the configuration
above needs to add SCRIPT_NAME.  If you do not do this, Fossil returns an
error.

dozen other smaller projects.  This demonstrates that Fossil can run on
a low-power host processor.
Multiple fossil-based projects can easily be hosted on the same machine,
even if that machine is itself one of several dozen virtual machines on
single physical box.  The CGI script that runs the canonical Fossil
self-hosting repository is as follows:

<blockquote><pre>
#!/usr/bin/fossil
repository: /fossil/fossil.fossil
</pre></blockquote>

Server (3) ran for 10 years as a CGI script on a shared hosting account at
<a href="http://www.he.net/">Hurricane Electric</a> in Fremont, CA.
This server demonstrated the ability of
Fossil to run on an economical shared-host web account with no
privileges beyond port 80 HTTP access and CGI.  It is not necessary
to have a dedicated computer with administrator privileges to run Fossil.
As far as we are aware,
Fossil is the only full-featured configuration management system
that can run in
such a restricted environment.  The CGI script that ran on the
Hurricane Electric server was the same as the CGI script shown above,
except that the pathnames are modified to suit the environment:

<blockquote><pre>
#!/home/hwaci/bin/fossil
repository: /home/hwaci/fossil/fossil.fossil
</pre></blockquote>

In recent years, virtual private servers have become a more flexible and
less expensive hosting option compared to shared hosting accounts.
So on 2017-07-25, server (3) was moved
onto a $5/month "droplet" [https://en.wikipedia.org/wiki/Virtual_private_server|VPS]
from [https://www.digitalocean.com|Digital Ocean]
located in San Francisco.

Server (3) is synchronized with the canonical server (1) by running
a command similar to the following via cron:

<blockquote><pre>
/usr/local/bin/fossil all sync -u
</pre></blockquote>

Server (2) is a
<a href="http://www.linode.com/">Linode 4096</a> located in Newark, NJ
and set up just like the canonical server (1) with the addition of a
cron job for synchronization.  The same cron job also runs the
[/help?cmd=git|fossil git export] command after each sync in order to
[./mirrortogithub.md#ex1|mirror all changes to GitHub].

<title>Serving via rc on OpenBSD</title>

OpenBSD provides [https://man.openbsd.org/rc.subr.8|rc.subr(8)],
a framework for writing [https://man.openbsd.org/rc.8|rc(8)] scripts.

<h2>Creating the daemon</h2>

Create the file /etc/rc.d/fossil with contents like the following.

<blockquote><pre>
#!/bin/ksh
daemon="/usr/local/bin/fossil" # fossil executable
daemon_user="_fossil" # user to run fossil as
daemon_flags="server /home/_fossil/example --repolist --port 8888" # fossil command

. /etc/rc.d/rc.subr
# pexp="$daemon server .*" # See below.
rc_reload=NO # Unsupported by Fossil; 'rcctl reload fossil' kills the process.
rc_bg=YES # Run in the background, since fossil serve does not daemonize itself
rc_cmd $1
</pre></blockquote>

<h3>pexp</h3>

You may need to uncomment the "pexp=". rc.subr typically
finds the daemon process based by matching the process name and argument list.
Without the "pexp=" line, rc.subr would look for this exact command:

<blockquote><pre>
/usr/local/bin/fossil server /home/_fossil/example --repolist --port 8888
</pre></blockquote>

Depending on the arguments and their order, fossil may rewrite the arguments
for display in the process listing ([https://man.openbsd.org/ps.1|ps(1)]),
so rc.subr may fail to find the process through the default match. The example
above does not get rewritten, but the same commands in a different order can
be rewritten.
For example, when I switch the order of the arguments in "daemon_flags",

<blockquote><pre>
/usr/local/bin/fossil server --repolist --port 8888 /home/_fossil/example
</pre></blockquote>

the process command is changed to this.

<blockquote><pre>
/usr/local/bin/fossil server /home/_fossil/example /home/_fossil/example 8888 /home/_fossil/example
</pre></blockquote>

The commented "pexp=" line instructs rc.subr to choose the process whose
command and arguments text starts with this:

<blockquote><pre>
/usr/local/bin/fossil server 
</pre></blockquote>

<h2>Enabling the daemon</h2>

Once you have created /etc/rc.d/fossil, run these commands.

<blockquote><pre>
rcctl enable fossil # add fossil to pkg_scripts in /etc/rc.conf.local
rcctl start fossil # start the daemon now
</pre></blockquote>

The daemon should now be running and set to start at boot.

<h2>Multiple daemons</h2>

You may want to serve multiple fossil instances with different options.
For example,

  *  If different users own different repositories, you may want different users
     to serve different repositories.
  *  You may want to serve different repositories on different ports so you can
     control them differently with, for example, HTTP reverse proxies or
     [https://man.openbsd.org/pf.4|pf(4)].

To run multiple fossil daemons, create multiple files in /etc/rc.d, and
enable each of them. Here are two approaches for creating
the files in /etc/rc.d: Symbolic links and copies.

<h3>Symbolic links</h3>

Suppose you want to run one fossil daemon as user "user1" on port 8881
and another as user "user2" on port 8882. Create the files with
[https://man.openbsd.org/ln.1|ln(1)], and configure them to run different
fossil commands.

<blockquote><pre>
cd /etc/rc.d
ln -s fossil fossil1
ln -s fossil fossil2
rcctl enable fossil1 fossil2
rcctl set fossil1 user user1
rcctl set fossil2 user user2
rcctl set fossil1 flags 'server /home/user1/repo1.fossil --port 8881'
rcctl set fossil2 flags 'server /home/user2/repo2.fossil --port 8882'
rcctl start fossil1 fossil2
</pre></blockquote>

<h3>Copies</h3>

You may want to run fossil daemons that are too different to configure
just with [https://man.openbsd.org/rcctl.8|rcctl(8)].
In particular, you can't change the "pexp" with rcctl.

If you want to run fossil commands that are more different,
you may prefer to create separate files in /etc/rc.d.
Replace "ln -s" above with "cp" to accomplish this.

<blockquote><pre>
cp /etc/rc.d/fossil /etc/rc.d/fossil-user1
cp /etc/rc.d/fossil /etc/rc.d/fossil-user2
</pre></blockquote>

You can still use commands like "rcctl set fossil-user1 flags", but you
can also edit the "/etc/rc.d/fossil-user1" file.

An administrator activates the CGI extension mechanism by specifying
an "Extension Root Directory" or "extroot" as part of the 
[./server/index.html|server setup].
If the Fossil server is itself run as 
[./server/any/cgi.md|CGI], then add a line to the 
[./cgi.wiki#extroot|CGI script file] that says:

<blockquote><pre>
extroot: <i>DIRECTORY</i>
</pre></blockquote>

Or, if the Fossil server is being run using the 
"[./server/any/none.md|fossil server]" or
"[./server/any/none.md|fossil ui]" or 
"[./server/any/inetd.md|fossil http]" commands, then add an extra 
"--extroot <i>DIRECTORY</i>" option to that command.

The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI.
Files in the DOCUMENT_ROOT are accessed via URLs like this:

<blockquote>
https://example-project.org/ext/<i>FILENAME</i>
</blockquote>

In other words, access files in DOCUMENT_ROOT by appending the filename
relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext]
page of the Fossil server.
Files that are readable but not executable are returned as static
content.  Files that are executable are run as CGI.

<h3>2.1 Example #1</h3>

The source code repository for SQLite is a Fossil server that is run
as CGI.  The URL for the source code repository is [https://sqlite.org/src].
The CGI script looks like this:

<blockquote><verbatim>
#!/usr/bin/fossil
repository: /fossil/sqlite.fossil
errorlog: /logs/errors.txt
extroot: /sqlite-src-ext
</verbatim></blockquote>

The "extroot: /sqlite-src-ext" line tells Fossil that it should look for
extension CGIs in the /sqlite-src-ext directory.  (All of this is happening
inside of a chroot jail, so putting the document root in a top-level
directory is a reasonable thing to do.)

When a URL like "https://sqlite.org/src/ext/checklist" is received by the

main web server which in turn relays the result back to the original client.

<h3>2.2 Example #2</h3>

The [https://fossil-scm.org/home|Fossil self-hosting repository] is also
a CGI that looks like this:

<blockquote><verbatim>
#!/usr/bin/fossil
repository: /fossil/fossil.fossil
errorlog: /logs/errors.txt
extroot: /fossil-extroot
</verbatim></blockquote>

The extroot for this Fossil server is /fossil-extroot and in that directory
is an executable file named "fileup1" - another [https://wapp.tcl.tk|Wapp]
script.  (The extension mechanism is not required to use Wapp.  You can use
any kind of program you like.  But the creator of SQLite and Fossil is fond
of [https://www.tcl.tk|Tcl/Tk] and so he tends to gravitate toward Tcl-based
technologies like Wapp.)  The fileup1 script is a demo program that lets

header and footer, then the inserted header will include a
Content Security Policy (CSP) restriction on the use of javascript within
the webpage.  Any <script>...</script> elements within the 
CGI output must include a nonce or else they will be suppressed by the
web browser.  The FOSSIL_NONCE variable contains the value of that nonce.
So, in other words, to get javascript to work, it must be enclosed in:

<blockquote><verbatim>
<script nonce='$FOSSIL_NONCE'>...</script>
</verbatim></blockquote>

Except, of course, the $FOSSIL_NONCE is replaced by the value of the
FOSSIL_NONCE environment variable.

<h3>3.1 Input Content</h3>

If the HTTP request includes content (for example if this is a POST request)
then the CONTENT_LENGTH value will be positive and the data for the content
will be readable on standard input.


<h2>4.0 CGI Outputs</h2>

CGI programs construct a reply by writing to standard output.  The first
few lines of output are parameters intended for the web server that invoked
the CGI.  These are followed by a blank line and then the content.

Typical parameter output looks like this:

<blockquote><verbatim>
Status: 200 OK
Content-Type: text/html
</verbatim></blockquote>

CGI programs can return any content type they want - they are not restricted
to text replies.  It is OK for a CGI program to return (for example)
image/png.

The fields of the CGI response header can be any valid HTTP header fields.
Those that Fossil does not understand are simply relayed back to up the
line to the requester.

Fossil takes special action with some content types.  If the Content-Type
is "text/x-fossil-wiki" or "text/x-markdown" then Fossil
converts the content from [/wiki_rules|Fossil-Wiki] or 
[/md_rules|Markdown] into HTML, adding its
own header and footer text according to the repository skin.  Content
of type "text/html" is normally passed straight through
unchanged.  However, if the text/html content is of the form:

<blockquote><verbatim>
<div class='fossil-doc' data-title='DOCUMENT TITLE'>
... HTML content there ...
</div>
</verbatim></blockquote>

In other words, if the outer-most markup of the HTML is a &lt;div&gt;
element with a single class of "fossil-doc", 
then Fossil will adds its own header and footer to the HTML.  The
page title contained in the added header will be extracted from the
"data-title" attribute.

<h3>2.1 Ticket Table Schema</h3>

The two ticket tables are called TICKET and TICKETCHNG.
The default schema (as of this writing) for these two tables is shown
below:

<blockquote><verbatim>
CREATE TABLE ticket(
  -- Do not change any column that begins with tkt_
  tkt_id INTEGER PRIMARY KEY,
  tkt_uuid TEXT UNIQUE,
  tkt_mtime DATE,
  tkt_ctime DATE,
  -- Add as many fields as required below this line

  -- Add as many fields as required below this line
  login TEXT,
  username TEXT,
  mimetype TEXT,
  icomment TEXT
);
CREATE INDEX ticketchng_idx1 ON ticketchng(tkt_id, tkt_mtime);
</verbatim></blockquote>

Generally speaking, there is one row in the TICKETCHNG table for each
change to each ticket.  In other words, there is one row in the
TICKETCHNG table for each low-level ticket change artifact.  The
TICKET table, on the other hand, contains a summary of the current
status of each ticket.

the [/help?cmd=/uvlist|/uvlist] URL.  ([/uvlist|example]).

<h2>Syncing Unversioned Files</h2>

Unversioned content does not sync between repositories by default.
One must request it via commands such as:

<blockquote><pre>
fossil sync <b>-u</b>
fossil clone <b>-u</b> <i>URL local-repo-name</i>
fossil unversioned sync
</pre></blockquote>

The [/help?cmd=sync|fossil sync] and [/help?cmd=clone|fossil clone]
commands will synchronize unversioned content if and only if they're
given the "-u" (or "--unversioned") command-line option.  The
[/help?cmd=unversioned|fossil unversioned sync] command synchronizes the
unversioned content without synchronizing anything else.

<i>(This section outlines the current implementation of unversioned
files.  This is not an interface spec and hence subject to change.)</i>

Unversioned content is stored in the repository in the
"unversioned" table:

<blockquote><pre>
CREATE TABLE unversioned(
  uvid INTEGER PRIMARY KEY AUTOINCREMENT,  -- unique ID for this file
  name TEXT UNIQUE,       -- Name of the file
  rcvid INTEGER,          -- From whence this file was received
  mtime DATETIME,         -- Last change (seconds since 1970)
  hash TEXT,              -- SHA1 or SHA3-256 hash of uncompressed content
  sz INTEGER,             -- Size of uncompressed content
  encoding INT,           -- 0: plaintext  1: zlib compressed
  content BLOB            -- File content
);
</pre></blockquote>

Fossil does not create the table ahead of need.
If there are no unversioned files in the repository, the
"unversioned" table will not exist. Consequently,
one simple way to purge all unversioned content from a repository
is to run:

<blockquote><pre>
fossil sql "DROP TABLE unversioned; VACUUM;"
</pre></blockquote>

Lacking history for unversioned files, Fossil does not attempt delta
compression on them.

Fossil servers exchange unversioned content whole; it does not attempt
to "diff" your local version against the remote and send only the
changes. We point this out because one use-case for unversioned content