3.  <b>Enumeration Lists.</b>
      An enumeration list item is a line that begins with a single "#"
      character surrounded on both sides by two or more spaces or by a tab.
      Or it can be a number and a "." (ex:  "5.") surrounded on both sides
      by two spaces or a tab.
      Only a single level of enumeration list is supported by wiki.
      For nested lists or for enumerations that count using letters or
      roman numerials, use HTML.

  4.  <b>Indented Paragraphs.</b>
      Any paragraph that begins with two or more spaces or a tab and which
      is not a bullet or enumeration list item is rendered indented.
      Only a single level of indentation is supported by wiki.
      Use HTML for deeper indentation.

    of [digital signatures][dsig] to prevent Type 1 and Type 3 frauds. This
    chain forms an additional link between the blocks, separate from the
    hash chain that applies an ordering and lookup scheme to the blocks.
    [_Blockchain: Simple Explanation_][bse] explains this “hash chain”
    vs. “block chain” distinction in more detail.

    These signatures prevent modification of the face value of each
    transation (Type 1 fraud) by ensuring that only the one signing a
    new block has the private signing key that could change an issued
    block after the fact.

    The fact that these signatures are also *chained* prevents Type
    3 frauds by making the *prior* owner of a block sign it over to
    the new owner. To avoid an O(n²) auditing problem as a result,
    cryptocurrencies add a separate chain of hashes to make checking

    Cyrptocurrencies also use the work problem to prevent Type 2
    forgeries, but the application of that to Fossil is a matter we get
    to [later](#work).

    Although you have complete control over the contents of your local
    Fossil repository clone, you cannot perform Type 1 forgery on its
    contents short of executing a [preimage attack][prei] on the hash
    algorthm. ([SHA3-256][SHA-3] by default in the current version of
    Fossil.) Even if you could, Fossil’s sync protocol will prevent the
    modification from being pushed into another repository: the remote
    Fossil instance says, “I’ve already got that one, thanks,” and
    ignores the push.  Thus, short of breaking into the remote server
    and modifying the repository in place, you couldn’t even make use of
    a preimage attack if you had that power. This is an attack on the
    server itself, not on Fossil’s data structures, so while it is

    commit Type 2 frauds. But let us be clear: your choice of setting
    does not answer the question of whether Fossil is a blockchain.)

    If Fossil signatures prevent Type 1 and Type 2 frauds, you
    may wonder why they are not enabled by default. It is because
    they are defense-in-depth measures, not the minimum sufficient
    measures needed to prevent repository fraud, unlike the equivalent
    protections in a cryptocurrency blockcahin. Fossil provides its
    primary protections through other means, so it doesn’t need to
    mandate signatures.

    Also, Fossil is not itself a [PKI], and there is no way for regular
    users of Fossil to link it to a PKI, since doing so would likely
    result in an unwanted [PII] disclosure.  There is no email address
    in a Fossil commit manifest that you could use to query one of the

<pre><code>docker image rm THE_FOSSIL_ID THE_ALPINE_ID</code></pre>


<h2>6.0 Building on/for Android</h2>

<h3>6.1 Cross-compiling from Linux</h3>

