Fossil

Check-in [f187ada6]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add documentation on unversioned content.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: f187ada69767db892615aeeae18f35b7d105bbfc
User & Date: drh 2016-08-18 13:20:05
Context
2016-08-18
13:30
Mention "full text search" as a feature in the web interface documentation. check-in: 63bff950 user: drh tags: trunk
13:20
Add documentation on unversioned content. check-in: f187ada6 user: drh tags: trunk
12:33
Fix the "fossil rebuild" command so that it no longer trashes the unversioned content. Add the -u option to "fossil clone" to retrieve unversioned content during the clone. check-in: a5d8548f user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/index.wiki.

33
34
35
36
37
38
39
40
41
42
43


44
45
46
47
48
49
50
51
52
53
54
55
      [./wikitheory.wiki | wiki], and [./event.wiki | technotes].

  2.  <b>Built-in Web Interface</b> -
      Fossil has a built-in and intuitive [./webui.wiki | web interface]
      with a rich assortment of information pages
      ([./webpage-ex.md|examples]) designed to promote situational awareness.

      This entire website&#185;
      is just a running instance of Fossil.  The pages you see here
      are all [./wikitheory.wiki | wiki] or
      [./embeddeddoc.wiki | embedded documentation].


      When you clone Fossil from one of its
      [./selfhost.wiki | self-hosting repositories],
      you get more than just source code - you get this entire website.
      <span style='font-size:75%;'>(&#185;except the
      [http://www.fossil-scm.org/download.html | download] page)</span>

  3.  <b>Self-Contained</b> -
      Fossil is a single self-contained stand-alone executable.
      To install, simply download a
      <a href="http://www.fossil-scm.org/download.html">precompiled binary</a>
      for Linux, Mac, OpenBSD, or Windows and put it on your $PATH.
      [./build.wiki | Easy-to-compile source code] is also available.







<
|
|
|
>
>



<
<







33
34
35
36
37
38
39

40
41
42
43
44
45
46
47


48
49
50
51
52
53
54
      [./wikitheory.wiki | wiki], and [./event.wiki | technotes].

  2.  <b>Built-in Web Interface</b> -
      Fossil has a built-in and intuitive [./webui.wiki | web interface]
      with a rich assortment of information pages
      ([./webpage-ex.md|examples]) designed to promote situational awareness.


      This entire website is just a running instance of Fossil.
      The pages you see here are all [./wikitheory.wiki | wiki] or
      [./embeddeddoc.wiki | embedded documentation] or (in the case of
      the [/uv/download.html|download] page) 
      [./unvers.wiki | unversioned files].
      When you clone Fossil from one of its
      [./selfhost.wiki | self-hosting repositories],
      you get more than just source code - you get this entire website.



  3.  <b>Self-Contained</b> -
      Fossil is a single self-contained stand-alone executable.
      To install, simply download a
      <a href="http://www.fossil-scm.org/download.html">precompiled binary</a>
      for Linux, Mac, OpenBSD, or Windows and put it on your $PATH.
      [./build.wiki | Easy-to-compile source code] is also available.

Changes to www/mkindex.tcl.

63
64
65
66
67
68
69

70
71
72
73
74
75
76
  sync.wiki {The Fossil Sync Protocol}
  tech_overview.wiki {A Technical Overview Of The Design And Implementation
                      Of Fossil}
  tech_overview.wiki {SQLite Databases Used By Fossil}
  th1.md {The TH1 Scripting Language}
  tickets.wiki {The Fossil Ticket System}
  theory1.wiki {Thoughts On The Design Of The Fossil DVCS}

  webpage-ex.md {Webpage Examples}
  webui.wiki {The Fossil Web Interface}
  wikitheory.wiki {Wiki In Fossil}
}

set permindex {}
set stopwords {fossil and a in of on the to are about used by for or}







>







63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
  sync.wiki {The Fossil Sync Protocol}
  tech_overview.wiki {A Technical Overview Of The Design And Implementation
                      Of Fossil}
  tech_overview.wiki {SQLite Databases Used By Fossil}
  th1.md {The TH1 Scripting Language}
  tickets.wiki {The Fossil Ticket System}
  theory1.wiki {Thoughts On The Design Of The Fossil DVCS}
  unvers.wiki {Unversioned Files}
  webpage-ex.md {Webpage Examples}
  webui.wiki {The Fossil Web Interface}
  wikitheory.wiki {Wiki In Fossil}
}

