Fossil

Check-in [b16b4337]
Login

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

Overview
Comment:Fix documentation typos.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: b16b4337b9f5736afc279cbcdd53fb60d667c1c9
User & Date: drh 2010-06-11 12:27:51
Context
2010-06-13
15:58
Add the ability to escape Wiki page names in hyperlinks using a wiki: prefix. Ticket [f58a05747498d3aaa9ea1e4f8f4015c209dfc54a]. check-in: d6b2c387 user: drh tags: trunk
2010-06-11
12:27
Fix documentation typos. check-in: b16b4337 user: drh tags: trunk
12:02
Change the default style to center the title with the project name above and with 200 pixel wide logo and status boxes to the left and right. check-in: 15b29325 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/branching.wiki.

49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
...
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
...
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250

Fossil tries to prevent forks.  Suppose the two programmers who were
editing check-in 2 are named Alice and Bob.  Suppose Alice finished her
edits first and did a commit, resulting in check-in 3.  Later, when Bob
tried to commit his changes, fossil would try to verify that check-in 2
was still a leaf.  Fossil would see that check-in 3 had occurred and would
abort Bob's commit attempt with a message "would fork".  This allows Bob
to do a "fossil update" which would pull in Alices changes and merge them
together with his own changes.  After merging, Bob could then commit
check-in 4 as a child of check-in 3 and the result would be a linear graph
as shown in figure 1.  This is how CVS works.  This is also how fossil
works in "autosync" mode.

But it might be that Bob is off-network when he does his commit, so he
has no way of knowing that Alice has already committed her changes.
Or, it could be that Bob has turned off "autosync" mode in SQLite.  Or,
maybe Bob just doesn't want to merge in Alices changes before he has
saved his own, so he forces the commit to occur using the "--force" option
to the fossil <b>commit</b> command.  For whatever reason, two commits against
check-in 2 have occurred and now the tree has two leaves.

So which version of the project is the "latest" in the sense of having
the most features and the most bug fixes?  When there is more than
one leaf in the graph, you don't really know.  So we like to have
................................................................................
what branch the check-in is a member of.
The default branch is called "trunk".  All tags that begin with "<b>sym-</b>"
are symbolic name tags.  When a symbolic name tag is attached to a
check-in, that allows you to refer to that check-in by its symbolic
name rather than by its 40-character SHA1 hash name.  When a symbolic name
tag propagates (as does the <b>sym-trunk</b> tag) then referring to that
name is the same as referring to the most recent check-in with that name.
Thus the two tags on check-in one cause all decendents to be in the
"trunk" branch and to have the symbolic name "trunk".

Check-in 4 has a <b>branch</b> tag which changes the name of the branch
to "test".  The branch tag on check-in 4 propagates to check-ins 6 and 9.
But because tag propagation does not follow merge links, the <b>branch=test</b>
tag does not propagate to check-ins 7, 8, or 10.  Note also that the
<b>branch</b> tag on check-in 4 blocks the propagation of <b>branch=trunk</b>
................................................................................
<dt><b>Branch</b></dt>
<dd><p>A branch is a set of check-ins that have the same value for their
branch property.</p></dd>
<dt><b>Leaf</b></dt>
<dd><p>A leaf is a check-in that has no children in the same branch.</p></dd>
<dt><b>Closed Leaf</b></dt>
<dd><p>A closed leaf is leaf that has the <b>closed</b> tag.  Such leaves
are intented to never be extended with descendents and hence are omitted
from lists of leaves in the command-line and web interface.</p></dd>
<dt><b>Open Leaf</b></dt>
<dd><p>A open leaf is a leaf that is not closed.</p></dd>
<dt><b>Fork</b></dt>
<dd><p>A fork occurs when a check-in has two or more direct (non-merge)
children in the same branch.</p></dd>
<dt><b>Branch Point</b></dt>







|








|







 







|







 







|







49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
...
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
...
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250

