Check-in [627de3bf16]
Not logged in
HomeFilesLeavesTimelineBranchesTagsTicketsWikiLogin
Overview

SHA1 Hash:627de3bf16b0552bbed7b62496d2f82ac4f14b7d
Date: 2009-01-25 21:16:55
User: drh
Comment:Documentation updates: Added FAQ and testimonials.
Timelines: ancestors | descendants | both | trunk
Other Links: files | ZIP archive | manifest

Tags And Properties
Changes
[hide diffs]

Added www/faq.tcl version [b788977002]

@@ -1,1 +1,101 @@
+#!/usr/bin/tclsh
+#
+# Run this to generate the FAQ
+#
+set cnt 1
+proc faq {question answer} {
+  set ::faq($::cnt) [list [string trim $question] [string trim $answer]]
+  incr ::cnt
+}
+
+faq {
+  What GUIs are available for fossil?
+} {
+  The fossil executable comes with a web-based GUI built in.  Just run:
+
+  <blockquote>
+  <b>fossil ui</b> <i>REPOSITORY-FILENAME</i>
+  </blockquote>
+
+  And your default web browser should pop up and automatically point to
+  the fossil interface.  (Hint:  You can omit the <i>REPOSITORY-FILENAME</i>
+  if you are within an open check-out.)
+}
+
+faq {
+  What is the difference between a "branch" and a "fork"?
+} {
+  This is a big question - too big to answer in a FAQ.  Please
+  read the <a href="branching.wiki">Branching, Forking, Merging,
+  and Tagging</a> document.
+}
+
+
+faq {
+  How do I create a new branch in fossil?
+} {
+  There are lots of ways:
+
+  When you are checking in a new change using the <b>commit</b>
+  command, you can add the option  "--branch <i>BRANCH-NAME</i>" to
+  make the change be the founding check-in for a new branch.  You can
+  also add the "--bgcolor <i>COLOR</i>" option to give the branch a
+  specific background color on timelines.
+
+  If you want to create a new branch whose founding check-in is the
+  same as an existing check-in, use this command:
+
+  <blockquote>
+  <b>fossil branch new</b> <i>BRANCH-NAME BASIS</i>
+  </blockquote>
+
+  The <i>BRANCH-NAME</i> argument is the name of the new branch and the
+  <i>BASIS</i> argument is the name of the check-in that the branch splits
+  off from.
+
+  If you already have a fork in your check-in tree and you want to convert
+  that fork to a branch, you can do this from the web interface.
+  First locate the check-in that you want to be
+  the founding check-in of your branch on the timeline and click on its
+  link so that you are on the <b>ci</b> page.  Then find the "<b>edit</b>"
+  link (near the "Commands:" label) and click on that.  On the
+  "Edit Check-in" page, check the box beside "Branching:" and fill in
+  the name of your new branch to the right and press the "Apply Changes"
+  button.
+}
+
+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.
+
+  Of course, as long as you never push, you can make as many private
+  changes as you want.
+}
+
+
+
+#############################################################################
+# Code to actually generate the FAQ
+#
+puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n"
+puts "<p>Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n"
+
+puts {<ol>}
+for {set i 1} {$i<$cnt} {incr i} {
+  puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>"
+}
+puts {</ol>}
+puts {<hr>}
 
+for {set i 1} {$i<$cnt} {incr i} {
+  puts "<a name=\"q$i\"></a>"
+  puts "<p><b>($i) [lindex $faq($i) 0]</b></p>\n"
+  set body [lindex $faq($i) 1]
+  regsub -all "\n *" [string trim $body] "\n" body
+  puts "<blockquote>$body</blockquote></li>\n"
+}
+puts {</ol>}

Added www/faq.wiki version [4f2f594a41]