set permindex {}
set stopwords {fossil and a in of on the to are about used by for or}

Changes to www/permutedindex.html.

79
80
81
82
83
84
85

86
87
88
89
90
91
92
...
197
198
199
200
201
202
203

204
205
206
207
208
209
210
<li><a href="env-opts.md">Environment Variables and Global Options</a></li>
<li><a href="event.wiki">Events</a></li>
<li><a href="webpage-ex.md">Examples &mdash; Webpage</a></li>
<li><a href="inout.wiki">Export To And From Git &mdash; Import And</a></li>
<li><a href="fossil-from-msvc.wiki">Express 2010 IDE &mdash; Integrating Fossil in the Microsoft</a></li>
<li><a href="adding_code.wiki">Features To Fossil &mdash; Adding New</a></li>
<li><a href="fileformat.wiki">File Format &mdash; Fossil</a></li>

<li><a href="branching.wiki">Forking, Merging, and Tagging &mdash; Branching,</a></li>
<li><a href="delta_format.wiki">Format &mdash; Fossil Delta</a></li>
<li><a href="fileformat.wiki">Format &mdash; Fossil File</a></li>
<li><a href="changes.wiki">Fossil Changelog</a></li>
<li><a href="concepts.wiki">Fossil Core Concepts</a></li>
<li><a href="delta_encoder_algorithm.wiki">Fossil Delta Encoding Algorithm</a></li>
<li><a href="delta_format.wiki">Fossil Delta Format</a></li>
................................................................................
<li><a href="customgraph.md">Theming: Customizing the Timeline Graph</a></li>
<li><a href="theory1.wiki">Thoughts On The Design Of The Fossil DVCS</a></li>
<li><a href="custom_ticket.wiki">Ticket System &mdash; Customizing The</a></li>
<li><a href="tickets.wiki">Ticket System &mdash; The Fossil</a></li>
<li><a href="customgraph.md">Timeline Graph &mdash; Theming: Customizing the</a></li>
<li><a href="hints.wiki">Tips And Usage Hints &mdash; Fossil</a></li>
<li><a href="bugtheory.wiki">Tracking In Fossil &mdash; Bug</a></li>

<li><a href="fiveminutes.wiki">Update and Running in 5 Minutes as a Single User</a></li>
<li><a href="hints.wiki">Usage Hints &mdash; Fossil Tips And</a></li>
<li><a href="encryptedrepos.wiki">Use Encrypted Repositories &mdash; How To</a></li>
<li><a href="fiveminutes.wiki">User &mdash; Update and Running in 5 Minutes as a Single</a></li>
<li><a href="ssl.wiki">Using SSL with Fossil</a></li>
<li><a href="env-opts.md">Variables and Global Options &mdash; Environment</a></li>
<li><a href="checkin_names.wiki">Version Names &mdash; Check-in And</a></li>







>







 







>







