Fossil SCM

fossil-scm / www / unvers.wiki

Source Blame History 115 lines

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

Fossil SCM

Keyboard Shortcuts