Fossil

Check-in [bcea5291]
Login

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

Overview
Comment:More documentation updates to highlight recent changes.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: bcea5291cee5f9f4a70d52ec9e6314c16e85c54809baeaa8214e4485acb18b96
User & Date: drh 2019-05-11 01:42:52
Context
2019-05-12
23:48
Improved rendering of the graphs on the /thisdayinhistory page. More generally, improved rendering of multiple graphs on the same page that omit the TIMELINE_DISJOINT flag. check-in: 8e2b8b02 user: drh tags: trunk
2019-05-11
01:42
More documentation updates to highlight recent changes. check-in: bcea5291 user: drh tags: trunk
00:17
Updates to the change log, as well as other minor documentation improvements. check-in: 530963e0 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/markdown.md.

56
57
58
59
60
61
62

63
64
65
66
67
68
69
## Lists ##

>
     *   bullet item
     +   bullet item
     -   bullet item
     1.  numbered item


> A two-level list is created by placing additional whitespace before the
> **\***/**+**/**-**/**1.** of the secondary items.

>
     *   top-level item
       * secondary item







>







56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
## Lists ##

>
     *   bullet item
     +   bullet item
     -   bullet item
     1.  numbered item
     2)  numbered item

> A two-level list is created by placing additional whitespace before the
> **\***/**+**/**-**/**1.** of the secondary items.

>
     *   top-level item
       * secondary item

Changes to www/checkin_names.wiki.

140
141
142
143
144
145
146
147
148
149
150



151

152
153
154
155
156
157


158
159
160
161
162
163
164
Again, this behavior only occurs on a few commands where it make sense.

<h2>Timestamps</h2>

A timestamp in one of the formats shown below means the most recent
check-in that occurs no later than the timestamp given:

  *   <i>YYYY-MM-DD</i>
  *   <i>YYYY-MM-DD HH:MM</i>
  *   <i>YYYY-MM-DD HH:MM:SS</i>
  *   <i>YYYY-MM-DD HH:MM:SS.SSS</i>





The space between the day and the year can optionally be
replaced by an uppercase <b>T</b> and the entire timestamp can
optionally be followed by "<b>z</b>" or "<b>Z</b>".  In the fourth
form with fractional seconds, any number of digits may follow the
decimal point, though due to precision limits only the first three
digits will be significant.



In its default configuration, Fossil interprets and displays all dates
in Universal Coordinated Time (UTC).  This tends to work the best for
distributed projects where participants are scattered around the globe.
But there is an option on the Admin/Timeline page of the web-interface to
switch to local time.  The "<b>Z</b>" suffix on a timestamp check-in
name is meaningless if Fossil is in the default mode of using UTC for







|
|
|
|
>
>
>

>
|




|
>
>







140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
Again, this behavior only occurs on a few commands where it make sense.

<h2>Timestamps</h2>

A timestamp in one of the formats shown below means the most recent
check-in that occurs no later than the timestamp given:

  1.   <i>YYYY-MM-DD</i>
  2.   <i>YYYY-MM-DD HH:MM</i>
  3.   <i>YYYY-MM-DD HH:MM:SS</i>
  4.   <i>YYYY-MM-DD HH:MM:SS.SSS</i>
  5.   <i>YYYYMMDD</i>
  6.   <i>YYYYMMDDHHMM</i>
  7.   <i>YYYYMMDDHHMMSS</i>

In the second through the fourth forms,
the space between the day and the year can optionally be
replaced by an uppercase <b>T</b> and the entire timestamp can
optionally be followed by "<b>z</b>" or "<b>Z</b>".  In the fourth
form with fractional seconds, any number of digits may follow the
decimal point, though due to precision limits only the first three
digits will be significant.  The final three pure-digit forms 
without punctuation are only valid if the number they encode is
not also the prefix of an artifact hash.

In its default configuration, Fossil interprets and displays all dates
in Universal Coordinated Time (UTC).  This tends to work the best for
distributed projects where participants are scattered around the globe.
But there is an option on the Admin/Timeline page of the web-interface to
switch to local time.  The "<b>Z</b>" suffix on a timestamp check-in
name is meaningless if Fossil is in the default mode of using UTC for

Changes to www/fossil-v-git.wiki.

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
...
157
158
159
160
161
162
163




























