Fossil

<h2>add</h2>

The often used <code>add</code> command is how you tell <b>fossil</b> to
include a (usually new) file in the repository.

<b>fossil</b> is designed to manage artifacts whose role is being
"source" for something, most probably software program code or other
text.  One can imagine all kinds of ways to let fossil know just what
constitutes a source; the simplest and most direct way it
<i>actually</i> finds out is when you give it the
<code> fossil add <i>path</i> </code> command.

It's reasonable to think of
the [./cmd_import.wiki | <code>import</code>]
and [./cmd_clone.wiki | <code>clone</code>]
commands as very high-powered versions of the <code>add</code>
command that are combined with system level file movement and
networking functions.  Not particularly accurate, but reasonable.

Typing <code>&nbsp;fossil add myfile</code> causes fossil to put
<i>myfile</i> into the repository at the next
<code>commit</code>—provided you issue it from within the source
tree, of course.

By contrast, <code>&nbsp;fossil add mydirectory</code> will add
<em><strong>all</strong></em> of the files in <i>mydirectory</i>, and
all of its sub-directories.  In other words, adding a directory will
recursively add all of the directory's file system descendants to the
repository.  This was an oft-requested feature, recently implemented.
It is very flexible.  Only when you add a directory do you get the
recursive behavior.  If you are globbing a subset of files, you won't
get the recursion.

Realize that the repository is <u>not</u> changed by the
<code>add</code> command, but by the <code>&nbsp;commit</code> command.
<code>add</code> <i>myfile</i> tells <b>fossil</b> to "mark"
<i>myfile</i> as part of the repository.  Only commands which actually
manipulate the content of the repository can physically put source
artifacts into (or remove them from) the repository.

Just to keep things symmetric, there are also commands that can
manipulate the repository without affecting the checked-out sources
(see [./cmd_pull.wiki | fossil pull], for instance.)

It's worthwhile reiterating that <b>fossil</b> is storing the content
of source artifacts and the names of the artifacts in their "native
habitat", a sequence of "temporal slices" (aka "versions") of the
state of the whole system, and a set of unique identifiers.  When you
add a file to a repository, the <i>path</i> to the file is a part of
the <i>name</i> of the file.  There is a mis-match between the file
system's idea of a directory (a file containing pointers to files) and
fossil's idea (a substring of the name of the artifact.)  The names of
the artifacts specify their relative locations because of the way the
file system interprets them.  If you don't keep this in mind, you may
fool yourself into thinking <b>fossil</b> somehow "stores
directories."  It doesn't, and believing it does will eventually
confuse you.

See also: [./cmd_rm.wiki | fossil rm],
[./cmd_import.wiki | fossil import],
[./cmd_clone.wiki | fossil clone],
[./cmd_commit.wiki | fossil commit],
[./cmd_pull.wiki | fossil pull],
[./cmd_settings.wiki | fossil setting] (async),
[./reference.wiki | Reference]

<h2>all</h2>

The <code>all</code> command will let you perform (some) commands on
<em>all</em> of your repositories, and provides a way of finding all
of your repositories as well.

There are some commands you might especially want to perform on every
repository you've got, once in a while.  <code> fossil&nbsp;all
</code> includes four of the most likely as sub-commands:
[./cmd_pull.wiki | <code>pull</code>],
[./cmd_push.wiki | <code>push</code>],
[./cmd_rebuild.wiki | <code>rebuild</code>] and
[./cmd_sync.wiki | <code>sync</code>].

Follow the links to find out what each of those do, and then a moment
of thought will tell you why you might want to have them available for
all repositories.

Certainly you'll want your repositories all rebuilt when you upgrade
<b>fossil</b> after there has been a change in the repository
structure.  For the others, it depends.  Usually you would want
across-the-board versions if you've been "off Net" for a while, and
have commits to multiple repositories than you need to share, or want
to get the repository changes that have been made by others, or both.

The last sub-command provided by <code>all</code> is "<code>list</code>."

While the other sub-commands give you a way to conveniently take care
of all of your repositories for some common tasks, the
<code>list</code> provides a way to take care of any subset of your
repositories in any way you want.  It provides a list of all of your
repositories' locations.  <code>fossil&nbsp;all&nbsp;list</code>
outputs a one-per-line listing of the path for each of your
repositories.  With that in hand, you can easily script just about any
repository manipulations you want.

Or, you could just jog your memory.

The <code>all</code> command uses the <i>.fossil</i> file in the home
directory to find all of your repositories, so you can mess it up by
moving your repositories around.  This is easy to do inadvertently if
you have a cavalier attitude about repos, but you'll know pretty
quickly that you've done it—many commands you try to use from
inside of a checkout won't work correctly.  The <i>.fossil</i> file is
an <b>sqlite</b> db file which fossil uses to keeping track of
repository locations. Advice: if you move your repositories around,
let fossil know you did;
[./cmd_close.wiki | <code>close</code>] them before you move
them, and then [./cmd_open.wiki | <code>open</code>] them from
their new locations.

