|
1
|
<title>Unversioned Content</title> |
|
2
|
|
|
3
|
"Unversioned content" or "unversioned files" are |
|
4
|
files stored in a Fossil repository without history, meaning |
|
5
|
it retains the newest version of each such file, and that alone. |
|
6
|
Unversioned files may have an optional directory name prefix. |
|
7
|
|
|
8
|
Though it omits history, Fossil does sync unversioned content between |
|
9
|
repositories. In the event of a conflict during a sync, it retains |
|
10
|
the most recent version of each unversioned file, discarding |
|
11
|
older versions. |
|
12
|
|
|
13
|
Unversioned files are useful for storing ephemeral content such as |
|
14
|
builds or frequently changing web pages. We store the |
|
15
|
[https://fossil-scm.org/home/uv/download.html|download] page of the |
|
16
|
self-hosting Fossil repository as unversioned content, for |
|
17
|
example. |
|
18
|
|
|
19
|
<h2>Accessing Unversioned Files</h2> |
|
20
|
|
|
21
|
Unversioned files are <u>not</u> a part of a check-out. |
|
22
|
Unversioned files are intended to be accessible as web pages using |
|
23
|
URLs of the form: "<tt>https://example.com/cgi-script/<b>uv</b>/<i>FILENAME</i></tt>". |
|
24
|
In other words, the URI method "<b>uv</b>" (short for "unversioned") |
|
25
|
followed by the name of the unversioned file will retrieve the content |
|
26
|
of the file. The MIME type is inferred from the filename suffix. |
|
27
|
|
|
28
|
The content of unversioned files can also be retrieved using the |
|
29
|
[/help/unversioned|fossil unvers cat <i>FILENAME...</i>] |
|
30
|
or [/help/unversioned|fossil unvers export <i>FILENAME</i>] commands. |
|
31
|
|
|
32
|
A list of all unversioned files on a server can be seen using |
|
33
|
the [/help/www/uvlist|/uvlist] URL. ([/uvlist|example].) |
|
34
|
|
|
35
|
<h2>Syncing Unversioned Files</h2> |
|
36
|
|
|
37
|
Unversioned content does not sync between repositories by default. |
|
38
|
One must request it via commands such as: |
|
39
|
|
|
40
|
<pre> |
|
41
|
fossil sync <b>-u</b> |
|
42
|
fossil clone <b>-u</b> <i>URL local-repo-name</i> |
|
43
|
fossil unversioned sync |
|
44
|
</pre> |
|
45
|
|
|
46
|
The [/help/sync|fossil sync] and [/help/clone|fossil clone] |
|
47
|
commands will synchronize unversioned content if and only if they're |
|
48
|
given the "-u" (or "--unversioned") command-line option. The |
|
49
|
[/help/unversioned|fossil unversioned sync] command synchronizes the |
|
50
|
unversioned content without synchronizing anything else. |
|
51
|
|
|
52
|
Notice that the "-u" option does not work on |
|
53
|
[/help/push|fossil push] or [/help?cmd=pull|fossil pull]. |
|
54
|
The "-u" option is only available on "sync" and "clone". |
|
55
|
A rough equivalent of an unversioned pull would be the |
|
56
|
[/help?cmd=unversioned|fossil unversioned revert] command. The |
|
57
|
"unversioned revert" |
|
58
|
command causes the unversioned content on the local repository to be |
|
59
|
overwritten by the unversioned content found on the remote repository. |
|
60
|
|
|
61
|
Beware that because unversioned file sync is an uncommonly dangerous |
|
62
|
capability — there being no history to revert to in the case of human |
|
63
|
error — even the all-powerful Fossil "setup" user does not get |
|
64
|
unversioned file sync capability by default. See |
|
65
|
[./caps/admin-v-setup.md#dcap | this] for the full details, but the |
|
66
|
short-and-sweet takeaway is that a user needs the "y" capability on the |
|
67
|
remote before they can sync unversioned content. Until then, you're |
|
68
|
allowed to add such files to your local repo, but they will not sync. |
|
69
|
|
|
70
|
<h2>Implementation Details</h2> |
|
71
|
|
|
72
|
<i>(This section outlines the current implementation of unversioned |
|
73
|
files. This is not an interface spec and hence subject to change.)</i> |
|
74
|
|
|
75
|
Unversioned content is stored in the repository in the |
|
76
|
"unversioned" table: |
|
77
|
|
|
78
|
<pre> |
|
79
|
CREATE TABLE unversioned( |
|
80
|
uvid INTEGER PRIMARY KEY AUTOINCREMENT, -- unique ID for this file |
|
81
|
name TEXT UNIQUE, -- Name of the file |
|
82
|
rcvid INTEGER, -- From whence this file was received |
|
83
|
mtime DATETIME, -- Last change (seconds since 1970) |
|
84
|
hash TEXT, -- SHA1 or SHA3-256 hash of uncompressed content |
|
85
|
sz INTEGER, -- Size of uncompressed content |
|
86
|
encoding INT, -- 0: plaintext 1: zlib compressed |
|
87
|
content BLOB -- File content |
|
88
|
); |
|
89
|
</pre> |
|
90
|
|
|
91
|
Fossil does not create the table ahead of need. |
|
92
|
If there are no unversioned files in the repository, the |
|
93
|
"unversioned" table will not exist. Consequently, |
|
94
|
one simple way to purge all unversioned content from a repository |
|
95
|
is to run: |
|
96
|
|
|
97
|
<pre> |
|
98
|
fossil sql "DROP TABLE unversioned; VACUUM;" |
|
99
|
</pre> |
|
100
|
|
|
101
|
Lacking history for unversioned files, Fossil does not attempt delta |
|
102
|
compression on them. |
|
103
|
|
|
104
|
Fossil servers exchange unversioned content whole; it does not attempt |
|
105
|
to "diff" your local version against the remote and send only the |
|
106
|
changes. We point this out because one use-case for unversioned content |
|
107
|
is to send large, frequently-changing files. Appreciate the consequences |
|
108
|
before making each change. |
|
109
|
|
|
110
|
There are two bandwidth-saving measures in "<tt>fossil uv sync</tt>". |
|
111
|
The first is the regular HTTP payload compression step, done on all |
|
112
|
syncs. The second is that Fossil sends hash exchanges to determine |
|
113
|
when it can avoid sending duplicate content over the wire unnecessarily. |
|
114
|
See the [./sync.wiki|synchronization protocol documentation] for further |
|
115
|
information. |
|
116
|
|