Fossil

#!/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>}

<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>

[http://www.hwaci.com/cgi-bin/fossil | two separate servers].
You can download the [/timeline?y=ci | latest sources] and
[./build.wiki | compile it yourself].
Or you can grab
[http://www.fossil-scm.org/download.html | pre-compiled binaries].


<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>,
      <a href="http://www.selenic.com/mercurial/wiki/index.cgi">mercurial</a>,
      and <a href="http://www.bitkeeper.com/">bitkeeper</a>

     not yet born.
  *  Automatic [./selfcheck.wiki | self-check]
     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].

<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.
  *  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]
     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.

<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
     efficiently store changes between file revisions.
  *  The [./delta_encoder_algorithm.wiki | encoder algorithm] used to
     efficiently generate deltas.
  *  The [./sync.wiki | synchronization protocol].

<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.

<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>
  <p>I wrote fossil because none of the
  other available DVCSes met my needs.  If the other DVCSes do

<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>