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 [./webui.wiki | web-based GUI] built in.
  Just run:

  <blockquote>
  <b>fossil [/help/ui|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?
} {
  There are lots of ways:

  When you are checking in a new change using the <b>[/help/commit|commit]</b>
  command, you can add the option  "--branch <i>BRANCH-NAME</i>" to
  make the new check-in be the first 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 initial content is the
  same as an existing check-in, use this command:

  <blockquote>
  <b>fossil [/help/branch|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 initial 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 tag a check-in?
} {
  There are several ways:

  When you are checking in a new change using the <b>[/help/commit|commit]</b>
  command, you can add a tag to that check-in using the
  "--tag <i>TAGNAME</i>" command-line option.

  If you want add a tag to an existing check-in, you can use the
  <b>[/help/tag|tag]</b> command.  For example:

  <blockquote>
  <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i>
  </blockquote>

  The CHECK-IN in the previous line can be any
  [./checkin_names.wiki | valid check-in name format].

  You can also add (and remove) tags from a check-in using the
  [./webui.wiki | web interface].  First locate the check-in that you 
  what to tag on the tmline, then click on the link to go the detailed
  information page for that check-in.  Then find the "<b>edit</b>"
  link (near the "Commands:" label) and click on that.  There are
  controls on the edit page that allow new tags to be added and existing
  tags to be removed.
}  

faq {
  How do I create a private branch that won't get pushed back to the
  main repository.
} {
  Use the <b>--private</b> command-line option on the 
  <b>commit</b> command.  The result will be a check-in which exists on

}

faq {
  How do I make a clone of the fossil self-hosting repository?
} {
  Any of the following commands should work:
  <blockquote><pre>
  fossil [/help/clone|clone]  http://www.fossil-scm.org/  fossil.fossil<br>
  fossil [/help/clone|clone]  http://www2.fossil-scm.org/  fossil.fossil<br>
  fossil [/help/clone|clone]  http://www3.fossli-scm.org/site.cgi  fossil.fossil
  </pre></blockquote>
  Once you have the repository cloned, you can open a local check-out
  as follows:
  <blockquote><pre>
  mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil
  </pre></blockquote>
  Thereafter you should be able to keep your local check-out up to date
  with the latest code in the public repository by typing:
  <blockquote><pre>
  fossil [/help/update|update]
  </pre></blockquote>
}

faq {
  How do I import or export content from and to other version control systems?
} {
  Please see [./inout.wiki | Import And Export]
}



#############################################################################
# Code to actually generate the FAQ
#
puts "<title>Fossil FAQ</title>"
puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n"
puts "<p>Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n"

<title>Fossil FAQ</title>
<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?</a></li>
<li><a href="#q4">How do I tag a check-in?</a></li>
<li><a href="#q5">How do I create a private branch that won't get pushed back to the
  main repository.</a></li>
<li><a href="#q6">How can I delete inappropriate content from my fossil repository?</a></li>
<li><a href="#q7">How do I make a clone of the fossil self-hosting repository?</a></li>
<li><a href="#q8">How do I import or export content from and to other version control systems?</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 [./webui.wiki | web-based GUI] built in.
Just run:

<blockquote>
<b>fossil [/help/ui|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?</b></p>

<blockquote>There are lots of ways:

When you are checking in a new change using the <b>[/help/commit|commit]</b>
command, you can add the option  "--branch <i>BRANCH-NAME</i>" to
make the new check-in be the first 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 initial content is the
same as an existing check-in, use this command:

<blockquote>
<b>fossil [/help/branch|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 initial 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 tag a check-in?</b></p>

<blockquote>There are several ways:

When you are checking in a new change using the <b>[/help/commit|commit]</b>
command, you can add a tag to that check-in using the
"--tag <i>TAGNAME</i>" command-line option.

If you want add a tag to an existing check-in, you can use the
<b>[/help/tag|tag]</b> command.  For example:

<blockquote>
<b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i>
</blockquote>

The CHECK-IN in the previous line can be any
[./checkin_names.wiki | valid check-in name format].

You can also add (and remove) tags from a check-in using the
[./webui.wiki | web interface].  First locate the check-in that you 
what to tag on the tmline, then click on the link to go the detailed
information page for that check-in.  Then find the "<b>edit</b>"
link (near the "Commands:" label) and click on that.  There are
controls on the edit page that allow new tags to be added and existing
tags to be removed.</blockquote></li>

<a name="q5"></a>
<p><b>(5) 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
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.</blockquote></li>

<a name="q6"></a>
<p><b>(6) How can I delete inappropriate content from my fossil repository?</b></p>

<blockquote>See the article on [./shunning.wiki | "shunning"] for details.</blockquote></li>

<a name="q7"></a>
<p><b>(7) How do I make a clone of the fossil self-hosting repository?</b></p>

<blockquote>Any of the following commands should work:
<blockquote><pre>
fossil [/help/clone|clone]  http://www.fossil-scm.org/  fossil.fossil<br>
fossil [/help/clone|clone]  http://www2.fossil-scm.org/  fossil.fossil<br>
fossil [/help/clone|clone]  http://www3.fossli-scm.org/site.cgi  fossil.fossil
</pre></blockquote>
Once you have the repository cloned, you can open a local check-out
as follows:
<blockquote><pre>
mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil
</pre></blockquote>
Thereafter you should be able to keep your local check-out up to date
with the latest code in the public repository by typing:
<blockquote><pre>
fossil [/help/update|update]
</pre></blockquote></blockquote></li>

<a name="q8"></a>
<p><b>(8) How do I import or export content from and to other version control systems?</b></p>

<blockquote>Please see [./inout.wiki | Import And Export]</blockquote></li>

</ol>

<title>The Fossil Web Interface</title>


One of the innovative features of Fossil is its built-in web interface.
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]
  *  Status information
  *  Timelines
  *  Graphs of revision and branching history
  *  [./event.wiki | Blogs, News, and Announcements]
  *  File and version lists and differences
  *  Download historical versions as ZIP archives
  *  Historical change data

  *  Add and remove tags on checkins
  *  Move checkins between branches
  *  Revise checkin comments
  *  Manage user credentials and access permissions
  *  And so forth...

You get all of this, and more, for free when you use Fossil. 
There are no extra programs to install or setup.
Everything you need is already pre-configured and built into the
self-contained, stand-alone Fossil executable.

As an example of how useful this web interface can be,
the entire [./index.wiki | Fossil website] (except for the
[http://www.fossil-scm.org/download.html | download page]),
including the document you are now reading,
is rendered using the Fossil web interface, with no enhancements,
and little customization.

<blockquote>
<b>Key point:</b> <i>The Fossil website is just a running instance
of Fossil!
</blockquote>

Note also that because Fossil is a distributed system, you can run
the web interface on your local machine while off network (for example,
while on an airplane) including
making changes to wiki pages and/or trouble ticket, then synchronize with your
co-workers after you reconnect.  When you clone a Fossil repository, you
don't just get the project source code, you get the entire project
management website.

<h2>Drop-Dead Simple Startup</h2>

To start using the built-in Fossil web interface on an existing Fossil
repository, simply type this:

   <b>fossil ui existing-repository.fossil</b>

Substitute the name of your repository, of course.
The "ui" command will start a webserver running (it figures out an
available TCP port to use on its own) and then automatically launches 
your web browser to point at that server.  If you run the "ui" command
from within an open check-out, you can omit the repository name:

  <b>fossil ui</b>

The latter case is a very useful short-cut when you are working on a
Fossil project and you want to quickly do some work with the web interface.
Notice that Fossil automatically finds an unused TCP port to run the
server own and automatically points your web browser to the correct
URL.  So there is never any fumbling around trying to find an open
port or to type arcane strings into your browser URL entry box.
The interface just pops right up, ready to run.

The Fossil web interface is also very easy to setup and run on a
network server, as either a CGI program or from inetd.  Details on how
to do that are described further below.

<h2>Things To Do Using The Web Interface</h2>

You can view <b>timelines</b> of changes to the project.  The default
"Timeline" link on the menu bar takes you to a page that shows the 20
most recent check-ins, wiki page edits, ticket/bug-report changes,
and/or blog entries.
This gives a very useful snapshot of what has been happening lately on the
project.  You can click to go further back in time, if needed.  Or
follow hyperlinks to see details, including diffs and annotated diffs,
of individual check-ins, wiki page edits, ticket changes, and
blog edits.

You can view and edit <b>tickets and bug reports</b> by following the
"Tickets" link on the menu bar.
Fossil is backed by an SQL database, so users with appropriate permissions
can write new ticket report formats based on SQL query statements.
Fossil is careful to prevent ticket report formats from doing any mischief
on the database (it only allows SELECT statements to run) and it restricts

You can view and edit <b>wiki</b> by following the "Wiki" link on the
menu bar.  Fossil uses simple and easy-to-remember
[/wiki_rules | wiki formatting rules] so you won't have to spend a lot
of time learning a new markup language.  And, as with tickets, all of
your edits will automatically merge with those of your co-workers when
your repository synchronizes.

You can view summary reports of <b>branches</b> in the
check-in graph by visiting the "Branche" links on the
menu bar.  From those pages you can follow hyperlinks to get additional
details.  These screens allow you to easily keep track of what is going
on with separate subteams within your project team.

The "Files" link on the menu allows you to browse though the <b>file
hierarchy</b> of the project and to view complete changes histories on
individual files, with hyperlinks to the check-ins that made those

for the entire page.  You can even change around the main menu.
Timeline display preferences can be edited.  The page that is brought
up as the "Home" page can be changed.  It is often useful to set the
"Home" page to be a wiki page or an embedded document.

<h2>Installing On A Network Server</h2>

When you create a new Fossil project and after you have configured it
like you want it using the web interface, you can make the project
available to a distributed team by simply copying the single
repository file up to a web server that supports CGI.  Just put the
<b>sample-project.fossil</b> file in a directory where CGI scripts
have both read and write permission on the file and the directory that
contains the file, then add a CGI script that looks something like this:

  <verbatim>
  #!/usr/local/bin/fossil
  repository: /home/www/sample-project.fossil
  </verbatim>

Adjust the script above so that the paths are correct for your system,
of course, and also make sure the Fossil binary is installed on the server.
But that is <u>all</u> you have to do.  You now have everything you need to host
a distributed software development project in less than five minutes using a 
two-line CGI script.

You don't have a CGI-capable web server running on your server machine?
Not a problem.  The Fossil interface can also be launched via inetd or
xinetd.  An inetd configuration line sufficient to launch the Fossil
web interface looks like this:

  <verbatim>
  80 stream tcp nowait.1000 root /usr/local/bin/fossil \
  /usr/local/bin/fossil http /home/www/sample-project.fossil 
  </verbatim>

As always, you'll want to adjust the pathnames to whatever is appropriate
for your system.  The xinetd setup uses a different syntax but follows
the same idea.