Fossil tries to prevent forks.  Suppose the two programmers who were
editing check-in 2 are named Alice and Bob.  Suppose Alice finished her
edits first and did a commit, resulting in check-in 3.  Later, when Bob
tried to commit his changes, fossil would try to verify that check-in 2
was still a leaf.  Fossil would see that check-in 3 had occurred and would
abort Bob's commit attempt with a message "would fork".  This allows Bob
to do a "fossil update" which would pull in Alice's changes and merge them
together with his own changes.  After merging, Bob could then commit
check-in 4 as a child of check-in 3 and the result would be a linear graph
as shown in figure 1.  This is how CVS works.  This is also how fossil
works in "autosync" mode.

But it might be that Bob is off-network when he does his commit, so he
has no way of knowing that Alice has already committed her changes.
Or, it could be that Bob has turned off "autosync" mode in SQLite.  Or,
maybe Bob just doesn't want to merge in Alice's changes before he has
saved his own, so he forces the commit to occur using the "--force" option
to the fossil <b>commit</b> command.  For whatever reason, two commits against
check-in 2 have occurred and now the tree has two leaves.

So which version of the project is the "latest" in the sense of having
the most features and the most bug fixes?  When there is more than
one leaf in the graph, you don't really know.  So we like to have
................................................................................
what branch the check-in is a member of.
The default branch is called "trunk".  All tags that begin with "<b>sym-</b>"
are symbolic name tags.  When a symbolic name tag is attached to a
check-in, that allows you to refer to that check-in by its symbolic
name rather than by its 40-character SHA1 hash name.  When a symbolic name
tag propagates (as does the <b>sym-trunk</b> tag) then referring to that
name is the same as referring to the most recent check-in with that name.
Thus the two tags on check-in one cause all descendants to be in the
"trunk" branch and to have the symbolic name "trunk".

Check-in 4 has a <b>branch</b> tag which changes the name of the branch
to "test".  The branch tag on check-in 4 propagates to check-ins 6 and 9.
But because tag propagation does not follow merge links, the <b>branch=test</b>
tag does not propagate to check-ins 7, 8, or 10.  Note also that the
<b>branch</b> tag on check-in 4 blocks the propagation of <b>branch=trunk</b>
................................................................................
<dt><b>Branch</b></dt>
<dd><p>A branch is a set of check-ins that have the same value for their
branch property.</p></dd>
<dt><b>Leaf</b></dt>
<dd><p>A leaf is a check-in that has no children in the same branch.</p></dd>
<dt><b>Closed Leaf</b></dt>
<dd><p>A closed leaf is leaf that has the <b>closed</b> tag.  Such leaves
are intented to never be extended with descendants and hence are omitted
from lists of leaves in the command-line and web interface.</p></dd>
<dt><b>Open Leaf</b></dt>
<dd><p>A open leaf is a leaf that is not closed.</p></dd>
<dt><b>Fork</b></dt>
<dd><p>A fork occurs when a check-in has two or more direct (non-merge)
children in the same branch.</p></dd>
<dt><b>Branch Point</b></dt>

Changes to www/faq.wiki.

68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
<a name="q4"></a>
<p><b>(4) How do I create a private branch that won't get pushed back to the
  main repository.</b></p>

<blockquote>Use the <b>--private</b> command-line option on the 
<b>commit</b> command.  The result will be a check-in which exists on
your local repository only and is never pushed to other repositories.  
All descendents of a private check-in are also private.

Unless you specify something different using the <b>--branch</b> and/or
<b>--bgcolor</b> options, the new private check-in will be put on a branch
named "private" with an orange background color.

You can merge from the trunk into your private branch in order to keep
your private branch in sync with the latest changes on the trunk.  Once







|







68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
<a name="q4"></a>
<p><b>(4) How do I create a private branch that won't get pushed back to the
  main repository.</b></p>

<blockquote>Use the <b>--private</b> command-line option on the 
<b>commit</b> command.  The result will be a check-in which exists on
your local repository only and is never pushed to other repositories.  
All descendants of a private check-in are also private.

Unless you specify something different using the <b>--branch</b> and/or
<b>--bgcolor</b> options, the new private check-in will be put on a branch
named "private" with an orange background color.

You can merge from the trunk into your private branch in order to keep
your private branch in sync with the latest changes on the trunk.  Once