164
165
166
167
168
169
170
171
...
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
...
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
...
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
...
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290

Differences between Fossil and Git are summarized by the following table,
with further description in the text that follows.

<blockquote><table border=1 cellpadding=5 align=center>
<tr><th width="50%">GIT</th><th width="50%">FOSSIL</th></tr>
<tr><td>File versioning only</td>
    <td>Versioning, Tickets, Wiki, and Technotes</td></tr>
<tr><td>Ad-hoc, pile-of-files key/value database</td>
    <td>Relational SQL database</td></tr>
<tr><td>Bazaar-style development</td><td>Cathedral-style development</td></tr>
<tr><td>Designed for Linux development</td>
    <td>Designed for SQLite development</td></tr>


<tr><td>Lots of little tools</td><td>Stand-alone executable</td></tr>
<tr><td>One check-out per repository</td>
    <td>Many check-outs per repository</td></tr>
<tr><td>Remembers what you should have done</td>
    <td>Remembers what you actually did</td></tr>
<tr><td>GPL</td><td>BSD</td></tr>
</table></blockquote>

<h3>2.1 Feature Set</h3>

Git provides file versioning services only, whereas Fossil adds
integrated [./wikitheory.wiki | wiki],
[./bugtheory.wiki | ticketing &amp; bug tracking],
[./embeddeddoc.wiki | embedded documentation], and
[./event.wiki | Technical notes].
These additional capabilities are available for Git as 3rd-party and/or
user-installed add-ons, but with Fossil they are integrated into
the design.  One way to describe Fossil is that it is
"[https://github.com/ | github]-in-a-box".

If you clone Git's self-hosting repository you get just Git's source code.
If you clone Fossil's self-hosting repository, you get the entire
................................................................................
Git is designed for this scenario.

SQLite uses cathedral-style development.  95% of the code in SQLite
comes from just three programmers, 64% from just the lead developer.
And all SQLite developers know each other well and interact daily.
Fossil is designed for this development model.





























<h3>2.5 Lots of little tools vs. Self-contained system</h3>

Git consists of many small tools, each doing one small part of the job,
which can be recombined (by experts) to perform powerful operations.
Git has a lot of complexity and many dependencies and requires an "installer"
script or program to get it running.

Fossil is a single self-contained stand-alone executable with hardly
................................................................................

The designer of Git says that the unix philosophy is to have lots of
small tools that collaborate to get the job done.  The designer of
Fossil says that the unix philosophy is "it just works".  Both
individuals have written their DVCSes to reflect their own view
of the "unix philosophy".

<h3>2.6 One vs. Many Check-outs per Repository</h3>

A "repository" in Git is a pile-of-files in the ".git" subdirectory
of a single check-out.  The check-out and the repository are located
together in the filesystem.

With Fossil, a "repository" is a single SQLite database file
that can be stored anywhere.  There
................................................................................
The check-out and the repository in Git used to be inseparable.
More recently, Git has been enhanced with the
"[https://git-scm.com/docs/git-worktree|worktree]" command that
allows a single repository to host multiple check-outs.  However,
the interface is sufficiently difficult to use that most people
find it easier to create a separate clone for each check-out.

<h3>2.7 What you should have done vs. What you actually did</h3>

Git puts a lot of emphasis on maintaining
a "clean" check-in history.  Extraneous and experimental branches by
individual developers often never make it into the main repository.  And
branches are often rebased before being pushed, to make
it appear as if development had been linear.  Git strives to record what
the development of a project should have looked like had there been no
................................................................................
is that this makes the history "accurate".  In actual practice, the
superior reporting tools available in Fossil mean that the added "mess"
is not a factor.

One commentator has mused that Git records history according to
the victors, whereas Fossil records history as it actually happened.

<h3>2.8 GPL vs. BSD</h3>

Git is covered by the GPL license whereas Fossil is covered by
a two-clause BSD license.

