1 files changed, 115 insertions, 0 deletions
diff --git a/www/unvers.wiki b/www/unvers.wiki
new file mode 100644
index 0000000..9c581a3
--- /dev/null
+++ b/www/unvers.wiki
@@ -0,0 +1,115 @@
+<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.
+Unversioned files may have an optional directory name prefix.
+
+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/unversioned|fossil unvers cat <i>FILENAME...</i>]
+or [/help/unversioned|fossil unvers export <i>FILENAME</i>] commands.
+
+A list of all unversioned files on a server can be seen using
+the [/help/www/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/sync|fossil sync] and [/help/clone|fossil clone]
+commands will synchronize unversioned content if and only if they're
+given the "-u" (or "--unversioned") command-line option.  The
+[/help/unversioned|fossil unversioned sync] command synchronizes the
+unversioned content without synchronizing anything else.
+
+Notice that the "-u" option does not work on
+[/help/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 be
+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.