Changes to www/fileformat.wiki.

241
242
243
244
245
246
247
248
249
250
251
252
253
254
255

Control artifacts are used to assign properties to other artifacts
within the repository.  The basic format of a control artifact is
the same as a manifest or cluster.  A control artifact is a text
files divided into cards by newline characters.  Each card has a
single-character card type followed by arguments.  Spaces separate
the card type and the arguments.  No surplus whitespace is allowed.
All cards must occur in strict lexigraphical order.

Allowed cards in a control artifact are as follows:

<blockquote>
<b>D</b> <i>time-and-date-stamp</i><br />
<b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name  artifact-id  ?value?</i><br />
<b>U</b> <i>user-name</i><br />







|







241
242
243
244
245
246
247
248
249
250
251
252
253
254
255

Control artifacts are used to assign properties to other artifacts
within the repository.  The basic format of a control artifact is
the same as a manifest or cluster.  A control artifact is a text
files divided into cards by newline characters.  Each card has a
single-character card type followed by arguments.  Spaces separate
the card type and the arguments.  No surplus whitespace is allowed.
All cards must occur in strict lexicographical order.

Allowed cards in a control artifact are as follows:

<blockquote>
<b>D</b> <i>time-and-date-stamp</i><br />
<b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name  artifact-id  ?value?</i><br />
<b>U</b> <i>user-name</i><br />

Changes to www/index.wiki.