Consider the difference between GPL and BSD licenses:  GPL is designed
to make writing easier at the expense of making reading harder.  BSD is
designed to make reading easier at the expense of making writing harder.
................................................................................
  *  <b>The ability to show descendents of a check-in.</b>

   Both Git and Fossil can easily find the ancestors of a check-in.  But
   only Fossil shows the descendents.  (It is possible to find the
   descendents of a check-in in Git using the log, but that is sufficiently
   difficult that nobody ever actually does it.)

  *  <b>Wiki, Embedded documentation, Trouble-tickets, and Tech-Notes</b>

   Git only provides versioning of source code.  Fossil strives to provide
   other related configuration management services as well.

  *  <b>Named branches</b>

   Branches in Fossil have persistent names that are propagated
   to collaborators via [/help?cmd=push|push] and [/help?cmd=pull|pull].
   All developers see the same name on the same branch.  Git, in contrast,
   uses only local branch names, so developers working on the







|





>
>













|
|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|







 







|







 







|







 







|







 







|


|







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
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
...
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
...
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
...
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
...
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320

Differences between Fossil and Git are summarized by the following table,
with further description in the text that follows.

<blockquote><table border=1 cellpadding=5 align=center>
<tr><th width="50%">GIT</th><th width="50%">FOSSIL</th></tr>
<tr><td>File versioning only</td>
    <td>Versioning, Tickets, Wiki, Technotes, Forum</td></tr>
<tr><td>Ad-hoc, pile-of-files key/value database</td>
    <td>Relational SQL database</td></tr>
<tr><td>Bazaar-style development</td><td>Cathedral-style development</td></tr>
<tr><td>Designed for Linux development</td>
    <td>Designed for SQLite development</td></tr>
<tr><td>Focus on individual branches</td>
    <td>Focus on the entire tree of changes</td></tr>
<tr><td>Lots of little tools</td><td>Stand-alone executable</td></tr>
<tr><td>One check-out per repository</td>
    <td>Many check-outs per repository</td></tr>
<tr><td>Remembers what you should have done</td>
    <td>Remembers what you actually did</td></tr>
<tr><td>GPL</td><td>BSD</td></tr>
</table></blockquote>

<h3>2.1 Feature Set</h3>

Git provides file versioning services only, whereas Fossil adds
integrated [./wikitheory.wiki | wiki],
[./bugtheory.wiki | ticketing &amp; bug tracking],
[./embeddeddoc.wiki | embedded documentation], 
[./event.wiki | Technical notes], and a [./forum.wiki | forum].
These additional capabilities are available for Git as 3rd-party and/or
user-installed add-ons, but with Fossil they are integrated into
the design.  One way to describe Fossil is that it is
"[https://github.com/ | github]-in-a-box".

If you clone Git's self-hosting repository you get just Git's source code.
If you clone Fossil's self-hosting repository, you get the entire
................................................................................
Git is designed for this scenario.

SQLite uses cathedral-style development.  95% of the code in SQLite
comes from just three programmers, 64% from just the lead developer.
And all SQLite developers know each other well and interact daily.
Fossil is designed for this development model.

<h3>2.5 Individual Branches vs. The Entire Change History</h3>

Both Fossil and Git store history as a directed acyclic graph (DAG)
of changes.  But Git tends to focus more on individual branches of
the DAG, whereas Fossil puts more emphasis on the entire DAG.

For example, the default "sync" behavior in Git is to only sync
a single branch, whereas with Fossil the only sync option it to
sync the entire DAG.  Git commands, and Git web interfaces such as
GitHub and/or GitLab, tend to show only a single branch at
a time, whereas Fossil usually shows all parallel branches all at
once.  Git has commands like "rebase" that help keep all relevant
changes on a single branch, whereas Fossil encourages a style of
many concurrent branches constantly springing into existance,
undergoing active development in parallel for a few days or weeks, then
merging back into the main line and disappearing.

This difference in emphasis arises from the different purposes of
the two systems.  Git focuses on individual branches, because that
is exactly what you want for a highly-distributed bazaar-style project
such as Linux.  Linus Torvalds does not want to see every check-in
by every contributor to Linux, as such extreme visibility does not scale
well.  But Fossil was written for the cathedral-style SQLite project
with just a handful of active committers.  Seeing all
changes on all branches all at once helps keep the whole team
up-to-date with what everybody else is doing, resulting in a more 
tightly focused and cohesive implementation.

<h3>2.6 Lots of little tools vs. Self-contained system</h3>