79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
...
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
<li><a href="env-opts.md">Environment Variables and Global Options</a></li>
<li><a href="event.wiki">Events</a></li>
<li><a href="webpage-ex.md">Examples &mdash; Webpage</a></li>
<li><a href="inout.wiki">Export To And From Git &mdash; Import And</a></li>
<li><a href="fossil-from-msvc.wiki">Express 2010 IDE &mdash; Integrating Fossil in the Microsoft</a></li>
<li><a href="adding_code.wiki">Features To Fossil &mdash; Adding New</a></li>
<li><a href="fileformat.wiki">File Format &mdash; Fossil</a></li>
<li><a href="unvers.wiki">Files &mdash; Unversioned</a></li>
<li><a href="branching.wiki">Forking, Merging, and Tagging &mdash; Branching,</a></li>
<li><a href="delta_format.wiki">Format &mdash; Fossil Delta</a></li>
<li><a href="fileformat.wiki">Format &mdash; Fossil File</a></li>
<li><a href="changes.wiki">Fossil Changelog</a></li>
<li><a href="concepts.wiki">Fossil Core Concepts</a></li>
<li><a href="delta_encoder_algorithm.wiki">Fossil Delta Encoding Algorithm</a></li>
<li><a href="delta_format.wiki">Fossil Delta Format</a></li>
................................................................................
<li><a href="customgraph.md">Theming: Customizing the Timeline Graph</a></li>
<li><a href="theory1.wiki">Thoughts On The Design Of The Fossil DVCS</a></li>
<li><a href="custom_ticket.wiki">Ticket System &mdash; Customizing The</a></li>
<li><a href="tickets.wiki">Ticket System &mdash; The Fossil</a></li>
<li><a href="customgraph.md">Timeline Graph &mdash; Theming: Customizing the</a></li>
<li><a href="hints.wiki">Tips And Usage Hints &mdash; Fossil</a></li>
<li><a href="bugtheory.wiki">Tracking In Fossil &mdash; Bug</a></li>
<li><a href="unvers.wiki">Unversioned Files</a></li>
<li><a href="fiveminutes.wiki">Update and Running in 5 Minutes as a Single User</a></li>
<li><a href="hints.wiki">Usage Hints &mdash; Fossil Tips And</a></li>
<li><a href="encryptedrepos.wiki">Use Encrypted Repositories &mdash; How To</a></li>
<li><a href="fiveminutes.wiki">User &mdash; Update and Running in 5 Minutes as a Single</a></li>
<li><a href="ssl.wiki">Using SSL with Fossil</a></li>
<li><a href="env-opts.md">Variables and Global Options &mdash; Environment</a></li>
<li><a href="checkin_names.wiki">Version Names &mdash; Check-in And</a></li>

Added www/unvers.wiki.





































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
<title>Unversioned Content</title>
<h1 align="center">Unversioned Content</h1>

"Unversioned content" or "unversioned files" are
files stored in a Fossil repository without history.
Only the newest version of each unversioned file is retained.

Though history is omitted, unversioned content is synced between
respositories.  In the event of a conflict during a sync, the most recent
version of each unversioned file is retained and older versions are discarded.

Unversioned files are useful for storing ephemeral content such as builds
or frequently changing web pages.
The [https://www.fossil-scm.org/fossil/uv/download.html|download] page of
the self-hosting Fossil repository is stored 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:  "http://domain/cgi-script/<b>uv</b>/<i>FILENAME</i>".
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 mimetype 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 is synced between respositories, though not by default.
Special commands or command-line options are required.
Unversioned content can be synced using the following commands:

<blockquote><pre>
fossil sync <b>-u</b>
fossil clone <b>-u</b> <i>URL local-repo-name</i>
fossil unversioned sync
</pre></blockquote>

The [/help?cmd=sync|fossil sync] and [/help?cmd=clone|fossil clone]
commands will synchronize unversion content if and only if the
"-u" (or "--unversioned") command-line option is supplied.  The
[/help?cmd=unversioned|fossil unversioned sync] command will synchronize the
unversion 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 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.

<h2>Implementation Details</h2>

<i>(This section outlines the current implementation of unversioned
files.  This is not an interface spec and is hence subject to change.)</i>

Unversioned content is stored in the repository in the 
"unversioned" table:

<blockquote><pre>
CREATE TABLE unversioned(
  name TEXT PRIMARY KEY,  -- Name of the file
  rcvid INTEGER,          -- From whence this file was received
  mtime DATETIME,         -- Last change (seconds since 1970)
  hash TEXT,              -- SHA1 has of uncompressed content
  sz INTEGER,             -- Size of uncompressed content
  encoding INT,           -- 0: plaintext  1: zlib compressed
  content BLOB            -- File content
) WITHOUT ROWID;
</pre></blockquote>

If there are no unversioned files in the repository, then the
"unversioned" table does not necessarily exist.
A simple way to purge all unversioned content from a repository
is to run:

<blockquote><pre>
fossil sql "DROP TABLE unversioned; VACUUM;"
</pre></blockquote>

No delta compression is performed on unversioned files, since there is no
history to delta against.

Unversioned content is exchanged between servers as whole, uncompressed
files (though the content does get compressed when the overall HTTP message
payload is compressed).  SHA1 hash exchanges are used to avoid sending
content over the wire unnecessarily.  See the
[./sync.wiki|synchronization protocol documentation] for further
information.