@@ -1,1 +1,76 @@
+<h1 align="center">Frequently Asked Questions</h1>
+
+<p>Note: See also <a href="qandc.wiki">Questions and Criticisms</a>.
+
+<ol>
+<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>
+</ol>
+<hr>
+<a name="q1"></a>
+<p><b>(1) What GUIs are available for fossil?</b></p>
+
+<blockquote>The fossil executable comes with a web-based GUI built in.  Just run:
+
+<blockquote>
+<b>fossil ui</b> <i>REPOSITORY-FILENAME</i>
+</blockquote>
+
+And your default web browser should pop up and automatically point to
+the fossil interface.  (Hint:  You can omit the <i>REPOSITORY-FILENAME</i>
+if you are within an open check-out.)</blockquote></li>
+
+<a name="q2"></a>
+<p><b>(2) What is the difference between a "branch" and a "fork"?</b></p>
+
+<blockquote>This is a big question - too big to answer in a FAQ.  Please
+read the <a href="branching.wiki">Branching, Forking, Merging,
+and Tagging</a> document.</blockquote></li>
+
+<a name="q3"></a>
+<p><b>(3) How do I create a new branch in fossil?</b></p>
+
+<blockquote>There are lots of ways:
+
+When you are checking in a new change using the <b>commit</b>
+command, you can add the option  "--branch <i>BRANCH-NAME</i>" to
+make the change be the founding check-in for a new branch.  You can
+also add the "--bgcolor <i>COLOR</i>" option to give the branch a
+specific background color on timelines.
+
+If you want to create a new branch whose founding check-in is the
+same as an existing check-in, use this command:
+
+<blockquote>
+<b>fossil branch new</b> <i>BRANCH-NAME BASIS</i>
+</blockquote>
+
+The <i>BRANCH-NAME</i> argument is the name of the new branch and the
+<i>BASIS</i> argument is the name of the check-in that the branch splits
+off from.
+
+If you already have a fork in your check-in tree and you want to convert
+that fork to a branch, you can do this from the web interface.
+First locate the check-in that you want to be
+the founding check-in of your branch on the timeline and click on its
+link so that you are on the <b>ci</b> page.  Then find the "<b>edit</b>"
+link (near the "Commands:" label) and click on that.  On the
+"Edit Check-in" page, check the box beside "Branching:" and fill in
+the name of your new branch to the right and press the "Apply Changes"
+button.</blockquote></li>
+
+<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>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.
+
+Of course, as long as you never push, you can make as many private
+changes as you want.</blockquote></li>
 
+</ol>

Modified www/index.wiki from [b5ddee628e] to [2046c07523]. 

@@ -13,11 +13,11 @@
 [./build.wiki | compile it yourself].
 Or you can grab
 [http://www.fossil-scm.org/download.html | pre-compiled binaries].
 
 
-Feature Summary:
+<b>Feature Summary:</b>
 
   *  Flexible workflow:<ul>
     <li>Disconnected, distributed development like
       <a href="http://kerneltrap.org/node/4982">git</a>,
       <a href="http://www.monotone.ca/">monotone</a>,
@@ -51,12 +51,13 @@
      on repository changes makes it exceedingly
      unlikely that data will ever be lost because of a software bug.
   *  Ridiculously easy to [./build.wiki | install] and
      [./quickstart.wiki | operate].
 
-User Links:
+<b>User Links:</b>
 
+  *  [./faq.wiki | FAQ]
   *  The [./concepts.wiki | concepts] behind fossil
   *  [./build.wiki | Building And Installing]
   *  [./quickstart.wiki | Quick Start] guide to using fossil
   *  Fossil supports [./embeddeddoc.wiki | embedded documentation]
      that is versioned along with project source code.
@@ -67,14 +68,15 @@
   *  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]
      available for discussing fossil issues.
   *  [./qandc.wiki | Questions &amp; Criticisms] directed at fossil.
+  *  [./reviews.wiki | Testimonials] from fossil users.
   *  Some (unfinished but expanding) extended
       [./reference.wiki | reference documentation] for the fossil command line.
 
-Developer Links:
+<b>Developer Links:</b>
 
   *  [./pop.wiki | Principles Of Operation]
   *  The [./fileformat.wiki | file format] used by every content
      file stored in the repository.
   *  The [./delta_format.wiki | format of deltas] used to
@@ -81,14 +83,14 @@
      efficiently store changes between file revisions.
   *  The [./delta_encoder_algorithm.wiki | encoder algorithm] used to
      efficiently generate deltas.
   *  The [./sync.wiki | synchronization protocol].
 