Git consists of many small tools, each doing one small part of the job,
which can be recombined (by experts) to perform powerful operations.
Git has a lot of complexity and many dependencies and requires an "installer"
script or program to get it running.

Fossil is a single self-contained stand-alone executable with hardly
................................................................................

The designer of Git says that the unix philosophy is to have lots of
small tools that collaborate to get the job done.  The designer of
Fossil says that the unix philosophy is "it just works".  Both
individuals have written their DVCSes to reflect their own view
of the "unix philosophy".

<h3>2.7 One vs. Many Check-outs per Repository</h3>

A "repository" in Git is a pile-of-files in the ".git" subdirectory
of a single check-out.  The check-out and the repository are located
together in the filesystem.

With Fossil, a "repository" is a single SQLite database file
that can be stored anywhere.  There
................................................................................
The check-out and the repository in Git used to be inseparable.
More recently, Git has been enhanced with the
"[https://git-scm.com/docs/git-worktree|worktree]" command that
allows a single repository to host multiple check-outs.  However,
the interface is sufficiently difficult to use that most people
find it easier to create a separate clone for each check-out.

<h3>2.8 What you should have done vs. What you actually did</h3>

Git puts a lot of emphasis on maintaining
a "clean" check-in history.  Extraneous and experimental branches by
individual developers often never make it into the main repository.  And
branches are often rebased before being pushed, to make
it appear as if development had been linear.  Git strives to record what
the development of a project should have looked like had there been no
................................................................................
is that this makes the history "accurate".  In actual practice, the
superior reporting tools available in Fossil mean that the added "mess"
is not a factor.

One commentator has mused that Git records history according to
the victors, whereas Fossil records history as it actually happened.

<h3>2.9 GPL vs. BSD</h3>

Git is covered by the GPL license whereas Fossil is covered by
a two-clause BSD license.

Consider the difference between GPL and BSD licenses:  GPL is designed
to make writing easier at the expense of making reading harder.  BSD is
designed to make reading easier at the expense of making writing harder.
................................................................................
  *  <b>The ability to show descendents of a check-in.</b>

   Both Git and Fossil can easily find the ancestors of a check-in.  But
   only Fossil shows the descendents.  (It is possible to find the
   descendents of a check-in in Git using the log, but that is sufficiently
   difficult that nobody ever actually does it.)

  *  <b>Wiki, Embedded documentation, Trouble-tickets, Tech-Notes, and Forum</b>

   Git only provides versioning of source code.  Fossil strives to provide
   other related project management services as well.

  *  <b>Named branches</b>

   Branches in Fossil have persistent names that are propagated
   to collaborators via [/help?cmd=push|push] and [/help?cmd=pull|pull].
   All developers see the same name on the same branch.  Git, in contrast,
   uses only local branch names, so developers working on the

Changes to www/index.wiki.

60
61
62
63
64
65
66
67
68

