SHA1 Hash:	d6b8b5ba7370b3946b29d1ec0cc7ed1780e0893e
Date:	2009-08-26 19:50:21
User:	drh
Comment:	More FAQ updates. Add the document on "shunning".
Timelines:	ancestors | descendants | both | trunk
Other Links:	files | ZIP archive | manifest

• branch=trunk inherited from [a28c83647d]
• sym-trunk inherited from [a28c83647d]

Modified www/faq.tcl from [b788977002] to [8ff9488a6c].

@@ -66,16 +66,34 @@
 
 faq {
   How do I create a private branch that won't get pushed back to the
   main repository.
 } {
-  You cannot.  All branches in fossil are public in the sense that
-  are all pushed and pulled together.  There is no way to tell fossil
-  to only push or pull a subset of branches.
+  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
+  you have everything in your private branch the way you want it, you can
+  then merge your private branch back into the trunk and push.  Only the
+  final merge operation will appear in other repositories.  It will seem
+  as if all the changes that occurred on your private branch occurred in
+  a single check-in.
+  Of course, you can also keep your branch private forever simply
+  by not merging the changes in the private branch back into the trunk.
+}
 
-  Of course, as long as you never push, you can make as many private
-  changes as you want.
+faq {
+  How can I delete inappropriate content from my fossil repository?
+} {
+  See the article on [./shunning.wiki | "shunning"] for details.
 }
 
 
 
 #############################################################################

Modified www/faq.wiki from [7adf59141f] to [05996cbdab].

@@ -6,10 +6,11 @@
 <li><a href="#q1">What GUIs are available for fossil?</a></li>
 <li><a href="#q2">What is the difference between a "branch" and a "fork"?</a></li>
 <li><a href="#q3">How do I create a new branch in fossil?</a></li>
 <li><a href="#q4">How do I create a private branch that won't get pushed back to the
   main repository.</a></li>
+<li><a href="#q5">How can I delete inappropriate content from my fossil repository?</a></li>
 </ol>
 <hr>
 <a name="q1"></a>
 <p><b>(1) What GUIs are available for fossil?</b></p>
 
@@ -77,13 +78,17 @@
 
 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
 you have everything in your private branch the way you want it, you can
 then merge your private branch back into the trunk and push.  Only the
-final merge operation will appear in other repositories.  It will appear
+final merge operation will appear in other repositories.  It will seem
 as if all the changes that occurred on your private branch occurred in
 a single check-in.
-Of course, you can also keep your private branch private forever simply
-by not merging the changes in the private branch back into the trunk.
-</blockquote></li>
+Of course, you can also keep your branch private forever simply
+by not merging the changes in the private branch back into the trunk.</blockquote></li>
+
+<a name="q5"></a>
+<p><b>(5) How can I delete inappropriate content from my fossil repository?</b></p>
+
+<blockquote>See the article on [./shunning.wiki | "shunning"] for details.</blockquote></li>
 
 </ol>

Modified www/index.wiki from [ee31c52eb6] to [72859af219].

@@ -78,10 +78,11 @@
   *  There is a
     [http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users | mailing list]
      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.
   *  Some (unfinished but expanding) extended
       [./reference.wiki | reference documentation] for the fossil command line.
 
 <h3>Developer Links:</h3>
 

Added www/shunning.wiki version [7b6d5703dc]

@@ -1,1 +1,80 @@
+<title>Deleting Content From Fossil</title>
+<h1 align="center">Deleting Content From Fossil</h1>
+
+Fossil is designed to keep all historical content forever.  Users
+of Fossil are discouraged from "deleting" content simply because it
+has become obsolete.  Old content is part of the historical record
+(part of the "fossil record") and should be maintained indefinitely.
+Such is the design intent of Fossil.
+
+Nevertheless, there may occasionally arise legitimate reasons for
+deleting content.  Such reasons might include:
+
+  *  Spammers have inserted inappropriate content into a wiki page
+     or ticket that needs to be removed.
+
+  *  A file that contains trade secrets or that is under copyright
+     may have been accidentally committed and needs to be backed
+     out.
+
+  *  A malformed control artifact may have been inserted and is
+     disrupting the operation of Fossil.
+
+<h2>Shunning</h2>
+
+Fossil provides a mechanism called "shunning" for removing content from
+a repository.
+
+Every Fossil repository maintains a list of the SHA1 hash names of
+"shunned" artifacts.
+Fossil will refuse to push or pull any shunned artifact.
+Furthermore, all shunned artifacts (but not the shunning list
+itself) are removed from the
+repository whenever the repository is reconstructed using the
+"rebuild" command.
+
+<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 pull shun</b> <i>remote-url</i><br>
+    <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.