110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
     not yet born.
  *  A tutorial on [./branching.wiki | branching], what it means and how
     to do it using fossil.
  *  The [./selfcheck.wiki | automatic self-check] mechanism
     helps insure project integrity.
  *  Fossil contains a [./wikitheory.wiki | built-in wiki].
  *  There is a
    [http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users | mailing list] (with publically readable
     [http://www.mail-archive.com/fossil-users@lists.fossil-scm.org | archives]
     available for discussing fossil issues.
  *  [./stats.wiki | Performance statistics] taken from real-world projects
     hosted on fossil.
  *  How to [./shunning.wiki | delete content] from a fossil repository.
  *  How Fossil does [./password.wiki | password management].
  *  Some (unfinished but expanding) extended







|







110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
     not yet born.
  *  A tutorial on [./branching.wiki | branching], what it means and how
     to do it using fossil.
  *  The [./selfcheck.wiki | automatic self-check] mechanism
     helps insure project integrity.
  *  Fossil contains a [./wikitheory.wiki | built-in wiki].
  *  There is a
    [http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users | mailing list] (with publicly readable
     [http://www.mail-archive.com/fossil-users@lists.fossil-scm.org | archives]
     available for discussing fossil issues.
  *  [./stats.wiki | Performance statistics] taken from real-world projects
     hosted on fossil.
  *  How to [./shunning.wiki | delete content] from a fossil repository.
  *  How Fossil does [./password.wiki | password management].
  *  Some (unfinished but expanding) extended

Changes to www/newrepo.wiki.

30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
..
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
</verbatim>

The <tt>ui</tt> command starts up a server (with an optional <tt>-port
NUMBER</tt> argument) and launches a web browser pointing at the
fossil server. From there it takes just a few moments to configure the
repo. Most importantly, go to the Admin menu, then the Users link, and
set your account name and password, and grant your account all access
priviledges. (I also like to grant Clone access to the anonymous user,
but that's personal preference.)

Once you are done, kill the fossil server (with Ctrl-C or equivalent)
and close the browser window.

<blockquote>
Tip: it is not strictly required to configure a repository
................................................................................
That creates a file called <tt>_FOSSIL_</tt> in the current
directory, and this file contains all kinds of fossil-related
information about your local repository. You can ignore it
for all purposes, but be sure not to accidentally remove it
or otherwise damage it - it belongs to fossil, not you.

The next thing we need to do is add files to our repository.  As it
happens, we have a few C source files laying around, which we'll
simply copy into our working directory.

<verbatim>
stephan@ludo:~/fossil/demo$ cp ../csnip/*.{c,h} .
stephan@ludo:~/fossil/demo$ ls
clob.c  clob.h  clobz.c  _FOSSIL_  mkdep.c  test-clob.c
tokenize_path.c tokenize_path.h  vappendf.c  vappendf.h
</verbatim>

Fossil doesn't know about those files yet. Telling fossil about
a new file is a two-step process. First we <em>add</em> the file
to the repo, then we <em>commit</em> the file. This is a familiar
process for anyone who's worked with SCM systems before:

<verbatim>
stephan@ludo:~/fossil/demo$ fossil add *.{c,h}
stephan@ludo:~/fossil/demo$ fossil commit -m "egg"
New_Version: d1296b4a08b9f8b943bb6c73698e51eed23f8f91
</verbatim>







|







 







|











|







30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
..
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
</verbatim>

The <tt>ui</tt> command starts up a server (with an optional <tt>-port
NUMBER</tt> argument) and launches a web browser pointing at the
fossil server. From there it takes just a few moments to configure the
repo. Most importantly, go to the Admin menu, then the Users link, and
set your account name and password, and grant your account all access
privileges. (I also like to grant Clone access to the anonymous user,
but that's personal preference.)

Once you are done, kill the fossil server (with Ctrl-C or equivalent)
and close the browser window.

<blockquote>
Tip: it is not strictly required to configure a repository
................................................................................
That creates a file called <tt>_FOSSIL_</tt> in the current
directory, and this file contains all kinds of fossil-related
information about your local repository. You can ignore it
for all purposes, but be sure not to accidentally remove it
or otherwise damage it - it belongs to fossil, not you.

The next thing we need to do is add files to our repository.  As it
happens, we have a few C source files lying around, which we'll
simply copy into our working directory.

<verbatim>
stephan@ludo:~/fossil/demo$ cp ../csnip/*.{c,h} .
stephan@ludo:~/fossil/demo$ ls
clob.c  clob.h  clobz.c  _FOSSIL_  mkdep.c  test-clob.c
tokenize_path.c tokenize_path.h  vappendf.c  vappendf.h
</verbatim>

Fossil doesn't know about those files yet. Telling fossil about
a new file is a two-step process. First we <em>add</em> the file
to the repository, then we <em>commit</em> the file. This is a familiar
process for anyone who's worked with SCM systems before:

<verbatim>
stephan@ludo:~/fossil/demo$ fossil add *.{c,h}
stephan@ludo:~/fossil/demo$ fossil commit -m "egg"
New_Version: d1296b4a08b9f8b943bb6c73698e51eed23f8f91
</verbatim>

Changes to www/qandc.wiki.

36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
..
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
  <ol>
  <li> Fossil is distributed.  You can view and/or edit tickets, wiki, and
       code while off network, then sync your changes later.  With Trac, you
       can only view and edit tickets and wiki while you are connected to
       the server. </li>
  <li> Fossil is lightweight and fully self-contained.  It is very easy 
       to setup on a low-resource machine. Fossil does not require an
       administator.</li>
  <li> Fossil integrates code versioning into the same repository with
       wiki and tickets.  There is nothing extra to add or install.
       Fossil is an all-in-one turnkey solution. </li>
  </ol>
</blockquote>

<b>Love the concept here. Anyone using this for real work yet?</b>
................................................................................
Linksys Router's administration screen.</p>

<blockquote>
<p>I take a pragmatic approach to software: form follows function.
To me, it is more important to have a reliable, fast, efficient,
enduring, and simple DVCS than one that looks pretty.</p>

<p>On the other hand, if you have patches that improve the apparance
of Fossil without seriously compromising its reliablity, performance,
and/or maintainability, I will be happy to accept them.  Fossil is
self-hosting.  Send email to request a password that will let
you push to the main fossil repository.</p>
</blockquote>

<b>It would be useful to have a separate application that
keeps the bug-tracking database in a versioned file. That file can







|







 







|
|







36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
..
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
  <ol>
  <li> Fossil is distributed.  You can view and/or edit tickets, wiki, and
       code while off network, then sync your changes later.  With Trac, you
       can only view and edit tickets and wiki while you are connected to
       the server. </li>
  <li> Fossil is lightweight and fully self-contained.  It is very easy 
       to setup on a low-resource machine. Fossil does not require an
       administrator.</li>
  <li> Fossil integrates code versioning into the same repository with
       wiki and tickets.  There is nothing extra to add or install.
       Fossil is an all-in-one turnkey solution. </li>
  </ol>
</blockquote>

<b>Love the concept here. Anyone using this for real work yet?</b>
................................................................................
Linksys Router's administration screen.</p>

<blockquote>
<p>I take a pragmatic approach to software: form follows function.
To me, it is more important to have a reliable, fast, efficient,
enduring, and simple DVCS than one that looks pretty.</p>

<p>On the other hand, if you have patches that improve the appearance
of Fossil without seriously compromising its reliability, performance,
and/or maintainability, I will be happy to accept them.  Fossil is
self-hosting.  Send email to request a password that will let
you push to the main fossil repository.</p>
</blockquote>

<b>It would be useful to have a separate application that
keeps the bug-tracking database in a versioned file. That file can

Changes to www/quickstart.wiki.

37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
    restrictions.  As an example, you can clone the fossil repository
    this way:</p>
    
    <blockquote>
    <b>fossil clone http://www.fossil-scm.org/ myclone.fossil</b>
    </blockquote>

    <p>The new local copy of the respository is stored in a single file,
    which in the example above is named "myclone.fossil".
    You can name your repositories anything you want.  The ".fossil" suffix
    is not required.</p>

    <p>Note: If you are behind a restrictive firewall, you might need
    to <a href="#proxy">specify an HTTP proxy</a> to use.</p>
    







|







37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
    restrictions.  As an example, you can clone the fossil repository
    this way:</p>
    
    <blockquote>
    <b>fossil clone http://www.fossil-scm.org/ myclone.fossil</b>
    </blockquote>

    <p>The new local copy of the repository is stored in a single file,
    which in the example above is named "myclone.fossil".
    You can name your repositories anything you want.  The ".fossil" suffix
    is not required.</p>

    <p>Note: If you are behind a restrictive firewall, you might need
    to <a href="#proxy">specify an HTTP proxy</a> to use.</p>
    

Changes to www/selfcheck.wiki.

28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
..
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
A check-in operation in fossil makes many changes to the repository
database.  But all these changes happen within a single transaction.
If something goes wrong in the middle of the commit, then the transaction
is rolled back and the database is unchanged.

<h2>Verification Of Delta Encodings Prior To Transaction Commit</h2>

The content files that comprise the global state of a fossil respository
are stored in the repository as a tree.  The leaves of the tree are
stored as zlib-compressed BLOBs.  Interior nodes are deltas from their
decendants.  A lot of encoding is going on.  There is
zlib-compression which is relatively well-tested but still might
cause corruption if used improperly.  And there is the relatively
new delta-encoding mechanism designed expressly for fossil.  We want
to make sure that bugs in these encoding mechanisms do not lead to
loss of data.

To increase our confidence that everything in the repository is
................................................................................
Hence bugs in fossil are unlikely to corrupt the repository in
a way that prevents us from extracting historical versions of 
files.

<h2>Checksum Over All Files In A Check-in</h2>

Manifest artifacts that define a check-in have two fields (the
R-card and Z-card) that record MD5 hashs of the manifest itself
and of all other files in the manifest.  Prior to any check-in
commit, these checksums are verified to ensure that the check-in
checked in agrees exactly with what is on disk.  Similarly,
the repository checksum is verified after a checkout to make
sure that the entire repository was checked out correctly.
Note that these added checks use a different hash (MD5 instead
of SHA1) in order to avoid common-mode failures in the hash







|


|







 







|







28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
..
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
A check-in operation in fossil makes many changes to the repository
database.  But all these changes happen within a single transaction.
If something goes wrong in the middle of the commit, then the transaction
is rolled back and the database is unchanged.

<h2>Verification Of Delta Encodings Prior To Transaction Commit</h2>

The content files that comprise the global state of a fossil repository
are stored in the repository as a tree.  The leaves of the tree are
stored as zlib-compressed BLOBs.  Interior nodes are deltas from their
descendants.  A lot of encoding is going on.  There is
zlib-compression which is relatively well-tested but still might
cause corruption if used improperly.  And there is the relatively
new delta-encoding mechanism designed expressly for fossil.  We want
to make sure that bugs in these encoding mechanisms do not lead to
loss of data.

To increase our confidence that everything in the repository is
................................................................................
Hence bugs in fossil are unlikely to corrupt the repository in
a way that prevents us from extracting historical versions of 
files.

<h2>Checksum Over All Files In A Check-in</h2>

Manifest artifacts that define a check-in have two fields (the
R-card and Z-card) that record MD5 hashes of the manifest itself
and of all other files in the manifest.  Prior to any check-in
commit, these checksums are verified to ensure that the check-in
checked in agrees exactly with what is on disk.  Similarly,
the repository checksum is verified after a checkout to make
sure that the entire repository was checked out correctly.
Note that these added checks use a different hash (MD5 instead
of SHA1) in order to avoid common-mode failures in the hash

Changes to www/shunning.wiki.

36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
..
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
<h3>Shunning lists are local state</h3>

The shunning list is part of the local state of a Fossil repository.
In other words, shunning does not propagate using the normal "sync"
mechanism.  An artifact can be
shunned from one repository but be allowed to exist in another.  The fact that
the shunning list does not propagate is a security feature.  If the
shunning list propagated then a malecious user (or
a bug in the fossil code) might introduce a shun record that would
propagate through all respositories in a network and permanently 
destroy vital information.  By refusing to propagate the shunning list,
Fossil insures that no remote user will ever be able to remove 
information from your personal repositories without your permission.

The shunning list does not propagate by the normal "sync" mechanism,
but it is still possible to copy shuns from one repository to another
using the "configuration" command:
................................................................................
    <b>fossil configuration push shun</b> <i>remote-url</i>

The two command above will pull or push shunning lists from or to
the <i>remote-url</i> indicated and merge the lists on the receiving
end.  "Admin" privilege on the remote server is required in order to
push a shun list.  

Note that the shunning list remains in the respository even after the
shunned artifact has been removed.  This is to prevent the artifact
from being reintroduced into the repository the next time it syncs with
another repository that has not shunned the artifact.

<h3>Managing the shunning list</h3>

The complete shunning list for a repository can be viewed by a user
with "admin" privilege on the "/shunned" URL of the web interface to Fossil.  
That URL is accessible under the "Admin" button on the default menu
bar.  Items can be added to or removed from the shunning list.  "Sync"
operations are inhibited as soon as the artifact is added to the
shunning list, but the content of the artifact is not actually removed
from the responstory until the next time the repository is rebuilt.

When viewing individual artifacts with the web interface, "admin"
users will usually see a "Shun" option in the submenu that will take
them directly to the shunning page and enable that artifact to be
shunned with a single additional mouse click.







|

|







 







|












|





36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
..
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
<h3>Shunning lists are local state</h3>

The shunning list is part of the local state of a Fossil repository.
In other words, shunning does not propagate using the normal "sync"
mechanism.  An artifact can be
shunned from one repository but be allowed to exist in another.  The fact that
the shunning list does not propagate is a security feature.  If the
shunning list propagated then a malicious user (or
a bug in the fossil code) might introduce a shun record that would
propagate through all repositories in a network and permanently 
destroy vital information.  By refusing to propagate the shunning list,
Fossil insures that no remote user will ever be able to remove 
information from your personal repositories without your permission.

The shunning list does not propagate by the normal "sync" mechanism,
but it is still possible to copy shuns from one repository to another
using the "configuration" command:
................................................................................
    <b>fossil configuration push shun</b> <i>remote-url</i>

The two command above will pull or push shunning lists from or to
the <i>remote-url</i> indicated and merge the lists on the receiving
end.  "Admin" privilege on the remote server is required in order to
push a shun list.  

Note that the shunning list remains in the repository even after the
shunned artifact has been removed.  This is to prevent the artifact
from being reintroduced into the repository the next time it syncs with
another repository that has not shunned the artifact.

<h3>Managing the shunning list</h3>

The complete shunning list for a repository can be viewed by a user
with "admin" privilege on the "/shunned" URL of the web interface to Fossil.  
That URL is accessible under the "Admin" button on the default menu
bar.  Items can be added to or removed from the shunning list.  "Sync"
operations are inhibited as soon as the artifact is added to the
shunning list, but the content of the artifact is not actually removed
from the repository until the next time the repository is rebuilt.

When viewing individual artifacts with the web interface, "admin"
users will usually see a "Shun" option in the submenu that will take
them directly to the shunning page and enable that artifact to be
shunned with a single additional mouse click.

Changes to www/sync.wiki.

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
SHA1 hashes for this many artifacts can be large.  So optimizations are
employed that usually reduce the number of SHA1 hashes that need to be
shared to a few hundred.</p>

<p>Each repository also has local state.  The local state determines
the web-page formatting preferences, authorized users, ticket formats,
and similar information that varies from one repository to another.
The local state is not transfered by the <b>push</b>, <b>pull</b>,
and <b>sync</b> command, though some local state is transfered during
a <b>clone</b> in order to initialize the local state of the new
repository.  The <b>configuration push</b> and <b>configuration pull</b>
commands can be used to send or receive local state.</p>


<h2>2.0 Transport</h2>








|
|







24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
SHA1 hashes for this many artifacts can be large.  So optimizations are
employed that usually reduce the number of SHA1 hashes that need to be
shared to a few hundred.</p>

<p>Each repository also has local state.  The local state determines
the web-page formatting preferences, authorized users, ticket formats,
and similar information that varies from one repository to another.
The local state is not transferred by the <b>push</b>, <b>pull</b>,
and <b>sync</b> command, though some local state is transferred during
a <b>clone</b> in order to initialize the local state of the new
repository.  The <b>configuration push</b> and <b>configuration pull</b>
commands can be used to send or receive local state.</p>


<h2>2.0 Transport</h2>

Changes to www/wikitheory.wiki.

6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
..
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
   *  Description and comments in [./bugtheory.wiki | bug reports].
   *  Check-in comments.
   *  [./embeddeddoc.wiki | Embedded documentation] files whose
      name ends in "wiki".

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 bulletted lists, and hyperlinking for
simple documents together with a safe subset of HTML for more complex
formatting tasks.

Some commentators feel that the use of HTML is a mistake and that
fossil should use the markup language of the
<i>fill-in-your-favorite</i> wiki engine instead.  That approach
was considered but was rejected for the following reasons:
................................................................................
of type [./fileformat.wiki#wikichng | "Wiki Page"].

<h2>Embedded Documentation</h2>

Files in the source tree that use the ".wiki" suffix can be accessed
and displayed using special URLs to the fossil server.  This allows
project documentation to be stored in the source tree and accessed 
online.  (Details are descripted [./embeddeddoc.wiki | separately].)

Some project prefer to store their documentation in wiki.  There is nothing
wrong with that.  But other projects prefer to keep documentation as part
of the source tree, so that it is versioned along with the source tree and
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 wiki markup language.  Some projects may choose to
use both forms of documentation at the same time.  Because the same
format is used, it is trival to move 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
..
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
   *  Description and comments in [./bugtheory.wiki | bug reports].
   *  Check-in comments.
   *  [./embeddeddoc.wiki | Embedded documentation] files whose
      name ends in "wiki".

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.

Some commentators feel that the use of HTML is a mistake and that
fossil should use the markup language of the
<i>fill-in-your-favorite</i> wiki engine instead.  That approach
was considered but was rejected for the following reasons:
................................................................................
of type [./fileformat.wiki#wikichng | "Wiki Page"].

<h2>Embedded Documentation</h2>

Files in the source tree that use the ".wiki" suffix can be accessed
and displayed using special URLs to the fossil server.  This allows
project documentation to be stored in the source tree and accessed 
online.  (Details are described [./embeddeddoc.wiki | separately].)

Some project prefer to store their documentation in wiki.  There is nothing
wrong with that.  But other projects prefer to keep documentation as part
of the source tree, so that it is versioned along with the source tree and
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 wiki markup language.  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 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.