-Competing Projects:
+<b>Competing Projects:</b>
 
   *  [http://www.ditrack.org/ | DITrace] - A Distributed Issue Tracker
   *  [http://www.distract.wellquite.org/ | DisTract]
      - Another distributed issue tracker based on
      [http://www.monotone.ca/ | monotone].
   *  [http://www.monotone.ca/ | Monotone] - distributed
      SCM in a single-file executable with a single-file SQLite
      database repository.

Modified www/qandc.wiki from [61ff0d8364] to [36405b750a]. 

@@ -1,10 +1,12 @@
 <nowiki>
 <h1 align="center">Questions And Criticisms</h1>
 
 <p>This page is a collection of real questions and criticisms that have been
 raised against fossil together with responses from the program's author.</p>
+
+<p>Note: See also the <a href="faq.wiki">Frequently Asked Questions</a>.</p>
 
 <b>Fossil sounds like a lot of reinvention of the wheel.
 Why create your own DVCS when you could have reused mercurial?</b>
 
 <blockquote>

Added www/reviews.wiki version [50033359c6]

@@ -1,1 +1,115 @@
+<h2 align="center">What People Are Saying About Fossil</h2>
+
+<b>Daniel writes on 2009-01-06:</b>
+
+<blockquote>
+The reasons I use fossil are that it's the only version control I
+have found that I can get working through the VERY annoying MS
+firewalls at work.. (albeit through an ntlm proxy) and I just love
+single .exe applications!
+</blockquote>
+
+<b>Stephen Beal writes on 2009-01-11:</b>
+
+<blockquote>
+Sometime in late 2007 I came across a link to fossil on
+<a href="http://www.sqlite.org/">sqlite.org</a>. It
+was a good thing I bookmarked it, because I was never able to find the
+link again (it might have been in a bug report or something). The
+reasons I first took a close look at it were (A) it stemmed from the
+sqlite project, which I've held in high regards for years (e.g. I
+wrote JavaScript bindings for it:
+<a href="http://spiderape.sourceforge.net/plugins/sqlite/">
+http://spiderape.sourceforge.net/plugins/sqlite/</a>), and (B) it could
+run as a CGI. That second point might seem a bit archaic, but in
+practice CGI is the only way most hosted sites can set up a shared
+source repository with multiple user IDs. (i'm not about to give out
+my only account password or SSH key for my hosted sites, no matter how
+much I trust the other developers, and none of my hosters allow me to
+run standalone servers or add Apache modules.)
+
+So I tried it out. The thing which bugged me most about it was having
+to type "commit" or "com" instead of "ci" for checking in (as is
+custom in all other systems I've used), despite the fact that fossil
+uses "ci" as a filter in things like the timeline view. Looking back
+now, I have used fossil for about about 95% of my work in the past
+year (http://blog.s11n.net/?p=71), in over 15 source trees, and I now
+get tripped up when I have to use svn or cvs.
+
+So, having got over typing "fossil com -m ...", here's why I love it so much...
+
+Point #1: CGI
+
+Again, this sounds archaic, but fossil has allowed me to share source
+trees which I cannot justifiably host in other projects I work on
+(they don't belong to those projects), which I cannot host in google
+code (because google code doesn't allow/recognize Public Domain as a
+license, and I refuse to relicense just to accommodate them), and for
+which SourceForge is overkill (and way too slow). With fossil I can
+create a new repo, have it installed on my hoster
+(http://fossil.wanderinghorse.net), and be commiting code to it within
+5 minutes.
+
+Point #2: Wiki
+
+I hate wikis. I really do. Always have. They all have a different
+syntax and the content tends to get really disorganized really
+quickly. Their nature makes it difficult to reorganize them without
+replacing old pages with lots of "has been moved to
+<nowiki>[TheNewPage]</nowiki>"
+links. I'm one of those "code for tomorrow" coders (i.e., code such
+that it'll be easy to reorganize/refactor later). I like to document
+the same way, and wikis make that problematic. Then again, no
+documentation system is really good in that regard.
+
+That said, fossil has made me love having a centralized, common
+documentation platform. Whereas I used to document everything in the
+API docs (header files) and often include an ODT file for a library
+manual, fossil has become my preferred platform for non-API
+documentation because it's just so easy to do. No matter where I am, I
+can log in and write (I write a lot). The added ability to export my
+wiki pages, edit them in xemacs, and re-import them just makes it
+nicer, as I can tweak as much as I want without ending up with 10
+"updated wiki page SoAndSo" messages in the commit log.
+
+
+Point #3: running a server locally
+
+Fossil runs not only as a CGI, but as a server. I don't WANT to host
+my own server (and don't have the rights to on my hosters). I hate
+server-side maintenance (a hate born from years of administering
+systems). But the server has other uses. When working on the wiki, bug
+reports, etc., the local server is *the* way to do it. It's blazingly
+fast and much more productive. When you're done, just run "fossil
+push" and everything's synced.
+
+
+Point #4: the single-file repository
+
+Having all controlled content inside a single container file has been
+a godsend when it comes to backups and copying/moving a repository.
+There are no access or file ownership issues, which are often
+problematic with other server-side systems (at least on the initial
+install). For about 5 years I administered a CVS repo for a company
+for, and every time someone added a directory to the (huge and
+dynamic) source tree I had to log in and "chmod 4775" the directory
+before others could commit to it. Fossil's model inherently eliminates
+that type of problem, and I'm a *huge* fan of solutions which
+inherently (that is, due to their very nature) avoid certain
+foreseeable problems. The single-file repository model's flexibility
+would seem to become more problematic for huge repos (a few hundred
+MB+) with many users with differing levels of access (e.g. OpenOffice,
+Firefox, or the Linux Kernel), but 99.9% of projects never reach
+anywhere near that size or complexity.
+
+
+In summary:
 
+I remember my first reaction to fossil being, "this will be an
+excellent solution for small projects [like the dozens we've all got
+sitting on our hard drives but which don't justify the hassle of
+version control]." A year of daily use in over 15 source trees has
+confirmed that, and I continue to heartily recommend fossil to other
+developers I know who also have their own collection of "unhosted" pet
+projects.
+</blockquote>

Fossil version [c0211010a1] 2009-12-13 01:31:36