1<title>Unversioned Content</title>
2<h1 align="center">Unversioned Content</h1>
3
4"Unversioned content" or "unversioned files" are
5files stored in a Fossil repository without history.
6Only the newest version of each unversioned file is retained.
7
8Though history is omitted, unversioned content is synced between
9repositories.  In the event of a conflict during a sync, the most recent
10version of each unversioned file is retained and older versions are discarded.
11
12Unversioned files are useful for storing ephemeral content such as builds
13or frequently changing web pages.
14The [https://fossil-scm.org/home/uv/download.html|download] page of
15the self-hosting Fossil repository is stored as unversioned
16content, for example.
17
18<h2>Accessing Unversioned Files</h2>
19
20Unversioned files are <u>not</u> a part of a check-out.
21Unversioned files are intended to be accessible as web pages using
22URLs of the form:  "http://domain/cgi-script/<b>uv</b>/<i>FILENAME</i>".
23In other words, the URI method "<b>uv</b>" (short for "unversioned")
24followed by the name of the unversioned file will retrieve the content
25of the file.  The MIME type is inferred from the filename suffix.
26
27The content of unversioned files can also be retrieved using the
28[/help?cmd=unversioned|fossil unvers cat <i>FILENAME</i>] command.
29
30A list of all unversioned files on a server can be seen using
31the [/help?cmd=/uvlist|/uvlist] URL.  ([/uvlist|example]).
32
33<h2>Syncing Unversioned Files</h2>
34
35Unversioned content is synced between repositories, though not by default.
36Special commands or command-line options are required.
37Unversioned content can be synced using the following commands:
38
39<blockquote><pre>
40fossil sync <b>-u</b>
41fossil clone <b>-u</b> <i>URL local-repo-name</i>
42fossil unversioned sync
43</pre></blockquote>
44
45The [/help?cmd=sync|fossil sync] and [/help?cmd=clone|fossil clone]
46commands will synchronize unversioned content if and only if the
47"-u" (or "--unversioned") command-line option is supplied.  The
48[/help?cmd=unversioned|fossil unversioned sync] command will synchronize the
49unversioned content without synchronizing anything else.
50
51Notice that the "-u" option does not work on
52[/help?cmd=push|fossil push] or [/help?cmd=pull|fossil pull].
53The "-u" option is only available on "sync" and "clone".
54
55A rough equivalent of an unversioned pull would be the
56[/help?cmd=unversioned|fossil unversioned revert] command.  The
57"unversioned revert"
58command causes the unversioned content on the local repository to overwritten
59by the unversioned content found on the remote repository.
60
61<h2>Implementation Details</h2>
62
63<i>(This section outlines the current implementation of unversioned
64files.  This is not an interface spec and hence subject to change.)</i>
65
66Unversioned content is stored in the repository in the
67"unversioned" table:
68
69<blockquote><pre>
70CREATE TABLE unversioned(
71  uvid INTEGER PRIMARY KEY AUTOINCREMENT,  -- unique ID for this file
72  name TEXT UNIQUE,       -- Name of the file
73  rcvid INTEGER,          -- From whence this file was received
74  mtime DATETIME,         -- Last change (seconds since 1970)
75  hash TEXT,              -- SHA1 hash of uncompressed content
76  sz INTEGER,             -- Size of uncompressed content
77  encoding INT,           -- 0: plaintext  1: zlib compressed
78  content BLOB            -- File content
79);
80</pre></blockquote>
81
82If there are no unversioned files in the repository, then the
83"unversioned" table does not necessarily exist.
84A simple way to purge all unversioned content from a repository
85is to run:
86
87<blockquote><pre>
88fossil sql "DROP TABLE unversioned; VACUUM;"
89</pre></blockquote>
90
91No delta compression is performed on unversioned files, since there is no
92history to delta against.
93
94Unversioned content is exchanged between servers as whole, uncompressed
95files (though the content does get compressed when the overall HTTP message
96payload is compressed).  SHA1 hash exchanges are used to avoid sending
97content over the wire unnecessarily.  See the
98[./sync.wiki|synchronization protocol documentation] for further
99information.
100