The following instructions for building Fossil for Andoid,
without requiring a rooted OS, are adapted from
[https://fossil-scm.org/forum/forumpost/e0e9de4a7e | forumpost/e0e9de4a7e].

On the development machine, from the fossil source tree:

<pre><code>export CC=$NDK_PATH/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabi21-clang
./configure --with-openssl=none

*   **SQL**: The Admin → SQL feature allows the Setup user to enter raw
    SQL queries against the Fossil repository via Fossil UI. This not
    only allows arbitrary ability to modify the repository hash tree
    and its backing data tables, it can probably also be used to damage
    the host such as via `PRAGMA temp_store = FILE`.

*   **Tickets**: This section allows input of aribtrary TH1 code that
    runs on the server, affecting the way the Fossil ticketing system
    works. The justification in the **TH1** section below therefore
    applies.

*   **TH1**: The [TH1 language][th1] is quite restricted relative to the
    Tcl language it descends from, so this author does not believe there
    is a way to damage the Fossil repository or its host via the Admin →

     using Ajax.

<a name='v2_0'></a>
<h2>Changes for Version 2.0 (2017-03-03)</h2>

  *  Use the
     [https://github.com/cr-marcstevens/sha1collisiondetection|hardened SHA1]
     implemenation by Marc Stevens and Dan Shumow.
  *  Add the ability to read and understand
     [./fileformat.wiki#names|artifact names] that are based on SHA3-256
     rather than SHA1, but do not actually generate any such names.
  *  Added the [/help?cmd=sha3sum|sha3sum] command.
  *  Update the built-in SQLite to version 3.17.0.

<a name='v1_37'></a>

     [/help?cmd=/timeline|/timeline] webpage, with associated form widgets.
  *  Enhance the [/help/changes|changes] and [/help/status|status] commands
     with many new filter options so that specific kinds of changes can be
     found without having to pipe through grep or sed.
  *  Enhanced the [/help/sqlite3|fossil sql] command so that it opens the
     [./tech_overview.wiki#localdb|checkout database] and the
     [./tech_overview.wiki#configdb|configuration database] in addition to the
     respository database.
  *  TH1 enhancements:
     <ul><li>Add <nowiki>[unversioned content]</nowiki> command.</li>
     <li>Add <nowiki>[unversioned list]</nowiki> command.</li>
     <li>Add project_description variable.</li>
     </ul>
  *  Rename crnl-glob [/help/settings|setting] to crlf-glob, but keep
     crnl-glob as a compatibility alias.

  *  Added --include and --exclude options to [/help?cmd=tarball|fossil tarball]
     and [/help?cmd=zip|fossil zip] and the in= and ex= query parameters to the
     [/help?cmd=/tarball|/tarball] and [/help?cmd=/zip|/zip] web pages.
  *  Add support for [./encryptedrepos.wiki|encrypted Fossil repositories].
  *  If the FOSSIL_PWREADER environment variable is set, then use the program it
     names in place of getpass() to read passwords and passphrases
  *  Option --baseurl now works on Windows.
  *  Numerious documentation improvements.
  *  Update the built-in SQLite to version 3.13.0.

<a name='v1_34'></a>
<h2>Changes for Version 1.34 (2015-11-02)</h2>

  *  Make the [/help?cmd=clean|fossil clean] command undoable for files less
     than 10MiB.

This document is *not* an introduction to CSS - the web is
full of tutorials on that topic. It covers only the specifics
of customizing certain CSS-based behaviors in a Fossil UI. That said...

## Is it Really `!important`?

By and large, CSS's `!important` qualifier is not needed when
customzing Fossil's CSS. On occasion, however, particular styles may
be set directly on DOM elements when Fossil generates its HTML, and
such cases require the use of `!important` to override them.


<!-- ============================================================ -->
# Main UI CSS

The skin is controlled by five files:

<blockquote><dl>
<dt><b>css.txt</b></dt><dd>

<p>The css.txt file is the text of the CSS for Fossil.
Fossil might add additional CSS elements after the
the css.txt file, if it sees that the css.txt omits some
CSS components that Fossil needs.  But for the most part,
the content of the css.txt is the CSS for the page.</dd>

<dt><b>details.txt</b><dt><dd>

<p>The details.txt file is short list of settings that control

read out of the directory named.  You can then edit the control
files in the ./newskin folder using you favorite text editor, and
press "Reload" on your browser to see the effects.

## <a name="headfoot"></a>Header and Footer Processing

The `header.txt` and `footer.txt` control files of a skin are the HTML text
of the Contnet Header and Content Footer, except that before being inserted
into the output stream, the text is run through a
[TH1 interpreter](./th1.md) that might adjust the text as follows:

  *  All text within &lt;th1&gt;...&lt;/th1&gt; is omitted from the
     output and is instead run as a TH1 script.  That TH1
     script has the opportunity to insert new text in place of itself,
     or to inhibit or enable the output of subsequent text.

        <p style="margin-left: 4em">Indented text.</p>

As the "`unsafe-`" prefix on the name implies, the `'unsafe-inline'`
feature is suboptimal for security.  However, there are
a few places in the Fossil-generated HTML that benefit from this
flexibility and the work-arounds are verbose and difficult to maintain.
Futhermore, the harm that can be done with style injections is far
less than the harm possible with injected javascript.  And so the
`'unsafe-inline'` compromise is accepted for now, though it might
go away in some future release of Fossil.

### <a name="script"></a> script-src 'self' 'nonce-%s'

This policy disables in-line JavaScript and only allows `<script>`

visiting their repository home page, set to [an HTML-formatted embedded
doc page][hfed] via Admin → Configuration → Index Page, with this
content:

         <script src="/doc/trunk/bad.js"></script>

That script can then do anything allowed in JavaScript to *any other*
Chisel repository your browser can access.The possibilities for mischief
are *vast*. For just one example, if you have login cookies on four
different Chisel repositories, your attacker could harvest the login
cookies for all of them through this path if we allowed Fossil to serve
JavaScript files under the same CSP policy as we do for CSS files.

This is why the default configuration of Fossil has no way for [embedded
docs][ed], [wiki articles][wiki], [tickets][tkt], [forum posts][fp], or

4.  Use the [optional CGI server extensions feature](./serverext.wiki)
    to serve such content via `/ext` URLs.

5.  Put Fossil behind a [front-end proxy server][svr] as a virtual
    subdirectory within the site, so that our default CSP’s “self” rules
    match static file routes on that same site. For instance, your repo
    might be at `https://example.com/code`, allowing documentes in that
    repo to refer to:

    *   images as `/image/foo.png`
    *   JavaScript files  as `/js/bar.js`
    *   CSS style sheets as `/style/qux.css`

    Although those files are all outside the Fossil repo at `/code`,

`--vfs VFSNAME`: Load the named VFS into SQLite.


Environment Variables
---------------------

The location of the user's account-wide [configuration database][configdb]
depends on the operating system and on the existance of various 
environment variables and/or files.  See the discussion of the
[configuration database location algorithm][configloc] for details.

`EDITOR`: Name the editor to use for check-in and stash comments.
Overridden by the local or global `editor` setting or the `VISUAL`
environment variable.

Fossil keeps some information pertinent to each user in the user's
[configuration database file][configdb]. 
The configuration database file includes the global settings
and the list of repositories and checkouts used by `fossil all`.

The location of the configuration database file depends on the
operating system and on the existance of various environment
variables and/or files.  In brief, the configuration database is
usually:

  *  Traditional unix → "`$HOME/.fossil`"
  *  Windows → "`%LOCALAPPDATA%/_fossil`"
  *  [XDG-unix][xdg] → "`$HOME/.config/fossil.db`"

somwhere on the page outside of the editor.

Exactly how long `localStorage` will survive, and how much it or
`sessionStorage` can hold, is environment-dependent. `sessionStorage`
will survive until the current browser tab is closed, but it survives
across reloads of the same tab.

If `/filepage` determines that no peristent storage is available a
warning is displayed on the editor page.

[html5storage]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API

## <a id="power"></a> The Power is Yours, but...

> "With great power comes great responsibility."

    means something else. You cannot simplify the cryptic incantation in
    the typical use case.

2.  A date string in Git without a time will be interpreted as
    “[at the local wall clock time on the given date][gapxd],” so the
    command means something different from one second to the next. This
    can be a problem if there are multiple commits on that date, because
    the command will give diffferent results depending on the time of
    day you run it.

3.  It gives misleading output if there is no close match for the date
    in the local [reflog]. It starts out empty after a fresh clone, and
    while it does build up as you use that clone, Git [automatically
    prunes][gle] the reflog to 90 days of history by default. This means
    the command above can give different results from one machine to the

sequences are allowed to match `/` directory separators as well as the
initial `.` in the name of a hidden file or directory. This is because
Fossil file names are stored as complete path names. The distinction
between file name and directory name is “below” Fossil in this sense.

[pg]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_13

The bracket expresssions above require some additional explanation:

 *  A range of characters may be specified with `-`, so `[a-f]` matches
    exactly the same characters as `[abcdef]`. Ranges reflect Unicode
    code points without any locale-specific collation sequence.
    Therefore, this particular sequence never matches the Unicode
    pre-composed character `é`, for example. (U+00E9)

## Experimenting

To preview the effects of command line glob pattern expansion for
various glob patterns (unquoted, quoted, comma-terminated), for any
combination of command shell, OS, C run time, and Fossil version,
preceed the command you want to test with [`test-echo`][] like so:

    $ fossil test-echo setting crlf-glob "*"
    C:\> echo * | fossil test-echo setting crlf-glob --args -

The [`test-glob`][] command is also handy to test if a string
matches a glob pattern.

database, which is what brought it to the attention of the SQLite architect.
These design choices were a major source of inspiration for Fossil.

[335]: https://www.monotone.ca/

Beginning around 2005, the need for a better version control system
for SQLite began to become evident.  The SQLite architect looked
around for a suitable replacement.  Monotone, Git, and Mercurical were
all considered.  But at that time, none of these supported sync
over ordinary HTTP, none could be run from an inexpensive shell
account on a leased server (this was before the widespread availability
of affordable virtual machines), and none of them supported anything 
resembling the wiki and ticket features of CVSTrac that had been 
found to be so useful.  And so, the SQLite architect began writing
his own DVCS.

[345]: https://fossil-scm.org/fossil/timeline?c=200707211410&n1=10

The first project hosted by Fossil was Fossil itself.  After a
few months of development work, the code was considered stable enough
to begin hosting the [SQLite documentation repository][350] which was
split off from the main SQLite CVS repository on [2007-11-12][355].
After two years of development work on Fossil, the
SQLite source code itself was transfered to Fossil on
[2009-08-11][360].

[350]: https://www.sqlite.org/docsrc/doc/trunk/README.md
[355]: https://www.sqlite.org/docsrc/timeline?c=200711120345&n1=10
[360]: https://sqlite.org/src/timeline?c=b0848925babde524&n1=12&y=ci

     readers can co-exist with the writer.  Or the script might just
     launch a background process that waits until the hook script finishes
     and the transaction commits before it tries to access the repository
     database.

  *  A push might not deliver all of the artifacts for a checkin.  If
     Fossil knows that a /xfer HTTP request is incomplete, it will defer
     running the after-receive push for 60 seconds, or unti a complete
     /xfer request is received.  This helps to prevent after-receive hooks
     from running when incomplete checkins exist in the repository, but
     it does not provide hard guarantees, as there is no way to do that
     in a distributed system.

  *  The list of artifacts delivered to standard input of the
     after-receive hook will not contain more than 24-hours worth

    the zlib binary data compression algorithm. This shows that for
    repos where the image files are committed only once, there is
    virtually no penalty to using BMP or TIFF over PNG. The file sizes
    likely differ only because of differences in zlib settings between
    the cases.

*   Because JPEG’s lossy nature allows it to start smaller and have
    smaller size increases than than PNG, the crossover point with
    BMP/TIFF isn’t until 7-9 checkins in typical runs of this [Monte
    Carlo experiment][mce].  Given a choice among these four file
    formats and a willingness to use lossy image compression, a rational
    tradeoff is to choose JPEG for repositories where each image will
    change fewer than that number of times.

The pathnames in the above command might need to be adjusted to get the
directories right.  The point is that the manifest.uuid, manifest, and
VERSION files
in the root of the source tree are the three arguments and
the generated VERSION.h file appears on standard output.

The builtin_data.h header file is generated by a C program: src/mkbuiltin.c.
The builtin_data.h file contains C-langauge byte-array definitions for
the content of resource files used by Fossil.  To generate the
builtin_data.h file, first compile the mkbuiltin.c program, then run:

<blockquote><pre>
mkbuiltin.exe diff.tcl <i>OtherFiles...</i> &gt;builtin_data.h
</pre></blockquote>

<b>[/help/changes | fossil changes]</b><br>
<b>[/help/diff | fossil diff]</b><br>
<b>[/help/timeline | fossil timeline]</b><br>
<b>[/help/ls | fossil ls]</b><br>
<b>[/help/branch | fossil branch]</b><br>
</blockquote>

<p>If you created a new respository using "fossil init" some commands will not
produce much output.</p>

<p>Note that Fossil allows you to make multiple check-outs in
separate directories from the same repository.  This enables you,
for example, to do builds from multiple branches or versions at
the same time without having to generate extra clones.</p>

<p>[/help/update | update] honors the "autosync" option and
does a "soft" switch, merging any local changes into the target
version, whereas [/help/checkout | checkout] does not
automatically sync and does a "hard" switch, overwriting local
changes if told to do so.</p>

<h2 id="changes">Making and Commiting Changes</h2>

<p>To add new files to your project or remove existing ones, use these
commands:</p>

<blockquote>
<b>[/help/add | fossil add]</b> <i>file...</i><br>
<b>[/help/rm | fossil rm]</b> <i>file...</i><br>

<blockquote>
<b>fossil setting proxy off</b>
</blockquote>

<p>Or unset the environment variable.  The fossil setting for the
HTTP proxy takes precedence over the environment variable and the
command-line option overrides both.  If you have an persistent
proxy setting that you want to override for a one-time sync, that
is easily done on the command-line.  For example, to sync with
a co-workers repository on your LAN, you might type:</p>

<blockquote>
<b>fossil sync http://192.168.1.36:8080/ --proxy off</b>
</blockquote>

<h2 id="links">Other Resources</h2>

doesn’t make the user tell counter-factual “stories,” it only allows the
user to provide annotations to provide a more readable edited
presentation for routine display purposes.

Git needs rebase because it lacks these annotation facilities.  Rather
than consider rebase a desirable feature missing in Fossil, ask instead
why Git lacks support for making editorial changes to check-ins without
modifyihng history?  Wouldn't it be better to fix the version control
tool rather than requiring users to fabricate a fictitious project
history?

## <a name="collapsing"></a>6.0 Collapsing check-ins throws away valuable information

One of the oft-cited advantages of rebasing in Git is that it lets you
collapse multiple check-ins down to a single check-in to make the

# Serving via althttpd

[Althttpd][althttpd]
is a light-weight web server that has been used to implement the SQLite and
Fossil websites for well over a decade. Althttpd strives for simplicity,
security, ease of configuration, and low resource usage.

To set up a Fossil server as CGI on a host running the althttpd web
server, follow these steps.
<ol>
<li<p>Get the althttpd webserver running on the host.  This is easily
done by following the [althttpd documentation][althttpd].

<li><p>Create a CGI script for your Fossil respository.  The script will
be typically be two lines of code that look something like this:

~~~
    #!/usr/bin/fossil
    repository: /home/yourlogin/fossils/project.fossil
~~~

1.  Install the unit file to one of the persistent system-level unit
    file directories. Typically, these are:

        /etc/systemd/system
        /lib/systemd/system

2.  Add `User` and `Group` directives to the `[Service]` section so
    Fossil runs as a normal user, preferrably one with access only to
    the Fossil repo files, rather than running as `root`.


## Socket Activation

Another useful method to serve a Fossil repo via `systemd` is via a
socket listener, which `systemd` calls “[socket activation][sa].”

## <a name="chroot"></a>Setup chroot

Fossil needs both `/dev/random` and `/dev/null`, which aren't accessible
from within the chroot, so need to be constructed; `/var`, however, is
mounted with the `nodev` option. Rather than removing this default
setting, create a small memory filesystem and then mount it on to
`/var/www/dev` with [`mount_mfs(8)`][mfs] so that the `random` and
`null` device files can be created. In order to avoid neccessitating a
startup script to recreate the device files at boot, create a template
of the needed ``/dev`` tree to automatically populate the memory
filesystem.

```console
    $ doas mkdir /var/www/dev
    $ doas install -d -g daemon /template/dev

      to host builds and downloads on the project website.

  2.  <b>A server gives developers a common point of rendezvous for
      syncing their work.</b><p>
      It is possible for developers to synchronize peer-to-peer but
      that requires the developers coordinate the sync, which in turn
      requires that the developers both want to sync at the same moment.
      A server aleviates this time dependency by allowing each developer
      to sync whenever it is convenient (for example, automatically syncing
      after each commit and before each update).  Developers all stay
      in sync with each other, without having to interrupt each other
      constantly to set up a peer-to-peer sync.

  3.  <b>A server provides project leaders with up-to-date status.</b><p>
      Project coordinators and BDFLs can click on a link or two at the

    check-in.</p></li>
</ul>

<h2>Exception: Non-versioned Content</h2>

It is normal and expected to delete data which is not versioned, such as
usernames and passwords in the user table. The [/help/scrub|fossil scrub]
command will remove all sensitive non-versioned data from a respository.

The scrub command will remove user 'bertina', along with their password,
any supplied IP address, any concealed email address etc. However, in the 
DAG, commits by 'bertina' will continue to be visible unchanged even though
there is no longer any such user in Fossil.

<h2>Shunning</h2>

CA's signing certificate in PEM format and pointing OpenSSL at it:

<pre>
     fossil set --global ssl-ca-location /path/to/local-ca.pem
</pre>

The use of <tt>--global</tt> with this option is common, since you may
have multiple reposotories served under certificates signed by that same
CA. However, if you have a mix of publicly-signed and locally-signed
certificates, you might want to drop the <tt>--global</tt> flag and set
this option on a per-repository basis instead.

A common way to run into the broader first problem is that you're on
FreeBSD, which does not install a CA certificate set by default, even as
a dependency of the OpenSSL library.  If you're using a certificate