See also: [./cmd_pull.wiki | fossil pull],
[./cmd_push.wiki | fossil push],
[./cmd_rebuild.wiki | fossil rebuild],
[./cmd_sync.wiki | fossil sync],
[./cmd_open.wiki | fossil open],
[./cmd_close.wiki | fossil close],
[./reference.wiki | Reference],
[http://www.sqlite.org | <b>SQLite</b>]

<h2>cgi</h2>

<code>cgi</code> is the command that tells fossil it is running as a
web-page supplier for an external http server.  (For you web-miesters,
the "cgi" is actually unnecessary if your web environment is set up in
a normal fashion.)

This is the command you will probably use if you want to make a
moderate-to-high hit rate public repository (like the <b>fossil</b>
project's self-hosted repository) but you'll be using it in the
shebang line.

If you need lower level access to the pages <b>fossil</b> generates,
you'll want to look at the [./cmd_http.wiki | <code>http</code>]
command.

See also: [./cmd_http.wiki | fossil http],
[./concepts.wiki#saserv | <i>Concepts (setting up a server)</i>],
[./reference.wiki | Reference]

<h2>changes</h2>

The <code>changes</code> command is informational, it doesn't do
anything to a checked-out project, but it tells you something about
it.

This is simply a quick way to get a list of the files which are
different in the source tree (the checkout) and the repository.

There is a bit more information (was a file edited, added or
removed?, for instance).

The same information will be displayed if you
[./cmd_status.wiki | <code>&nbsp;fossil&nbsp;status&nbsp;</code>],
except there will be some additional repository information displayed
first.

See also: [./cmd_status.wiki | fossil status],
[./reference.wiki | Reference]

<h2>checkout</h2>

The <code>checkout</code> command is how a project version goes from
the repository to the chosen project directory.

Without going into detail about getting/opening a repository, once you
have a repository and a place in which the repository has been
opened, you can "check out" a "version" of the files which make up the
repository at somewhen.

The term "checkout" is traditional in source management systems, but a
bit of an anachronism in a distributed system like <b>fossil</b>.
"Checking out" a version of a project means getting all of the source
artifacts out into the standard environment---currently the
shell/file-system.

Traditionally, the version is some "incrementing" code like
v1.3.2rcQuink or f451 or something.  In distributed SCM systems it's
some absolutely unique identifier, usually the result of a one-way
hash (SHA1, in fossil's case.)  The <b>fossil</b> term for these is
<em>artifact IDs</em>.

<code>fossil&nbsp;checkout&nbsp;</code> <i>id</i> will check out the
version corresponding to <i>id</i> into the source tree.

<code>checkout</code> requires you to pick a precise version to put into
the "on-disk" source tree, and leaves any edited files which are already
in the tree intact.

<code>update</code>, on the other hand, <em>merges</em> edits into the
version you choose (if you choose one; you can default the version.)

Since a version is required, and <b>fossil</b>'s artifact IDs are
fairly long, there are two good ways to refer to the version.  You can
use a unique proper prefix of the version (six or eight characters is
more than enough in most cases) <em>or</em> you can [./cmd_tag.wiki |
tag] your check-ins and use the tags for checkouts, reverting,
branching (tags are the best way to branch) and so forth.  Both
methods work throughout fossil.

See also [./cmd_tag.wiki | fossil tag],
[./cmd_revert.wiki | fossil revert],
[./cmd_update.wiki | fossil update],
[./cmd_push.wiki | fossil push],
[./cmd_pull.wiki | fossil pull],
[./cmd_clone.wiki | fossil clone],
[./cmd_open.wiki | fossil open],
[./cmd_close.wiki | fossil close],
[./cmd_new.wiki | fossil new],
[./reference.wiki | Reference]

<h2>extra</h2>

The <code>extra</code> command is informational, it doesn't do anything to
a checked-out project, but it tells you something about it.

Extra files are files that exist in a checked-out project, but don't belong to
the repository.

The <code>fossil extra</code> command will get you a list of these files.

This is convenient for figuring out if you've <code>
[./cmd_add.wiki | add]</code>ed every file that needs to be

in the repository before you do a commit.  It will also tell you what
will be removed if you [./cmd_clean.wiki | <code>clean</code>]
the project.

Suppose, for example, you have a "noodle.src" file as a scratch pad
for source code, and you don't want to include your latest
hare-brained ideas in the repository?  You don't <code>add</code> it
to the repository, of course—though there are ways you might add
it unintentionally.  If your project is big, and you want to find
noodle.src, and anything else that isn't under source control within
the project directories, then<code> fossil&nbsp;extra </code> will
give you a list.

If you don't think this is all that useful, then you've never had to write
a shell script that only affects project files and leaves everything
else alone.  ;)

The <code>extra</code> command is almost, but not quite entirely, the exact
opposite of the [./cmd_ls.wiki | <code>ls</code>] command.

See also: [./cmd_status.wiki | fossil status],
[./cmd_ls.wiki | fossil ls],
[./cmd_changes.wiki | fossil changes],
[./cmd_clean.wiki | fossil clean],
[./reference.wiki | Reference]

<h2>ls</h2>

The <code>ls</code><a href="#notes">*</a> command is informational, it doesn't do anything to
a checked-out project, but it tells you something about it.

A project consists of a "source tree" of "artifacts" (see [./concepts.wiki | Fossil concepts].)
From a practical standpoint this is a set of files and directories rooted
at a main project directory.  The files that are under source control aren't
particularly distinguishable from those that aren't.  The <code>ls</code> and
<code>extra</code> commands provide this information.

<code>fossil ls</code> produces a listing of the files which are under source
control <i>and</i> their status within the repository.  The output is a simple
list of STATUS/filepath pairs on separate lines.  The status of a file will
likely be one of ADDED, UNCHANGED, UPDATED, or DELETED. <a href="#notes">*</a>

It's important to realize that this is the status <i>relative to the repository</i>,
it's the status as <b>fossil</b> sees it and has nothing to do with
filesystem status.  If you're new to source-management/version-control
systems, you'll probably get bit by this concept-bug at least once.

To really see the difference, issue an <code>ls</code> before and after doing
a [./cmd_commit.wiki | <code>commit</code>].  Before, the status of files may be any of the three,
but after <code>commit</code>ting changes the status will be UNCHANGED "across
the board."

By way of example, here's what I see if I <code>fossil ls</code> in the
directory where I have checked out my testing repository:
<nowiki><pre>
    $ fossil ls
    ADDED     feegboing
    UNCHANGED fossil_docs.txt
    DELETED   nibcrod
</pre></nowiki>
But if I do a simple ls, what I get is
<nowiki><pre>
    $ ls
    feegboing  fossil_docs.txt  manifest.uuid  noodle.txt
    _FOSSIL_   manifest         nibcrod
</pre></nowiki>

The <code>ls</code> command is almost, but not quite entirely, the exact
opposite of the
[./cmd_extra.wiki | <code>extra</code> command].

<a name="notes">Notes:</a>
  *  If you come from the <b>Windows</b> world, it will help to know that 'ls' is the usual <b>unix</b> command for listing a directory.
  *  There are more states for a file to be in than those listed, including MISSING, EDITED, RENAMED and a couple of others.

See also: [./cmd_add.wiki | fossil add],
[./rm.wiki | fossil rm],
[./cmd_extra.wiki | fossil extra],
[./cmd_commit.wiki | fossil commit],
[./concepts.wiki | Fossil concepts],
[./reference.wiki | Reference]

<h2>mv | rename</h2>

The <code>mv</code> (alias "<code>rename</code>") command tells
<b>fossil</b> that a file has gone from one external name to another
without changing content.

You could do this by renaming the file in the file system,
[./cmd_rm.wiki | deleting] the old name from the project, and
[./cmd_add.wiki | adding] the new name.  But you would lose the
continuity of the <u>content's</u> history that way.  Using
<code>mv</code> makes the name change a part of the history
maintained by <b>fossil</b>.  You will, of course, need a good
comment somewhere (say, the commit comment) if you want to
remember <em>why</em> you changed the name...  <b>fossil</b>
only maintains history, it doesn't (yet) explain it.

<code>mv</code> is much like the [./cmd_rm.wiki | <code>rm</code>]
command, in that it manipulates <b>fossil</b>'s "idea" of what is
part of the project.  The difference is that <code>mv</code> assumes
you have actually made some change to the file system.

See also: [./cmd_rm.wiki | fossil rm],
[./cmd_add.wiki | fossil add],
[./reference.wiki | Reference]

<h2>new</h2>

The <code>new</code> command allows you to create a brand new
repository.

Pragmatically, this means that an SQLite database is created with
whatever name you specified, and set up with the appropriate tables
and initial data.

There's not much to <code>new</code>, it's what happens afterward that
gets a project going:

  Once you have a new repository file, you need to create and cd to a
  directory in which you will store your files, or move into an
  existing directory which contains the files for a project.

  Then, you need to [./cmd_open.wiki | <code>open</code>] the new
  repository, and get the server running so you can set up the project
  name and so forth.

  Finally, you'll [./cmd_add.wiki | <code>add</code>] files to it.  If
  you are adding exisiting files, you can add them individually, via
  globbing from the shell, or by adding the directory (which will add
  all of the directory's file-system descendants recursively.)

But you can't do all that until you create a repository file with
<code>new</code>.

See also:
[./cmd_open.wiki | fossil open],
[./cmd_add.wiki | fossil add],
[./cmd_server.wiki | fossil ui],
[./reference.wiki | Reference]

<h2>del | rm</h2>

The <code>del</code> (alias <code>rm</code>) command takes a "file"
<em>out</em> of a project.

It does <u>not</u> delete the file from the repository, it does
<u>not</u> remove the file from the file system on disk.  It tells
<b>fossil</b> that the file is no longer a part of the project for
which <b>fossil</b> is maintaining the sources.

For example, if you have a nice, clean source tree and use the
[./cmd_extra.wiki | <code>extra</code>] command on it, you won't
get any output.  If you then <code>rm</code> some file and commit
the change, that file will be listed by the <code>extra</code>
command.

The file is still on the disk, and it is still in the repository.
<strong>But</strong> the file <em>is not part of the project</em>
anymore.  Further changes to the file will not be checked in unless
you [./cmd_add.wiki | <code>add</code>] the file again.

It can initially be confusing to see a file that's been "deleted"
still showing up in the files list in the repository, but remember
that the files list currently<a href="#vnote"><sup>*</sup></a> shows
all of the files that have ever been in the repository <em>because
<b>fossil</b> is a source control system and therefore keeps a record
of the history of a project.</em>

To get a list of the files <em>only in the current version</em> of the
project, use the [./cmd_ls.wiki | <code>ls</code>] command.

The <code>del</code> command is the logical opposite of the
[./cmd_add.wiki | <code>add</code>] command, in its single-file-add
form.

<font size="-1"><a name="vnote"><sup>*</sup></a>version 7c281b629a on 20081220</font>

See also: [./cmd_add.wiki | fossil add],
[./cmd_ls.wiki | fossil ls],
[./reference.wiki | Reference]

<h2>status</h2>

The <code>status</code> command is informational, it doesn't do anything to
a checked-out project, but it tells you something about it.

Running <code>&nbsp;fossil&nbsp;status&nbsp;</code> currently prefixes
the output of the <code>[./cmd_changes.wiki | changes]</code> command
with information about the repository and checkout.  The information
is in the form of the [./concepts.wiki#aidex | Artifact ID]s of the
server code, the checkout, and the parent (of, I <em>think</em> the
checkout.)

This is useful for getting an at-a-glance view of the state of your
project, especially in a situation where you need the artifact IDs.

Here is what I get when I issue a <code>status</code> on my local
version of the <b>fossil</b> repository as I write this:

<nowiki><pre>
   $ fossil status
   repository:   /home/me/myclone.fossil
   local-root:   /home/me/fossil/
   server-code:  99d6c9cf3f262720579db177503812814d712fc7
   checkout:     a8c3a7ea9249281e0a1fb55fb31d2ad57844f848
   parent:       21cecd209f7201f17e8a784c0d8f735603d440ae
   EDITED   www/cmd_.wiki-template
   EDITED   www/cmd_add.wiki
   EDITED   www/cmd_all.wiki
   EDITED   www/cmd_extra.wiki
   EDITED   www/cmd_ls.wiki
   EDITED   www/cmd_update.wiki
   EDITED   www/index.wiki
   $
</pre></nowiki>

Once I actually make changes to the repository (say, a
[./cmd_commit.wiki | commit]) most of that will change—all
of those files showing as "EDITED" will be checked in and won't
show up, and the artifact IDs will reflect the new state of the
repository.

If the only thing you want to see is which files in the checked-out
source tree have changed in some way, use the
[./cmd_changes.wiki | <code>changes</code>] command.

If what you want is the files in the checked-out source tree which are
<em>not</em> part of the project, use the
[./cmd_extra.wiki | <code>extra</code>] command.

See also: [./cmd_changes.wiki | fossil changes],
[./cmd_extra.wiki | fossil extra],
[./concepts.wiki | <i>Fossil concepts</i>],
[./reference.wiki | Reference]

<h2>sync</h2>

The <code>sync</code> command [./cmd_pull.wiki | <code>pull</code>]s and
[./cmd_push.wiki | <code>push</code>]es repository changes simultaneously.

This applies to repositories available via a URL, of course.  If your
project is strictly local you can do all of the distributed stuff as
long as you are "serving" the repository via http in some fashion, but
it's probably pointless to do so.

Assuming you aren't running <b>fossil</b> as a high-powered version of
[http://www.gnu.org/software/rcs | RCS], your use of <code>sync</code>
in your projects is up to you.  <b>fossil</b> defaults to using a
[./cmd_setting.wiki | setting] of <code>autosync</code>
If you have cloned a repository you will automatically sync with the
original if you [./cmd_commit.wiki | commit] changes to your local
version <em>unless</em> you customize your configuration.

See also: [./cmd_pull.wiki | fossil pull],
[./cmd_push.wiki | fossil push],
[./cmd_setting.wiki | fossil setting],
[./reference.wiki | Reference]

<h2>update</h2>

What do you do if you have changes out on a repository and
you want them merged with your checkout?

You use the <code>update</code> command.

<b>fossil</b> can [./about_checkout.wiki | overwrite] any
changes you've made to your checkout, or it can
[./about_merge.wiki | merge] whatever changes have occurred
in the repo into your checkout.

Update <em>merges</em> changes from the repository into your checkout.

<b>fossil</b> uses a simple conflict resolution strategy for merges:
the latest change wins.

Local intranet <code>[./cmd_commit.wiki | commit]</code>s
(by someone else)
or Net <code>[./cmd_pull.wiki | pull]</code>s from a server
will usually require a <code>fossil&nbsp;update</code> afterward.

Local commits are likely to be made with
[./cmd_settings.wiki#autosync | automatic syncing]
set to "on", however, so if you don't use <b>fossil</b> for Net-wide
projects you may never have to use <code>update</code>.

See also: [./cmd_pull.wiki | fossil pull],
[./cmd_commit.wiki | fossil commit],
[./cmd_settings.wiki#autosync | fossil setting] (autosync),
[./about_checkout.wiki | <i>checkouts</i>],
[./about_merge.wiki | <i>merging</i>],
[./reference.wiki | Reference]

<h2>version</h2>

The <code>version</code> command is informational, it doesn't do
anything to a checked-out project, but it tells you something about
it.

Issuing the version command will print out the short-form of the
artifact ID for the fossil executable.

See also: [./cmd_status.wiki | fossil status],
[./cmd_info.wiki | fossil info],
[./reference.wiki | Reference]

  <h2>Command Line Interface Reference</h2>

  This is an easy introduction to the fossil command line interface
  (cli).  It assumes some familiarity with using the command line, and
  with Source Code Maintenence (SCM) systems—but not <i>too</i>
  much.

  If you are trying to find information about fossil's web
  capabilities, see the <a href="index.wiki">Fossil Home</a> and
  <a href="wikitheory.wiki">Fossil Wiki</a> pages for pointers.

  <h3>Things to note</h3>
  * Fossil cli commands do not use special delimeters, they use
  spaces.  This is traditional with VCS/SCM.  Some <i>options</i> to
  fossil commands <i>do</i> use special delimiters, particularly the
  '-' (hyphen, or dash) character.  This is very similar to Tcl.
  Think of fossil as a shell you invoke and feed a command to,
  including any options, and it will make more sense.

  * Any fossil command is acceptable once enough of it has been
  entered to make the intent unambiguous.  'clo' is a proper prefix of
  both the 'clone' and 'close' commands, for instance, but 'clon' is
  enough to make the intent—the 'clone'
  command—unambiguous.

  * Pragmatically, a [./concepts.wiki#keyconc | <u>version</u>]
  in <b>fossil</b> is a 40-character long string of hexadecimal.
  <b>fossil</b> will be able to figure out which version you want
  with any <i>distinct</i> prefix of that string which is at
  least four characters long.  <em>Commands which require a
  version are looking for the string, a distinct prefix of the
  string, or a <code>tag</code>.</em>

  * SCM in a distributed environment can be a bit confusing with
  regard to branching, merging, and versions in general.  See the
  [./branching.wiki | explanation of branching] and it will all make
  much more sense.

  * <i>Op.Ed.</i> An excellent way to learn to use <b>fossil</b>
    effectively is to
    [./quickstart.wiki#fslclone | clone the repository for fossil]
    itself.  You can then poke around using the <code>fossil ui</code>
    command, and look things up with no connection worries.  You can
    set up test repositories and try things out on-the-fly to see how
    they work, using their own ui's.  The CLI will far easier to
    understand if you can run a repository, watch it in a browser, and
    hack around with it in a simplified environment (your tests) with
    guaranteed and fast access to the sources & docs (your cloned fossil
    repository).
<br /><br /> <br />
  <b>You should</b> probably start interacting with fossil at the command
  line by asking it what it can
  do:&nbsp;&nbsp;&nbsp;&nbsp;<a name="tof">ˆ</a>

  <code>$ fossil help</code><nowiki><pre>
Usage: fossil help COMMAND.
Available COMMANDs:</pre><table width="80%"
                          style="font-family: fixed, courier, monospace;">
  <tr>
    <td><a href="#add">add</a>*</td>
    <td><a href="#checkout">co</a>*</td>
    <td><a href="#http">http</a></td>
    <td><a href="#rebuild">rebuild</a></td>
    <td><a href="#sync">sync</a>*</td>
  </tr>
  <tr>
    <td><a href="#all">all</a>*</td>
    <td><a href="#commit">commit</a></td>
    <td><a href="#info">info</a></td>
    <td><a href="#reconstruct">reconstruct</a></td>
    <td><a href="#tag">tag</a></td>
  </tr>
  <tr>
    <td><a href="#branch">branch</a></td>
    <td><a href="#configuration">configuration</a></td>
    <td><a href="#leaves">leaves</a></td>
    <td><a href="#redo">redo</a></td>
    <td><a href="#timeline">timeline</a></td>
  </tr>
  <tr>
    <td><a href="#cgi">cgi</a>*</td>
    <td><a href="#deconstruct">deconstruct</a></td>
    <td><a href="#ls">ls</a>*</td>
    <td><a href="#mv">rename</a>*</td>
    <td><a href="#server">ui</a></td>
  </tr>
  <tr>
    <td><a href="#changes">changes</a>*</td>
    <td><a href="#rm">del</a>*</td>
    <td><a href="#merge">merge</a></td>
    <td><a href="#revert">revert</a></td>
    <td><a href="#undo">undo</a></td>
  </tr>
  <tr>
    <td><a href="#checkout">checkout</a>*</td>
    <td><a href="#descendants">descendants</a></td>
    <td><a href="#mv">mv</a>*</td>
    <td><a href="#rm">rm</a>*</td>
    <td><a href="#settings">unset</a></td>
  </tr>
  <tr>
    <td><a href="#commit">ci</a></td>
    <td><a href="#diff">diff</a></td>
    <td><a href="#new">new</a>*</td>
    <td><a href="#rstats">rstats</a></td>
    <td><a href="#update">update</a>*</td>
  </tr>
  <tr>
    <td><a href="#clean">clean</a></td>
    <td><a href="#extra">extra</a>*</td>
    <td><a href="#open">open</a></td>
    <td><a href="#server">server</a></td>
    <td><a href="#user">user</a></td>
  </tr>
  <tr>
    <td><a href="#clone">clone</a></td>
    <td><a href="#diff">gdiff</a></td>
    <td><a href="#pull">pull</a></td>
    <td><a href="#settings">settings</a></td>
    <td><a href="#version">version</a>*</td>
  </tr>
  <tr>
    <td><a href="#close">close</a></td>
    <td><a href="#help">help</a></td>
    <td><a href="#push">push</a></td>
    <td><a href="#status">status</a>*</td>
    <td><a href="#wiki">wiki</a></td>
  </tr>
</table><nowiki><pre>
This is fossil version [a89b436bc9] 2009-02-11 05:00:02 UTC
</pre>
<b>What follows</b> is a survey of what you get if you type<code>
fossil&nbsp;help&nbsp;<i>command</i> </code>for all of the
commands listed above.  There are links to individual pages for each
of them; pages with content (commands marked with a '*' are done) go
into the reason for a command in a bit more depth than the program help.
<pre>
<hr><a href="#tof">ˆ</a>
    <a name="add">Usage: </a><code><a href="cmd_add.wiki">fossil add</a></code> FILE...
    Make arrangements to add one or more files to the current checkout
    at the next commit.

<hr><a href="#tof">ˆ</a>
    <a name="all">Usage: </a><code><a href="cmd_all.wiki">fossil all</a></code> (list|pull|push|rebuild|sync)
    The ~/.fossil file records the location of all repositories for a
    user.  This command performs certain operations on all repositories
    that can be useful before or after a period of disconnection operation.

    On Win32 systems, this file is located in %LOCALAPPDATA%, %APDDATA%
    or %HOMEPATH% and is named _fossil.

    Available operations are:

    list       Display the location of all repositories

    pull       Run a "pull" operation on all repositories

    push       Run a "push" on all repositories

    rebuild    Rebuild on all repositories

    sync       Run a "sync" on all repositories

    Respositories are automatically added to the set of known repositories
    when one of the following commands against the repository: clone, info,
    pull, push, or sync

<hr><a href="#tof">ˆ</a>
    <a name="branch">Usage: </a><code><a href="cmd_branch.wiki">fossil branch</a></code> SUBCOMMAND ... ?-R|--repository FILE?

Run various subcommands on the branches of the open repository or
of the repository identified by the -R or --repository option.

   fossil branch new BRANCH-NAME BASIS ?-bgcolor COLOR?

       Create a new branch BRANCH-NAME off of check-in BASIS.
       You can optionally give the branch a default color.

   fossil branch list

       List all branches

<hr><a href="#tof">ˆ</a>
    <a name="cgi">Usage: </a><a href="cmd_cgi.wiki">fossil cgi</a> SCRIPT
    The SCRIPT argument is the name of a file that is the CGI script
    that is being run.  The command name, "cgi", may be omitted if
    the GATEWAY_INTERFACE environment variable is set to "CGI" (which
    should always be the case for CGI scripts run by a webserver.)  The
    SCRIPT file should look something like this:

    #!/usr/bin/fossil
    repository: /home/somebody/project.db

    The second line defines the name of the repository.  After locating
    the repository, fossil will generate a webpage on stdout based on
    the values of standard CGI environment variables.

<hr><a href="#tof">ˆ</a>
    <a name="changes">Usage: </a><a href="cmd_changes.wiki">fossil changes</a>
    Report on the edit status of all files in the current checkout.
    See also the "status" and "extra" commands.

<hr><a href="#tof">ˆ</a>
    <a name="checkout">Usage: </a><a href="cmd_checkout.wiki">fossil checkout</a> VERSION ?-f|--force?
    Check out a version specified on the command-line.  This command
    will not overwrite edited files in the current checkout unless
    the --force option appears on the command-line.

    See also the "update" command.

<hr><a href="#tof">ˆ</a>
    <a name="commit">Usage: </a><a href="cmd_commit.wiki">fossil commit</a> ?-m COMMENT? ?--nosign? ?FILE...?    fossil ci  ...  (as above)

    Create a new version containing all of the changes in the current
    checkout.  You will be prompted to enter a check-in comment unless
    the "-m" option is used to specify a comment line.  You will be
    prompted for your GPG passphrase in order to sign the new manifest
    unless the "--nosign" option is used.  All files that have
    changed will be committed unless some subset of files is specified
    on the command line.

<hr><a href="#tof">ˆ</a>
    <a name="clean">Usage: </a><a href="cmd_clean.wiki">fossil clean</a> ?-all?
    Delete all "extra" files in the source tree.  "Extra" files are
    files that are not officially part of the checkout.  See also
    the "extra" command. This operation cannot be undone.

    You will be prompted before removing each file. If you are
    sure you wish to remove all "extra" files you can specify the
    optional -all flag.

<hr><a href="#tof">ˆ</a>
    <a name="clone">Usage: </a><a href="cmd_clone.wiki">fossil clone</a> URL FILENAME
    Make a clone of a repository specified by URL in the local
    file named FILENAME.

<hr><a href="#tof">ˆ</a>
    <a name="close">Usage: </a><a href="cmd_close.wiki">fossil close</a> ?-f|--force?
    The opposite of "open".  Close the current database connection.
    Require a -f or --force flag if there are unsaved changed in the
    current check-out.

<hr><a href="#tof">ˆ</a>
    <a name="configuration">Usage: </a><a href="cmd_configure.wiki">fossil configuration</a> METHOD ...
    Where METHOD is one of: export import merge pull push reset.  All methods
    accept the -R or --repository option to specific a repository.

    fossil configuration export AREA FILENAME

    Write to FILENAME exported configuraton information for AREA.
    AREA can be one of:  all ticket skin project

    fossil configuration import FILENAME

    Read a configuration from FILENAME, overwriting the current
    configuration.

    fossil configuration merge FILENAME

    Read a configuration from FILENAME and merge its values into
    the current configuration.  Existing values take priority over
    values read from FILENAME.

    fossil configuration pull AREA ?URL?

    Pull and install the configuration from a different server
    identified by URL.  If no URL is specified, then the default
    server is used.
    fossil configuration push AREA ?URL?

    Push the local configuration into the remote server identified
    by URL.  Admin privilege is required on the remote server for
    this to work.

    fossil configuration reset AREA

    Restore the configuration to the default.  AREA as above.

    WARNING: Do not import, merge, or pull configurations from an untrusted
    source.  The inbound configuration is not checked for safety and can
    introduce security vulnerabilities.

<hr><a href="#tof">ˆ</a>
    COMMAND: deconstruct
    <a name="deconstruct">Usage: </a><a href="cmd_deconstruct.wiki">fossil deconstruct</a> ?-R|--repository REPOSITORY? DESTINATION
    Populates the indicated DESTINATION directory with copies of all
    artifcats contained within the repository.  Artifacts are named AA/bbbbb
    where AA is the first 2 characters of the artifact ID and bbbbb is the
    remaining 38 characters.

<hr><a href="#tof">ˆ</a>
    <a name="rm">Usage: </a><a href="cmd_rm.wiki">fossil rm</a> FILE...    or: fossil del FILE...
    Remove one or more files from the tree.

<hr><a href="#tof">ˆ</a>
    <a name="descendants">Usage: </a><a href="cmd_descendants.wiki">fossil descendants</a> ?CHECKIN-ID?
    Find all leaf descendants of the check-in specified or if the argument
    is omitted, of the check-in currently checked out.

<hr><a href="#tof">ˆ</a>
    <a name="diff">Usage: </a><a href="cmd_diff.wiki">fossil diff</a>|gdiff ?-i? ?-r REVISION? FILE...
    Show the difference between the current version of a file (as it
    exists on disk) and that same file as it was checked out.

    diff will show a textual diff while gdiff will attempt to run a
    graphical diff command that you have setup. If the choosen command
    is not yet configured, the internal textual diff command will be
    used.

    If -i is supplied for either diff or gdiff, the internal textual
    diff command will be executed.

    Here are a few external diff command settings, for example:

    fossil setting diff-command diff

    fossil setting gdiff-command tkdiff
    fossil setting gdiff-command eskill22
    fossil setting gdiff-command tortoisemerge
    fossil setting gdiff-command meld
    fossil setting gdiff-command xxdiff
    fossil setting gdiff-command kdiff3

<hr><a href="#tof">ˆ</a>
    <a name="extra">Usage: </a><a href="cmd_extra.wiki">fossil extra</a>
    Print a list of all files in the source tree that are not part of
    the current checkout.  See also the "clean" command.

<hr><a href="#tof">ˆ</a>
    <a name="help">Usage: </a><a href="cmd_help.wiki">fossil help</a> COMMAND
    Display information on how to use COMMAND

<hr><a href="#tof">ˆ</a>
    <a name="http">Usage: </a><a href="cmd_http.wiki">fossil http</a> REPOSITORY
    Handle a single HTTP request appearing on stdin.  The resulting webpage
    is delivered on stdout.  This method is used to launch an HTTP request
    handler from inetd, for example.  The argument is the name of the    repository.

<hr><a href="#tof">ˆ</a>
    <a name="info">Usage: </a><a href="cmd_info.wiki">fossil info</a> ?ARTIFACT-ID|FILENAME?
    With no arguments, provide information about the current tree.
    If an argument is specified, provide information about the object
    in the respository of the current tree that the argument refers
    to.  Or if the argument is the name of a repository, show
    information about that repository.

<hr><a href="#tof">ˆ</a>
    <a name="leaves">Usage: </a><a href="cmd_leaves.wiki">fossil leaves</a>
    Find leaves of all branches.

<hr><a href="#tof">ˆ</a>
    <a name="ls">Usage: </a><a href="cmd_ls.wiki">fossil ls</a>
    Show the names of all files in the current checkout

<hr><a href="#tof">ˆ</a>
    <a name="merge">Usage: </a><a href="cmd_merge.wiki">fossil merge</a> VERSION
    The argument is a version that should be merged into the current
    checkout.
    Only file content is merged.  The result continues to use the
    file and directory names from the current check-out even if those
    names might have been changed in the branch being merged in.

<hr><a href="#tof">ˆ</a>
    <a name="mv">Usage: </a><a href="cmd_mv.wiki">fossil mv|rename</a> OLDNAME NEWNAME       or: fossil mv|rename OLDNAME... DIR

    Move or rename one or more files within the tree

    This command does not rename the files on disk.  All this command does is
    record the fact that filenames have changed so that appropriate notations
    can be made at the next commit/checkin.

<hr><a href="#tof">ˆ</a>
    <a name="new">Usage: </a><a href="cmd_new.wiki">fossil new</a> FILENAME

    Create a repository for a new project in the file named FILENAME.
    This command is distinct from "clone".  The "clone" command makes
    a copy of an existing project.  This command starts a new project.

<hr><a href="#tof">ˆ</a>
    <a name="open">Usage: </a><a href="cmd_open.wiki">fossil open</a> FILENAME
    Open a connection to the local repository in FILENAME.  A checkout
    for the repository is created with its root at the working directory.
    See also the "close" command.

<hr><a href="#tof">ˆ</a>
    <a name="rstats">Usage: </a><a href="cmd_rstats.wiki">fossil rstats</a>

    Deliver a report of the repository statistics for the
    current checkout.

<hr><a href="#tof">ˆ</a>
    <a name="pull">Usage: </a><a href="cmd_pull.wiki">fossil pull</a> ?URL? ?-R|--respository REPOSITORY?
    Pull changes in a remote repository into the local repository.
    The repository is identified by the -R or --repository option.
    If there is no such option then the open repository is used.
    The URL of the remote server is specified on the command line
    If no URL is specified then the URL used by the most recent
    "pull", "push", or "sync" command is used.

    The URL is of the following form:

    http://USER@HOST:PORT/PATH

    The "USER@" and ":PORT" substrings are optional.
    The "USER" substring specifies the login user.  You will be
    prompted for the password on the command-line.  The PORT
    specifies the TCP port of the server.  The default port is
    80.

<hr><a href="#tof">ˆ</a>
    <a name="push">Usage: </a><a href="cmd_push.wiki">fossil push</a> ?URL? ?-R|--repository REPOSITORY?
    Push changes in the local repository over into a remote repository.
    See the "pull" command for additional information.

<hr><a href="#tof">ˆ</a>
    <a name="rebuild">Usage: </a><a href="cmd_rebuild.wiki">fossil rebuild</a> REPOSITORY
    Reconstruct the named repository database from the core
    records.  Run this command after updating the fossil
    executable in a way that changes the database schema.

<hr><a href="#tof">ˆ</a>
    COMMAND: reconstruct
    <a name="reconstruct">Usage: </a><a href="cmd_reconstruct.wiki">fossil reconstruct</a> REPOSITORY ORIGIN
    Creates the REPOSITORY and populates it with the artifacts in the
    indicated ORIGIN directory.

<hr><a href="#tof">ˆ</a>
    <a name="redo">Usage: </a><a href="cmd_redo.wiki">fossil redo</a> ?FILENAME...?
    Redo the an update or merge operation that has been undone by the
    undo command.  If FILENAME is specified then restore the changes
    associated with the named file(s) but otherwise leave the update
    or merge undone.

    A single level of undo/redo is supported.  The undo/redo stack
    is cleared by the commit and checkout commands.

<hr><a href="#tof">ˆ</a>
    <a name="revert">Usage: </a><a href="cmd_revert.wiki">fossil revert</a> ?--yes? ?-r CHECKIN? FILE
    Revert to the current repository version of FILE, or to
    the version associated with check-in CHECKIN if the -r flag
    appears.  This command will confirm your operation unless the
    file is missing or the --yes option is used.

<hr><a href="#tof">ˆ</a>
    <a name="server">Usage: </a><a href="cmd_server.wiki">fossil server</a> ?-P|--port TCPPORT? ?REPOSITORY?    Or: fossil ui ?-P|--port TCPPORT? ?REPOSITORY?

    Open a socket and begin listening and responding to HTTP requests on
    TCP port 8080, or on any other TCP port defined by the -P or
    --port option.  The optional argument is the name of the repository.
    The repository argument may be omitted if the working directory is
    within an open checkout.

    The "ui" command automatically starts a web browser after initializing
    the web server.

<hr><a href="#tof">ˆ</a>
    COMMAND: settings
    COMMAND: unset
    <a name="settings">Usage: </a><a href="cmd_setting.wiki">fossil settings</a> ?PROPERTY? ?VALUE? ?-global?
    fossil unset PROPERTY ?-global?

    The "settings" command with no arguments lists all properties and their
    values.  With just a property name it shows the value of that property.
    With a value argument it changes the property for the current repository.

    The "unset" command clears a property setting.

       autosync         If enabled, automatically pull prior to
		        commit or update and automatically push
		        after commit or tag or branch creation.

       diff-command     External command to run when performing a diff.
		        If undefined, the internal text diff will be used.

       editor           Text editor command used for check-in comments.

       http-port        The TCP/IP port number to use by the "server"
		        and "ui" commands.  Default: 8080

       gdiff-command    External command to run when performing a graphical
		        diff. If undefined, text diff will be used.

       localauth        If enabled, require that HTTP connections from
		        127.0.0.1 be authenticated by password.  If
		        false, all HTTP requests from localhost have
		        unrestricted access to the repository.

       clearsign        When enabled (the default), fossil will attempt to
		        sign all commits with gpg.  When disabled, commits will
		        be unsigned.

       pgp-command      Command used to clear-sign manifests at check-in.
		        The default is "gpg --clearsign -o ".

       mtime-changes    Use file modification times (mtimes) to detect when
		        files have been modified.

       proxy            URL of the HTTP proxy.  If undefined or "on" then
		        the "http_proxy" environment variable is consulted.
		        If the http_proxy environment variable is undefined
		        then a direct HTTP connection is used.

       web-browser      A shell command used to launch your preferred
		        web browser when given a URL as an argument.
		        Defaults to "start" on windows, "open" on Mac,
		        and "firefox" on Unix.

<hr><a href="#tof">ˆ</a>
    <a name="status">Usage: </a><a href="cmd_status.wiki">fossil status</a>
    Report on the status of the current checkout.

<hr><a href="#tof">ˆ</a>
    <a name="sync">Usage: </a><a href="cmd_sync.wiki">fossil sync</a> ?URL? ?-R|--repository REPOSITORY?
    Synchronize the local repository with a remote repository.  This is
    the equivalent of running both "push" and "pull" at the same time.
    See the "pull" command for additional information.

<hr><a href="#tof">ˆ</a>
    <a name="tag">Usage: </a><a href="cmd_tag.wiki">fossil tag</a> SUBCOMMAND ...
    Run various subcommands to control tags and properties

    fossil tag add ?--raw? TAGNAME CHECK-IN ?VALUE?

    Add a new tag or property to CHECK-IN. The tag will
    be usable instead of a CHECK-IN in commands such as
    update and merge.

    fossil tag branch ?--raw? ?--nofork? TAGNAME CHECK-IN ?VALUE?

    A fork will be created so that the new checkin
    is a sibling of CHECK-IN and identical to it except
    for a generated comment. Then the new tag will
    be added to the new checkin and propagated to
    all direct children.  Additionally all symbolic
    tags of that checkin inherited from CHECK-IN will
    be cancelled.

    However, if the option --nofork is given, no
    fork will be created and the tag/property will be
    added to CHECK-IN directly. No tags will be canceled.

    fossil tag cancel ?--raw? TAGNAME CHECK-IN

    Remove the tag TAGNAME from CHECK-IN, and also remove
    the propagation of the tag to any descendants.

    fossil tag find ?--raw? TAGNAME

    List all check-ins that use TAGNAME

    fossil tag list ?--raw? ?CHECK-IN?

    List all tags, or if CHECK-IN is supplied, list
    all tags and their values for CHECK-IN.

    The option --raw allows the manipulation of all types of
    tags used for various internal purposes in fossil. You
    should not use this option to make changes unless you are
    sure what you are doing.

    If you need to use a tagname that might be confused with
    a hexadecimal check-in or artifact ID, you can explicitly
    disambiguate it by prefixing it with "tag:". For instance:

    fossil update decaf

    will be taken as an artifact or check-in ID and fossil will
    probably complain that no such revision was found. However

    fossil update tag:decaf

    will assume that "decaf" is a tag/branch name.

<hr><a href="#tof">ˆ</a>
    <a name="timeline">Usage: </a><a href="cmd_timeline.wiki">fossil timeline</a> ?WHEN? ?CHECK-IN|DATETIME? ?-n|--count N?
    Print a summary of activity going backwards in date and time
    specified or from the current date and time if no arguments
    are given.  Show as many as N (default 20) check-ins.  The
    WHEN argument can be any unique abbreviation of one of these
    keywords:

    before
    after
    descendants | children
    ancestors | parents

    The CHECK-IN can be any unique prefix of 4 characters or more.
    The DATETIME should be in the ISO8601 format.  For
    examples: "2007-08-18 07:21:21".  You can also say "current"
    for the current version or "now" for the current time.

<hr><a href="#tof">ˆ</a>
    <a name="undo">Usage: </a><a href="cmd_undo.wiki">fossil undo</a> ?FILENAME...?
    Undo the most recent update or merge operation.  If FILENAME is
    specified then restore the content of the named file(s) but otherwise
    leave the update or merge in effect.

    A single level of undo/redo is supported.  The undo/redo stack
    is cleared by the commit and checkout commands.

<hr><a href="#tof">ˆ</a>
    <a name="update">Usage: </a><a href="cmd_update.wiki">fossil update</a> ?VERSION? ?--latest?
    The optional argument is a version that should become the current
    version.  If the argument is omitted, then use the leaf of the
    tree that begins with the current version, if there is only a    single leaf.  If there are a multiple leaves, the latest is used
    if the --latest flag is present.

    This command is different from the "checkout" in that edits are
    not overwritten.  Edits are merged into the new version.

<hr><a href="#tof">ˆ</a>
    <a name="user">Usage: </a><a href="cmd_user.wiki">fossil user</a> SUBCOMMAND ...  ?-R|--repository FILE?
    Run various subcommands on users of the open repository or of
    the repository identified by the -R or --repository option.

    fossil user capabilities USERNAME ?STRING?

    Query or set the capabilities for user USERNAME

    fossil user default ?USERNAME?

    Query or set the default user.  The default user is the
    user for command-line interaction.

    fossil user list

    List all users known to the repository

    fossil user new ?USERNAME?

    Create a new user in the repository.  Users can never be
    deleted.  They can be denied all access but they must continue
    to exist in the database.

    fossil user password USERNAME

    Change the web access password for a user.

<hr><a href="#tof">ˆ</a>
    <a name="version">Usage: </a><a href="cmd_version.wiki">fossil version</a>
    Print the source code version number for the fossil executable.

<hr><a href="#tof">ˆ</a>
    <a name="wiki">Usage: </a><a href="cmd_wiki.wiki">fossil wiki</a> (export|create|commit|list) WikiName
    Run various subcommands to fetch wiki entries.

    fossil wiki export PAGENAME ?FILE?

    Sends the latest version of the PAGENAME wiki
    entry to the given file or standard output.

    fossil wiki commit PAGENAME ?FILE?

    Commit changes to a wiki page from FILE or from standard.

    fossil wiki create PAGENAME ?FILE?

    Create a new wiki page with initial content taken from
    FILE or from standard input.

    fossil wiki list

    Lists all wiki entries, one per line, ordered
    case-insentively by name.

    TODOs:

    fossil wiki export ?-u ARTIFACT? WikiName ?FILE?

    Outputs the selected version of WikiName.

    fossil wiki delete ?-m MESSAGE? WikiName

    The same as deleting a file entry, but i don't know if fossil
    supports a commit message for Wiki entries.

    fossil wiki ?-u? ?-d? ?-s=[|]? list

    Lists the artifact ID and/or Date of last change along with
    each entry name, delimited by the -s char.

    fossil wiki diff ?ARTIFACT? ?-f infile[=stdin]? EntryName

    Diffs the local copy of a page with a given version (defaulting
    to the head version).

  </pre></nowiki>

  <hr><a href="#tof">ˆ</a>

    <h3>Caveats</h3>
    This is not actually a reference, it's the start of a reference.
    There are wikilinks to uncreated pages for the commands.  This was
    created by running the fossil help for each command listed by running
    fossil help...  Duplicate commands are only listed once (I
    <i>think</i>).  There are several bits of <b>fossil</b> that are not addressed
    in the help for commands (special wiki directories, special users, etc.)
    so they are (currently) not addressed here.  Clarity and brevity may be
    sacrificed for expediency at the authors indiscretion.  All spelling and
    grammatical mistakes are somebody elses fault.<code>  void * </code>
    prohibited where<code> __C_PLUS_PLUS__ </code>. Title and taxes extra.
    Not valid in Hooptigonia.