### Data Design

There are two new tables in the repository database, starting with
Fossil 2.7.  These tables are not created in new repositories by
default.  The tables only come into existence as needed when email
alerts are configured and used.


  *  <b>SUBSCRIBER</b> →
     The subscriber table records the email address for people who
     want to receive email notifications.  Each subscriber has a
     `subscriberCode` which is a random 32-byte blob that uniquely
     identifies the subscriber.  There are also fields to indicate
     what kinds of notifications the subscriber wishes to receive,
     whether or not the email address of the subscriber has been
     verified, etc.

  *  <b>PENDING\_ALERT</b> →
     The PENDING\_ALERT table contains records that define events
     about which alert emails might need to be sent.
     A pending\_alert always refers to an entry in the
     EVENT table.  The EVENT table is part of the standard schema
     and records timeline entries.  In other words, there is one
     row in the EVENT table for each possible timeline entry.  The
     PENDING\_ALERT table refers to EVENT table entries for which
     we might need to send alert emails.

There was a third table "EMAIL_BOUNCE" in Fossil versions 2.7 through 2.14.
That table was intended to record email bounce history so that
subscribers with excessive bounces can be turned off.  But that feature
was never implemented and the table was removed in Fossil 2.15.

As pointed out above, ["subscribers" are distinct from "users"](#uvs).
The SUBSCRIBER.SUNAME field is the optional linkage between users and
subscribers.


<a id="stdout"></a>
### The "stdout" Method

# <a id="sql-solution"></a> Solution 2: SQL-Level Backup

The first method doesn’t get you a copy of the remote’s
[private branches][pbr], on purpose. It may also miss other info on the
remote, such as SQL-level customizations that the sync protocol can’t
see. (Some [ticket system customization][tkt] schemes rely on this ability, for example.) You can
solve such problems if you have access to the remote server, which
allows you to get a SQL-level backup. This requires Fossil 2.12 or
newer, which added [the `backup` command][bu] to take care of
locking and transaction isolation, allowing the user to safely back up an in-use
repository.

If you have SSH access to the remote server, something like this will work:

``` shell
#!/bin/bash
bf=repo-$(date +%Y-%m-%d).fossil

along with <tt>--fuzztype</tt>, be sure to check your system's process
list to ensure that your <tt>--fuzztype</tt> flag is there.


<a id='wasm'></a>
<h2>8.0 Building WebAssembly Components</h2>

As of version 2.19, fossil uses one component built as
[https://developer.mozilla.org/en-US/docs/WebAssembly | WebAssembly]
a.k.a. WASM. Because compiling WASM code requires non-trivial
client-side tooling, the repository includes compiled copies of these
pieces. Most Fossil hackers should never need to concern themselves
with the WASM parts, but this section describes how to for those who
want or need to do so.

  <tr id="d">
    <th>d</th>
    <th>n/a</th>
    <td>
      Legacy capability letter from Fossil's forebear <a
      href="http://cvstrac.org/">CVSTrac</a>, which has no useful
      meaning in Fossil due to the nature of its durable Merkle tree design. This
      letter was assigned by default to Developer in repos created with
      Fossil 2.10 or earlier, but it has no effect in current or past
      versions of Fossil; we recommend that you remove it in case we
      ever reuse this letter for another purpose. See <a
      href="https://fossil-scm.org/forum/forumpost/43c78f4bef">this
      post</a> for details.
    </td>
  </tr>

  <tr id="e">

# Fossil Chat

## Introduction

As of version 2.14,
Fossil supports a developer chatroom feature.  The chatroom provides an
ephemeral discussion venue for insiders.  Design goals include:

  *  **Simple but functional** →
     Fossil chat is designed to provide a convenient real-time
     communication mechanism for geographically dispersed developers.
     Fossil chat is *not* intended as a replacement or competitor for
     IRC, Slack, Discord, Telegram, Google Hangouts, etc.

For users with appropriate permissions, simply browse to the
[/chat](/help?cmd=/chat) to start up a chat session.  The default
skin includes a "Chat" entry on the menu bar on wide screens for
people with chat privilege.  There is also a "Chat" option on
the [Sitemap page](/sitemap), which means that chat will appear
as an option under the hamburger menu for many [skins](./customskin.md).

As of version 2.17, chat messages are subject to [fossil's
full range of markdown processing](/md_rules). Because chat messages are
stored as-is when they arrive from a client, this change applies
retroactively to messages stored by previous fossil versions.

Files may be sent via chat using the file selection element at the
bottom of the page. If the desktop environment system supports it,
files may be dragged and dropped onto that element. Files are not
automatically sent - selection of a file can be cancelled using the

will be included in that list. To switch sounds, tap the "settings"
button.

### <a id='connection'></a> Who's Online?

Because the chat app has to be able to work over transient CGI-based
connections, as opposed to a stable socket connection to the server,
real-time tracking of "who's online" is not feasible. As of version
2.17, chat offers an optional feature, toggleable in the settings,
which can list users who have posted messages in the client's current
list of loaded messages. This is not the same thing as tracking who's
online, but it gives an overview of which users have been active most
recently, noting that "lurkers" (people who post no messages) will not
show up in that list, nor does the chat infrastructure have a way to
track and present those. That list can be used to filter messages on a
specific user by tapping on that user's name, tapping a second time to

Basically, you replace the `cd` commands in the multiple checkouts
workflow above with `fossil up` commands.


#### <a id="open"></a> Opening a Repository by URI

In Fossil 2.12, we added a feature to simplify the single-worktree use
case:

    mkdir work-dir
    cd work-dir
    fossil open https://example.com/repo

Now you have “trunk” open in `work-dir`, with the repo file stored as
`repo.fossil` in that same directory.

Users of Git may be surprised that it doesn’t create a directory for you
and that you `cd` into it *before* the clone-and-open step, not after.
This is because we’re overloading the “open” command, which already had
the behavior of opening into the current working directory. Changing it
to behave like `git clone` would therefore make the behavior surprising
to Fossil users. (See [our discussions][caod] if you want the full
details.)


#### <a id="clone"></a> Git-Like Clone-and-Open

In Fossil 2.14, we added a more Git-like alternative:

    fossil clone https://fossil-scm.org/fossil
    cd fossil

This results in a `fossil.fossil` repo DB file and a `fossil/` working
directory.

to close out the generated HTML:

    </body>
    </html>

## <a id="mainmenu"></a>Changing the Main Menu Contents

As of Fossil 2.15, the actual text content of the skin’s main menu is no
longer part of the skin proper if you’re using one of the stock skins.
If you look at the Header section of the skin, you’ll find a
`<div class="mainmenu">` element whose contents are set by a short
[TH1](./th1.md) script from the contents of the **Main Menu** section of
the Setup → Configuration screen.

This feature allows the main menu contents to stay the same across
different skins, so you no longer have to reapply menu customizations

The three "timeline-" settings in details.txt control the appearance
of certain aspects of the timeline graph.  The number on the
right is a boolean - "1" to activate the feature and "0" to
disable it.  The "white-foreground:" setting should be set to
"1" if the page color has light-color text on a darker background,
and "0" if the page has dark text on a light-colored background.

If the "pikchr-foreground" setting (added in Fossil 2.14)
is defined and is not an empty string then it specifies a
foreground color to use for [pikchr diagrams](./pikchr.md).  The
default pikchr foreground color is black, or white if the
"white-foreground" boolean is set.  The "pikchr-background"
settings does the same for the pikchr diagram background color.
If the "pikchr-fontscale" and "pikchr-scale" values are not
empty strings, then they should be floating point values (close

typically cause the javascript to be loaded by including the
following TH1 code in the "header.txt" file:

<pre>
&lt;th1&gt;builtin_request_js hbmenu.js&lt;/th1&gt;
</pre>

The difference between styleScript and builtin_request_js
is that the styleScript command interprets the file
using TH1 and injects the content directly into the output
stream, whereas the builtin_request_js command inserts the
javascript verbatim and does so at some unspecified future time
down inside the Fossil-generated footer.  The built-in skins
of Fossil originally used the styleScript command to load
the hamburger menu javascript, but as of version 2.15 switched
to using the builtin_request_js method.  You can use either
approach in custom skins that you right yourself.

Note that the "js.txt" file is *not* automatically inserted into
the generate HTML for a page.  You, the skin designer, must
cause the javascript to be inserted by issuing appropriate
TH1 commands in the "header.txt" or "footer.txt" files.</dd>
</dl>

[b64]: https://en.wikipedia.org/wiki/Base64
[svr]: ./server/


### <a id="img"></a> img-src * data:


As of Fossil 2.15, we don’t restrict the source of inline images at all.
You can pull them in from remote systems as well as pull them from
within the Fossil repository itself, or use `data:` URIs.

If you are certain all images come from only within the repository, you
can close off certain risks — tracking pixels, broken image format
decoders, system dialog box spoofing, etc. — by changing this to
“`img-src 'self'`” possibly followed by “`data:`” if you will also use
`data:` URIs.

lost on a page reload. How that is done is completely dependent on the
3rd-party editor widget, but it generically looks something like:

```
myCustomWidget.on('eventName', ()=>fossil.page.notifyOfChange());
```

(This feature requires fossil version 2.13 or later. In 2.12 it is
possible to do this but requires making use of a "leaky abstraction".)

Lastly, if the 3rd-party editor does *not* hide or remove the native
editor widget, and does not inject itself into the DOM on the caller's
behalf, we can replace the native widget with the 3rd-party one with:

```javascript
fossil.page.replaceEditorWidget(yourNewWidgetElement);
```

Fossil delivered a new release allowing a clean migration to
[https://en.wikipedia.org/wiki/SHA-3|256-bit SHA-3] with
[./hashpolicy.wiki|full backwards compatibility] to old SHA-1 based
repositories.

In October 2019, after the last of the major binary
package repos offering Fossil upgraded to Fossil 2.<i>x</i>,
we switched the default hash mode so that from
Fossil 2.10 forward, the conversion to SHA-3 is fully automatic.
This not
only solves the SHAttered problem, it should prevent a reoccurrence of
similar problems for the foreseeable future.

Meanwhile, the Git community took until August 2018 to publish
[https://git-scm.com/docs/hash-function-transition/|their first plan]
for solving the same problem by moving to SHA-256, a variant of the

    <li><p>Both Fossil and Git support
    [https://en.wikipedia.org/wiki/Patch_(Unix)|<tt>patch(1)</tt>
    files] — unified diff formatted output — for accepting drive-by contributions, but it's a
    lossy contribution path for both systems. Unlike Git PRs and Fossil
    bundles, patch files collapse multiple checkins together, they don't
    include check-in comments, and they cannot encode changes made above
    the individual file content layer: you lose branching decisions,
    tag changes, file renames, and more when using patch files. Fossil
    2.16 adds [./patchcmd.md | a <tt>fossil patch</tt> command] that
    also solves these problems, but it is because it works like a Fossil
    bundle, only for uncommitted changes; it doesn't use Larry Wall's
    <tt>patch</tt> tool to apply unified diff output to the receiving
    Fossil checkout.</p></li>
</ol></i></small>

is "`trunk`".  The "`trunk`" branch in Fossil corresponds to the
"`master`" branch in stock Git or to [the “`main`” branch in GitHub][mbgh].

Because the `fossil git export` command has to work with both stock Git
and with GitHub, Fossil uses Git’s traditional default rather than
GitHub’s new default: your Fossil repo’s “trunk” branch becomes “master”
when [mirroring to GitHub][mirgh] unless you give the `--mainbranch`
option added in Fossil 2.14.

We do not know what happens on subsequent exports if you later rename
this branch on the GitHub side.

[mbgh]:  https://github.com/github/renaming
[mirgh]: ./mirrortogithub.md

    `patch(1)` files or piping diff output to another command that
    doesn’t understand ANSI escape sequences. There’s an example of this
    [below](#dstat).

*   Use the Fossil web UI to diff existing commits.

*   To diff the current working directory contents against some parent
    instead, Fossil 2.17 expanded the diff command so it can produce
    colorized HTML output and open it in the OS’s default web browser.
    For example, `fossil diff -by` will show side-by-side diffs.

*   Use the older `fossil diff --tk` option to do much the same using
    Tcl/Tk instead of a browser.

Viewed this way, Fossil doesn’t lack colorized diffs, it simply has

We start the same way, cloning the work repo down to the laptop:

    fossil clone https://dev-server.example.com/repo
    cd repo
    fossil remote add work https://dev-server.example.com/repo

We’ve chosen the new “`fossil clone URI`” syntax added in Fossil 2.14 rather than separate
`clone` and `open` commands to make the parallel with Git clearer. [See
above](#mwd) for more on that topic.

Our [`remote` command][rem] is longer than the Git equivalent because
Fossil currently has no short command
to rename an existing remote. Worse, unlike with Git, we can’t just keep
using the default remote name because Fossil uses that slot in its

    organizational tool well-suited to complicated documentation.

*   Your repository’s Home page is a good candidate for the wiki, as is
    documentation meant for use only with the current version of the
    repository’s contents.

*   If you are at all uncertain whether to use the wiki or the embedded
    documentation feature, prefer the latter, since it is more powerful
    and, with the addition of the [`/fileedit` feature][fef] in Fossil
    2.12, it’s nearly as easy to use.

    (This very file is embedded documentation: clone
    [Fossil’s self-hosting repository][fshr] and you will find it as
    `www/glossary.md`.)

[edoc]: ./embeddeddoc.wiki
[fef]:  ./fileedit-page.md

diff them” feature.

[wt]: https://fossil-scm.org/home/timeline


### <a id="wedit"></a>The New Wiki Editor

The [new wiki editor][fwt] added in Fossil 2.12 has many new features, a
few of which are impossible to get without use of JavaScript.

First, it allows in-browser previews without losing client-side editor
state, such as where your cursor is. With the old editor, you had to
re-locate the place you were last editing on each preview, which would
reduce the incentive to use the preview function. In the new wiki
editor, you just click the Preview tab to see how Fossil interprets your

this new editor was created, replacing it. If someone rescues that
feature, merging it in with the new editor, it will doubtless require
JavaScript in order to react to editor button clicks like the “**B**”
button, meaning “make \[selected\] text boldface.” There is no standard
WYSIWYG editor component in browsers, doubtless because it’s relatively
straightforward to create one using JavaScript.

_Graceful Fallback:_ Unlike in the Fossil 2.11 and earlier days, there
is no longer a script-free wiki editor mode. This is not from lack of
desire, only because the person who wrote the new wiki editor didn’t
want to maintain three different editors. (New Ajaxy editor, old
script-free HTML form based editor, and the old WYSIWYG JavaScript-based
editor.) If someone wants to implement a `<noscript>` alternative to the
new wiki editor, we will likely accept that [contribution][cg] as long
as it doesn’t interfere with the new editor. (The same goes for adding
a WYSIWYG mode to the new Ajaxy wiki editor.)

[fwc]: /help?cmd=wiki
[fwt]: ./wikitheory.wiki


### <a id="fedit"></a>The File Editor

Fossil 2.12 adds the [optional file editor feature][fedit], which works
much like [the new wiki editor](#wedit), only on files committed to the
repository.

The original designed purpose for this feature is to allow [embedded
documentation][edoc] to be interactively edited in the same way that
wiki articles can be. (Indeed, the associated `fileedit-glob` feature
allows you to restrict the editor to working *only* on files that can be

per [the `/file` docs](/help?cmd=/file).

_Potential Better Workaround:_ Someone sufficiently interested could
[provide a patch][cg] to add a `<noscript>` wrapped HTML button that
would reload the page with this parameter included/excluded to implement
the toggle via a server round-trip.

As of Fossil 2.12, there is also a JavaScript-based interactive method
for selecting a range of lines by clicking the line numbers when they’re
visible, then copying the resulting URL to share your selection with
others.

_Workaround:_ These interactive features would be difficult and
expensive (in terms of network I/O) to implement without JavaScript.  A
far simpler alternative is to manually edit the URL, per above.

[mainc]: https://fossil-scm.org/home/artifact?ln&name=87d67e745

in one box, you probably want to examine the same point on that line in
the other box.

_Graceful Fallback:_ Manually scroll both boxes to sync their views.

### <a id="diffcontext"></a>Diff Context Loading

As of version 2.17, fossil adds the ability for the diff views to
dynamically load more lines of context around changed blocks. The UI
controls for this feature are injected using JavaScript when the page
initializes and make use of XHR requests to fetch data from the
fossil instance.

_Graceful Fallback:_ The UI controls for this feature do not appear
when JS is unavailable, leaving the user with the "legacy" static diff

patch to do this][cg] may well be accepted. Since this is not a
*necessary* Fossil feature, an interested user is unlikely to get the
core developers to do this work for them.


### <a id="chat"></a>Chat

The [chat feature](./chat.md) added in Fossil 2.14 is deeply dependent
on JavaScript. There is no obvious way to do this sort of thing without
active client-side code of some sort.

_Potential Workaround:_ It would not be especially difficult for someone
sufficiently motivated to build a Fossil chat gateway, connecting to
IRC, Jabber, etc. The messages are stored in the repository’s `chat`
table with monotonically increasing IDs, so a poller that did something
like

    SELECT xfrom, xmsg FROM chat WHERE msgid > 1234;

…would pull the messages submitted since the last poll. Making the
gateway bidirectional should be possible as well, as long as it properly
uses SQLite transactions.

### <a id="brlist"></a>List of branches

Since Fossil 2.16 the [`/brlist`](/brlist) page uses JavaScript to enable
selection of several branches for further study via `/timeline`.
Client-side script interactively responds to checkboxes' events
and constructs a special hyperlink in the submenu.
Clicking this hyperlink loads a `/timeline` page that shows
only these selected branches (and the related check-ins).

_Potential Workaround:_ A user can manually construct an appropriate

     subsequent invocations of "`fossil git export`" will know where you
     left off the last time and what new content needs to be moved over into
     Git.  Be careful not to mess with the `.mirror_state` directory or
     any of its contents.  Do not put those files under Git management.  Do
     not edit or delete them.

  *  The name of the "trunk" branch is automatically translated into "master"
     in the Git mirror unless you give the `--mainbranch` option,
     added in Fossil 2.14.

  *  Only check-ins and simple tags are translated to Git.  Git does not
     support wiki or tickets or unversioned content or any of the other
     features of Fossil that make it so convenient to use, so those other
     elements cannot be mirrored in Git.

  *  In Git, all tags must be unique.  If your Fossil repository has the

detectors don’t include one that knows how to detect an attack on
Fossil.  We have to teach it by putting the following into
`/etc/fail2ban/filter.d/nginx-fossil-login.conf`:

    [Definition]
    failregex = ^<HOST> - .*POST .*/login HTTP/..." 401

That teaches `fail2ban` how to recognize the errors logged by Fossil
[as of 2.14](/info/39d7eb0e22). (Earlier versions of Fossil returned
HTTP status code 200 for this, so you couldn’t distinguish a successful
login from a failure.)

Then in `/etc/fail2ban/jail.local`, add this section:

    [nginx-fossil-login]
    enabled = true
    logpath = /var/log/nginx/*-https-access.log

# Fossil as a Windows Service

If you need Fossil to start automatically on Windows, it is suggested to install
Fossil as a Windows Service.

## Assumptions

1. You have Administrative access to a Windows 2012r2 or above server.
2. You have PowerShell 5.1 or above installed.

## Place Fossil on Server

However you obtained your copy of Fossil, it is recommended that you follow
Windows conventions and place it within `\Program Files\FossilSCM`.  Since
Fossil 2.10 is a 64bit binary, this is the proper location for the executable.
This way Fossil is at an expected location and you will have minimal issues with
Windows interfering in your ability to run Fossil as a service.  You will need
Administrative rights to place fossil at the recommended location.  If you will
only be running Fossil as a service, you do not need to add this location to the
path, though you may do so if you wish.

## Installing Fossil as a Service

## Assumptions

1. You have Administrative access to a Windows 2012r2 or above server.
2. You have PowerShell 5.1 or above installed.
3. You have acquired a certificate either from a Public CA or an Internal CA.

These instructions were tested with Fossil 2.10 and stunnel 5.55.  Other
versions may not function in a similar manner.  There is a bug in Fossil 2.9 and
earlier that prevents these versions of Fossil from properly constructing https
URLs when used with stunnel as a proxy.  Please make sure you are using Fossil
2.10 or later on Windows.

## Configure Fossil Service for https

Due to the need for the `--https` option for successfully using Fossil with
stunnel, we will use [Advanced service installation using PowerShell](./service.md#PowerShell).
We will need to change the command to install the Fossil Service to configure
it properly for use with stunnel as an https proxy.  Run the following:

to accept the certificate the first time you communicate with the
server. Verify the certificate fingerprint is correct, then answer
"always" if you want Fossil to remember your decision.

If you are cloning from or syncing to Fossil servers that use a
certificate signed by a well-known CA or one of its delegates, Fossil
still has to know which CA roots to trust. When this fails, you get an
error message that looks like this in Fossil 2.11 and newer:

<pre>
Unable to verify SSL cert from fossil-scm.org
  subject: CN = sqlite.org
  issuer:  C = US, O = Let's Encrypt, CN = Let's Encrypt Authority X3
  sha256:  bf26092dd97df6e4f7bf1926072e7e8d200129e1ffb8ef5276c1e5dd9bc95d52
accept this cert and continue (y/N)?

If you attempt to connect to a server which requests a client
certificate, but don't provide one, fossil will show an error message
which explains what to do to authenticate with the server.


<h2 id="server">Server-Side Configuration</h2>

Fossil's built-in HTTP server got [./ssl-server.md | TLS support] in
December 2021, released as version 2.18 in early 2022.  Prior to that,
system administrators that wanted to add TLS support to a Fossil server
had to put it behind a reverse proxy that would do the translation.
Since advantages remain for delegating TLS to another layer in the
stack, instructions for doing so continue to be included in our
documentation, such as:

  *  <a id="stunnel"  href="./server/any/stunnel.md">Serving via stunnel</a>
  *  <a id="althttpd" href="./server/any/althttpd.md">Serving via stunnel + althttpd</a>

document.



<a id="capexpr"></a>TH1 capexpr Command
-----------------------------------------------------

Added in Fossil 2.15.

  *  capexpr CAPABILITY-EXPR

The capability expression is a list. Each term of the list is a
cluster of [capability letters](./caps/ref.html). 
The overall expression is true if any
one term is true. A single term is true if all letters within that
term are true. Or, if the term begins with "!", then the term is true