<title>Unversioned Content</title>
"Unversioned content" or "unversioned files" are
files stored in a Fossil repository without history, meaning
it retains the newest version of each such file, and that alone.
Though it omits history, Fossil does sync unversioned content between
repositories. In the event of a conflict during a sync, it retains
the most recent version of each unversioned file, discarding
older versions.
Unversioned files are useful for storing ephemeral content such as builds
or frequently changing web pages. We store
the [https://fossil-scm.org/home/uv/download.html|download] page of
the self-hosting Fossil repository as unversioned
content, for example.
<h2>Accessing Unversioned Files</h2>
Unversioned files are <u>not</u> a part of a check-out.
Unversioned files are intended to be accessible as web pages using
URLs of the form: "<tt>https://example.com/cgi-script/<b>uv</b>/<i>FILENAME</i></tt>".
In other words, the URI method "<b>uv</b>" (short for "unversioned")
followed by the name of the unversioned file will retrieve the content
of the file. The MIME type is inferred from the filename suffix.
The content of unversioned files can also be retrieved using the
[/help?cmd=unversioned|fossil unvers cat <i>FILENAME</i>] command.
A list of all unversioned files on a server can be seen using
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:
<pre>
fossil sync <b>-u</b>
fossil clone <b>-u</b> <i>URL local-repo-name</i>
fossil unversioned sync
</pre>
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.
Notice that the "-u" option does not work on
[/help?cmd=push|fossil push] or [/help?cmd=pull|fossil pull].
The "-u" option is only available on "sync" and "clone".
A rough equivalent of an unversioned pull would be the
[/help?cmd=unversioned|fossil unversioned revert] command. The
"unversioned revert"
command causes the unversioned content on the local repository to overwritten
by the unversioned content found on the remote repository.
Beware that because unversioned file sync is an uncommonly dangerous
capability — there being no history to revert to in the case of human
error — even the all-powerful Fossil "setup" user does not get
unversioned file sync capability by default. See
[./caps/admin-v-setup.md#dcap | this] for the full details, but the
short-and-sweet takeaway is that a user needs the "y" capability on the
remote before they can sync unversioned content. Until then, you're
allowed to add such files to your local repo, but they will not sync.
<h2>Implementation Details</h2>
<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:
<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>
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:
<pre>
fossil sql "DROP TABLE unversioned; VACUUM;"
</pre>
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
is to send large, frequently-changing files. Appreciate the consequences
before making each change.
There are two bandwidth-saving measures in "<tt>fossil uv sync</tt>".
The first is the regular HTTP payload compression step, done on all
syncs. The second is that Fossil sends hash exchanges to determine
when it can avoid sending duplicate content over the wire unnecessarily.
See the [./sync.wiki|synchronization protocol documentation] for further
information.