69
70
71
72
73
74
75
      restrictive firewalls, including [./quickstart.wiki#proxy|proxies].
      The protocol is
      [./stats.wiki | bandwidth efficient] to the point that Fossil can be
      used comfortably over dial-up or over the exceedingly slow Wifi on
      airliners.

  5.  <b>CGI/SCGI Enabled</b> -  No server is required, but if you want to
      set one up, Fossil supports four easy
      [./server.wiki | server configurations].


  6.  <b>Autosync</b> -
      Fossil supports [./concepts.wiki#workflow | "autosync" mode]
      which helps to keep projects moving
      forward by reducing the amount of needless
      [./branching.wiki | forking and merging] often
      associated with distributed projects.







|
|
>







60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
      restrictive firewalls, including [./quickstart.wiki#proxy|proxies].
      The protocol is
      [./stats.wiki | bandwidth efficient] to the point that Fossil can be
      used comfortably over dial-up or over the exceedingly slow Wifi on
      airliners.

  5.  <b>CGI/SCGI Enabled</b> -  No server is required, but if you want to
      set one up, Fossil supports four easy [./server.wiki | server configurations].
      You can also easily set up your server to automatically
      [./mirrortogithub.md | mirror content on GitHub].

  6.  <b>Autosync</b> -
      Fossil supports [./concepts.wiki#workflow | "autosync" mode]
      which helps to keep projects moving
      forward by reducing the amount of needless
      [./branching.wiki | forking and merging] often
      associated with distributed projects.

Changes to www/inout.wiki.

46
47
48
49
50
51
52









53
54
55
56
57
58
59

As with the "import" command, the --git option is not required
since the git-fast-export file format is currently the only VCS interchange
format that Fossil will generate.  However,
future versions of Fossil might add the ability to generate other
VCS interchange formats, and so for compatibility, the use of the --git
option recommended.










<h2>Bidirectional Synchronization</h2>
Fossil also has the ability to synchronize with a Git repository via repeated
imports and/or exports.  To do this, it uses marks files to store a record of
artifacts which are known by both Git and Fossil to exist at a given point in
time.








>
>
>
>
>
>
>
>
>







46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

As with the "import" command, the --git option is not required
since the git-fast-export file format is currently the only VCS interchange
format that Fossil will generate.  However,
future versions of Fossil might add the ability to generate other
VCS interchange formats, and so for compatibility, the use of the --git
option recommended.

<h2>Mirror A Fossil Repository In Git</h2>

Fossil version 2.9 and later supports a simple mechanism for
doing a Git or
[./mirrortogithub.md|GitHub mirror of a Fossil repository].
See that separate document for details.  Fossil is self-hosting,
but a [https://github.com/drhsqlite/fossil-mirror|GitHub mirror of Fossil]
is available as a proof-of-concept.

<h2>Bidirectional Synchronization</h2>
Fossil also has the ability to synchronize with a Git repository via repeated
imports and/or exports.  To do this, it uses marks files to store a record of
artifacts which are known by both Git and Fossil to exist at a given point in
time.

Changes to www/selfhost.wiki.

8
9
10
11
12
13
14


15
16
17
18
19
20
21
..
65
66
67
68
69
70
71
72


  3.  [https://www3.fossil-scm.org/site.cgi]


The canonical repository is (1).  Repositories (2) and (3) automatically
stay in synchronization with (1) via a
<a href="http://en.wikipedia.org/wiki/Cron">cron job</a> that invokes
"fossil sync" at regular intervals.



Note that the two secondary repositories are more than just read-only mirrors.
All three servers support full read/write capabilities.
Changes (such as new tickets or wiki or check-ins) can be implemented
on any of the three servers and those changes automatically propagate to the
other two servers.

................................................................................
<blockquote><pre>
/home/hwaci/bin/fossil sync -R /home/hwaci/fossil/fossil.fossil
</pre></blockquote>

Server (2) is a
<a href="http://www.linode.com/">Linode 4096</a> located in Newark, NJ
and set up just like the canonical server (1) with the addition of a
cron job for synchronization as in server (3).









>
>







 







|
>
>
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
..
67
68
69
70
71
72
73
74
75
76
  3.  [https://www3.fossil-scm.org/site.cgi]


The canonical repository is (1).  Repositories (2) and (3) automatically
stay in synchronization with (1) via a
<a href="http://en.wikipedia.org/wiki/Cron">cron job</a> that invokes
"fossil sync" at regular intervals.
Repository (2) also publishes a
[./mirrortogithub.md|GitHub mirror of Fossil] as a demonstration.

Note that the two secondary repositories are more than just read-only mirrors.
All three servers support full read/write capabilities.
Changes (such as new tickets or wiki or check-ins) can be implemented
on any of the three servers and those changes automatically propagate to the
other two servers.

................................................................................
<blockquote><pre>
/home/hwaci/bin/fossil sync -R /home/hwaci/fossil/fossil.fossil
</pre></blockquote>

Server (2) is a
<a href="http://www.linode.com/">Linode 4096</a> located in Newark, NJ
and set up just like the canonical server (1) with the addition of a
cron job for synchronization.  The same cron job also runs the
[/help?cmd=git|fossil git export] command after each sync in order to
[./mirrortogithub.md|mirror all changes to GitHub].

Changes to www/webui.wiki.

4
5
6
7
8
9
10

11
12
13
14
15
16
17
This web interface provides everything you need to run a software
development project:

  *  [./bugtheory.wiki | Ticketing and bug tracking]
  *  [./wikitheory.wiki | Wiki]
  *  [./embeddeddoc.wiki | On-line documentation]
  *  [./event.wiki | Technical notes]

  *  Timelines
  *  Full text search over all of the above
  *  Status information
  *  Graphs of revision and branching history
  *  File and version lists and differences
  *  Download historical versions as ZIP archives
  *  Historical change data







>







4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
This web interface provides everything you need to run a software
development project:

  *  [./bugtheory.wiki | Ticketing and bug tracking]
  *  [./wikitheory.wiki | Wiki]
  *  [./embeddeddoc.wiki | On-line documentation]
  *  [./event.wiki | Technical notes]
  *  [./forum.wiki | Forum]
  *  Timelines
  *  Full text search over all of the above
  *  Status information
  *  Graphs of revision and branching history
  *  File and version lists and differences
  *  Download historical versions as ZIP archives
  *  Historical change data

Changes to www/wikitheory.wiki.

6
7
8
9
10
11
12


13
14
15
16
17
18
19
..
54
55
56
57
58
59
60
61
62
63
64
65
66


















   *  Stand-alone wiki pages.
   *  Description and comments in [./bugtheory.wiki | bug reports].
   *  Check-in comments.
   *  [./embeddeddoc.wiki | Embedded documentation] files whose
      name ends in ".wiki" or ".md" or ".markdown".
   *  [./event.wiki | Technical notes].



The [/wiki_rules | formatting rules for fossil wiki]
are designed to be simple and intuitive.  The idea is that wiki provides
paragraph breaks, numbered and bulleted lists, and hyperlinking for
simple documents together with a safe subset of HTML for more complex
formatting tasks.

................................................................................
so that only developers with check-in privileges can change it.
Embedded documentation serves this latter purpose.  Both forms of documentation
use the exact same markup.  Some projects may choose to
use both forms of documentation at the same time.  Because the same
format is used, it is trivial to move a file from wiki to embedded documentation
or back again as the project evolves.

<h2>Bug-reports and check-in comments</h2>

The comments on check-ins and the text in the descriptions of bug reports
both use wiki formatting.  Exactly the same set of formatting rules apply.
There is never a need to learn one formatting language for documentation
and a different markup for bugs or for check-in comments.
























>
>







 







|





>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
..
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

   *  Stand-alone wiki pages.
   *  Description and comments in [./bugtheory.wiki | bug reports].
   *  Check-in comments.
   *  [./embeddeddoc.wiki | Embedded documentation] files whose
      name ends in ".wiki" or ".md" or ".markdown".
   *  [./event.wiki | Technical notes].
   *  [./forum.wiki | Forum messages].
   *  Auxiliary notes on check-ins and branches.

The [/wiki_rules | formatting rules for fossil wiki]
are designed to be simple and intuitive.  The idea is that wiki provides
paragraph breaks, numbered and bulleted lists, and hyperlinking for
simple documents together with a safe subset of HTML for more complex
formatting tasks.

................................................................................
so that only developers with check-in privileges can change it.
Embedded documentation serves this latter purpose.  Both forms of documentation
use the exact same markup.  Some projects may choose to
use both forms of documentation at the same time.  Because the same
format is used, it is trivial to move a file from wiki to embedded documentation
or back again as the project evolves.

<h2>Bug-reports and check-in comments and Forum messages</h2>

The comments on check-ins and the text in the descriptions of bug reports
both use wiki formatting.  Exactly the same set of formatting rules apply.
There is never a need to learn one formatting language for documentation
and a different markup for bugs or for check-in comments.

<h2>Auxiliary notes attached to check-ins or branches</h2>

Stand-alone wiki pages with special names "branch/<i>BRANCHNAME</i>"
or "checkin/<i>HASH</i>" are associated with the corresponding
branch or check-in.  The wiki text appears in an "About" section of
timelines and info screens.  Examples:

   *  [/timeline?r=graph-test-branch] shows the text of the
      [/wiki?name=branch/graph-test-branch|branch/graph-test-branch]
      wiki page at the top of the timeline
   *  [/info/19c60b7fc9e2] shows the text of the
      [/wiki?name=checkin/19c60b7fc9e2400e56a6f938bbad0e34ca746ca2eabdecac10945539f1f5e8c6|checkin/19c60b7fc9e2...]
      wiki page in the "About" section.

This special wiki pages are very useful for recording historical
notes.