Fossil

add new ticket changes artifacts have to be set close to reality.
It is OK for a ticket change artifact timestamp to be off by a few
minutes or even a few hours.  But if a timestamp on a ticket change
artifact is off by months or years, it can seriously confuse the
replay algorithm for determining the current ticket state.  There
are techniques available to cause rogue artifacts to be ignored
by fossil.  So if a ticket change artifact with a bad timestamp
does get into a repository, it can be removed by an administrator.
But the best approach is to take steps to insure that timestamps
are approximately correct in the first place.

<h2>Local Configuration</h2>

The ticket change artifacts are part of the global state for a project.
The global state is that which is shared between repositories during

names of columns in the TICKET table correspond to the names in
the name/value pairs of ticket change artifacts.  When running the replay
algorithm, if a name/value pair is seen which has no corresponding column
in the TICKET table, then that name/value pair is ignored.  Columns can
be added or removed from the TICKET table at any time.  Whenever the
TICKET table is modified, the replay algorithm automatically reruns
to repopulate the table using the new column names.  Note that the TICKET
table schema and content is part of the local state of a repository
and is not shared with other repositories during a sync, push, or pull.

Each repository also defines scripts used to generate web pages for
creating new tickets, viewing existing tickets, and modifying an
existing ticket.  These scripts consist of HTML with an embedded
scripts written an a Tcl-like language called "TH1".  Every new fossil
repository is created with default scripts.  There is currently no
documentation on the TH1 language.  Administrators wishing to
customize their ticket entry, viewing, and editing screens should
modify the default scripts to suit their needs.  These screen generator
scripts are part of the local state of a repository and are not shared
with other repositories during a sync, push, or pull.

<i>To be continued...</i>

<nowiki>
<h1>Installing Fossil</h1>

<p>This page describes how to build and install Fossil.  The
whole process is designed to be very easy.</p>

<h2>0.0 Using A Pre-compiled Binary</h2>

<p>You can skip steps 1.0 and 2.0 below by downloading
a <a href="http://www.fossil-scm.org/download.html">pre-compiled binary</a>
appropriate for your platform.  If you use a pre-compiled binary
jump immediate to step 3.0.</p>

<h2>1.0 Obtaining The Source Code</h2>

<p>Fossil is self-hosting, so you can obtain a ZIP archive containing
a snapshot of the latest version directly from fossil's own fossil
repository.  Follow these steps:</p>

<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>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 <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&#8212;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 <a href="wiki?name=fossil+ls"><code>ls</code></a> command.

See also: [fossil clean], [fossil ls], [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 <a href="doc/tip/www/concepts.wiki">Fossil concepts</a>.)
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 <a href="wiki?name=fossil+commit"><code>commit</code></a>.  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
<a href="wiki?name=fossil+extra"><code>extra</code> command</a>.

<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: [fossil add], [fossil rm], [fossil extra], [fossil commit], <a href="doc/tip/www/concepts.wiki">Fossil concepts</a>, [Reference]

which is a shortcut for doing both a push and a pull at the same time.
Fossil also has the concept of "cloning".  A "clone" is like a "pull",
except that instead of beginning with an existing local repository,
a clone begins with nothing and creates a new local repository that
is a duplicate of a remote repository.</p>

<p>Communication between repositories is via HTTP.  Remote
repositories are identified by URL.  You can also point a web browser
at a repository and get human-readable status, history, and tracking
information about the project.</p>

<h3>2.1 Identification Of Artifacts</h3>

<p>A particular version of a particular file is called an "artifact".
Each artifact has a universally unique name which is the
<a href="http://en.wikipedia.org/wiki/SHA">SHA1</a> hash of the content
of that file expressed as 40 characters of lower-case hexadecimal.  Such
a hash is referred to as the Artifact Identifier or Artifact ID
for the artifact.  The SHA1 algorithm is created with the purpose of
providing a highly forgery-resistant identifier for a file.  Given any
file it is simple to find the artifact ID for that file.  But given a
artifact ID it is computationally intractable to generate a file that will
have that Artifact ID.</p>


<p>Artifact IDs look something like this:</p>

</ul>

<h2>3.0 Fossil - The Program</h2>

<p>Fossil is software.  The implementation of fossil is in the form
of a single executable named "fossil".  To install fossil on your system,
all you have to do is obtain a copy of this one executable file (either
by downloading a pre-compiled version or compiling it yourself) and then
putting that file somewhere on your PATH.</p>

<p>Fossil is completely self-contained.  It is not necessary to
install any other software in order to use fossil.  You do <u>not</u> need
CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, apache, PostgreSQL, MySQL,
SQLite, patch, or any similar software on your system in order to use
fossil effectively.  You will want to have some kind of text editor

a server with fossil is ridiculously easy.  You have three options:</p>

<ol>
<li><p><b>Setting up a stand-alone server</b></p>

<p>From within your source tree just use the <b>server</b> command and
fossil will start listening for incoming requests on TCP port 8080.
You can point your web browser at <a href="http://localhost:8080/">
http://localhost:8080/</a> and begin exploring.  Or your coworkers
can do pushes or pulls against your server.  Use the <b>--port</b>
option to the server command to specify a different TCP port.  If
you do not have a local source tree, use the <b>-R</b> command-line
option to specify the repository file.</p>

<p>A stand-alone server is a great way to set of transient connections

<blockquote><pre>
#!/usr/local/bin/fossil
repository: /home/me/bigproject.fossil
</pre></blockquote>

<p>Edit this script to use whatever pathnames are appropriate for
your project.  Then point your web browser at the script and off you
go.</p></li>

<li><p><b>Setting up an inetd server</b></p>

<p>If you have inetd or xinetd running on your system, you can set
those services up to launch fossil to deal with inbound TCP/IP connections
on whatever port you want.  Set up inetd or xinetd to launch fossil

<li>The "original" is split into chunks of NHASH bytes. Note that a
partial chunk of less than NHASH bytes at the end of "original" is
ignored.
</li>
<li>The <a href="#rollhash">rolling hash</a> of each chunk is
computed.
</li>
<li>A hash table is filled, mapping from the hashes of the chunks to
the list of chunk locations having this hash.
</li>
</ol>

<a name="processing"></a><h3>2.1 Processing the target</h3>

<p>This, the main phase of the encoder, processes the target in a loop

</ul>
</p>

<img src="encode10.gif" align="right" hspace="10">
<p>To make this decision the encoder first computes the hash value for
the NHASH bytes in the window and then looks at all the locations in
the "origin" which have the same signature. This part uses the hash
table created by the pre-processing step to efficiently find these
locations.</p>

<p>For each of the possible candidates the encoder finds the maximal
range of bytes common to both "origin" and "target", going forward and
backward from "slide" in the "target", and the candidate location in
the "origin". This search is constrained on the side of the "target"
by the "base" (backward search), and the end of the "target" (forward

     a rollback journal) then it currently fails silently on a push.
     It needs to return a helpful error.
 
@@ -27,8 +27,8 @@
  *  Additional information displayed for the "vinfo" page:
 
      +  All leaves of this version that are not included in the
-        descendant list.  With date, user, comment, and hyperlink.
-        Leaves in the descendant table should be marked as such.
+        descendant list.  With date, user, comment, and hyperlink.
+        Leaves in the descendant table should be marked as such.
         See the compute_leaves() function to see how to find all
         leaves.
      +  Add file diff links to the file change list.
@@ -37,7 +37,7 @@
 

"<b>ckout</b>".  The "<b>tip</b>" keyword means to use the most recently
checked-in baseline.  This is useful if you want to see the very latest
version of the documentation.  The "<b>ckout</b>" keywords means to
pull the documentation file from the local source tree on disk, not
from the any versioned baseline.  The "<b>ckout</b>" keyword normally
only works when you start your server using the "<b>fossil server</b>"
or "<b>fossil ui</b>"
command line and is indented to show what the documentation you are currently
editing looks like before you check it in.

Finally, the <i>&lt;filename&gt;</i> element of the URL is the full
pathname of the documentation file starting from the root of the source
tree.

The mimetype (and thus the rendering) of documentation files is 

<i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i>
</blockquote>

<p>
A manifest has zero or more F-cards.  Each F-card defines a file
(other than the manifest itself) which is part of the baseline that
the manifest defines.  There are two, three, or three arguments.
The first argument
is the pathname of the file in the baseline relative to the root
of the project file hierarchy.  No ".." or "." directories are allowed
within the filename.  Space characters are escaped as in C-card
comment text.  Backslash characters and newlines are not allowed
within filenames.  The directory separator character is a forward
slash (ASCII 0x2F).  The second argument to the F-card is the
full 40-character lower-case hexadecimal SHA1 hash of the content

check-in comment argument to the C-card.
</p>

<p>
A manifest has an option Z-card as its last line.  The argument
to the Z-card is a 32-character lowercase hexadecimal MD5 hash
of all prior lines of the manifest up to and including the newline 
character that immediately precedes the "Z".  The Z-card is just
a sanity check to prove that the manifest is well-formed and
consistent.
</p>

<h2>2.0 Clusters</h2>

<p>
A cluster is a artifact that declares the existence of other artifacts.
Clusters are used during repository synchronization to help 
reduce network traffic.  As such, clusters are an optimization and
may be removed from a repository without loss or damage to the
underlying project code.
</p>

<p>
Clusters follow a syntax that is very similar to manifests.
A Cluster is a line-oriented text file.  Newline characters
(ASCII 0x0a) separate the artifact into cards.  Each card begins with a single
character "card type".  Zero or more arguments may follow
the card type.  All arguments are separated from each other
and from the card-type character by a single space
character.  There is no surplus white space between arguments
and no leading or trailing whitespace except for the newline 
character that acts as the card separator.
All cards of a cluster occur in strict sorted lexicographical order.
No card may be duplicated.
The cluster may not contain additional text or data beyond 
what is described here.
Unlike manifests, clusters are never PGP signed.
</p>

<p>

some other artifact.  The T card has two or three values.  The
second argument is the 40 character lowercase artifact ID of the artifact
to which the tag is to be applied. The
first value is the tag name.  The first character of the tag
is either "+", "-", or "*".  A "+" means the tag should be added
to the artifact.  The "-" means the tag should be removed.
The "*" character means the tag should be added to the artifact
and all direct descendants (but not branches) of the artifact down
to but not including the first descendant that contains a 
more recent "-" tag with the same name.
The optional third argument is the value of the tag.  A tag
without a value is a boolean.</p>

<p>When two or more tags with the same name are applied to the
same artifact, the tag with the latest (most recent) date is
used.</p>

programmer who entered this change.  The Z card is the checksum over
the entire artifact.</p>

<p>
Every ticket has a unique ID.  The ticket to which this change is applied
is specified by the K card.  A ticket exists if it contains one or
more changes.  The first "change" to a ticket is what brings the
ticket into existence.</p>

<p>
J cards specify changes to the "value" of "fields" in the ticket.
If the <i>value</i> parameter of the J card is omitted, then the
field is set to an empty string.
Each fossil server has a ticket configuration which specifies the fields its
understands.  The ticket configuration is part of the local state for
the repository and thus can vary from one repository to another.
Hence a J card might specify a <i>field</i> that do not exist in the 
local ticket configuration.  If a J card specifies a <i>field</i> that
is not in the local configuration, then that J card
is simply ignored.</p>

<p>
The first argument of the J card is the field name.  The second
value is the field value.  If the field name begins with "+" then
the value is appended to the prior value.  Otherwise, the value
on the J card replaces any previous value of the field.
The field name and value are both encoded using the character
escapes defined for the C card of a manifest.
</p>

<h1>Fossil: Distributed Revision Control, Wiki, and Bug-Tracking</h1>

<p>
Fossil is a
<a href="http://en.wikipedia.org/wiki/Revision_control">
distributed software revision control system</a> that includes an integrated
<a href="wikitheory.wiki">wiki</a> and an integrated
<a href="bugtheory.wiki">bug-tracking system</a> all in a single, 
easy-to-use, stand-alone executable.
Fossil is
<a href="http://www.fossil-scm.org/">self-hosting</a>
since 2007-07-21 on
<a href="http://www.hwaci.com/cgi-bin/fossil">two separate servers</a>.
You can download the <a href="../../../timeline">latest sources</a> and
<a href="build.wiki">compile it yourself</a>.
Or you can grab
<a href="http://www.fossil-scm.org/download.html">pre-compiled binaries</a>.
</p>

<p>Feature Summary:</p>

<ul>
<li>Flexible workflow:<ul>
    <li>Disconnected, distributed development like

<a href="quickstart.wiki#proxy">proxy support</a>
so that everything works from behind restrictive firewalls.</li>
<li>Everything (client, server, and utilities) is included in a 
single self-contained executable - trivial to install</li>
<li>Server runs as <a href="quickstart.wiki#cgiserver">CGI</a>, using
<a href="quickstart.wiki#inetdserver">inetd/xinetd</a>
or using its own 
<a href="quickstart.wiki#serversetup">built-in, stand alone web server</a>.</li>
<li>An entire project contained in single disk file
(an <a href="http://www.sqlite.org/">SQLite</a> database.)</li>
<li>Uses an <a href="fileformat.wiki">enduring file format</a> that is 
designed to be readable, searchable, and extensible by people not yet born.</li>
<li>Automatic <a href="selfcheck.wiki">self-check</a>
on repository changes makes it exceedingly
unlikely that data will ever be lost because of a software bug.</li>

<h2>Command Line Interface Reference</h2>

The <code>fossil</code> program supplies most of the actual
documentation about its options, so a good way to start documenting
the program is to nab the output of <code>fossil help <i>command</i></code>
for all of its (exposed) cli.

<i>This was suggested under the <b>Reference</b> heading in
[Documentation outline].

If you are trying to find information about fossil's web capabilities,
see the <a href="doc/tip/www/index.wiki">Fossil Home</a> and 
<a href="doc/tip/www/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.

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&#8212;the 'clone' command&#8212;unambiguous.

You should probably start interacting with fossil at the command line
by asking it what it can do:

<code>$ fossil help</code><nowiki><pre>
Usage: fossil help COMMAND.
Available COMMANDs:
add            configuration  leaves         redo           ui
all            deconstruct    ls             rename         undo
cgi            del            merge          revert         unset
changes        descendants    mv             rm             update
checkout       diff           new            server         user
ci             extra          open           settings       version
clean          gdiff          pull           status         wiki
clone          help           push           sync
close          http           rebuild        tag
commit         info           reconstruct    timeline
This is fossil version [c66ffba6da] 2008-11-10 19:54:53 UTC
</pre></nowiki>
<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 (not all of them are done) go into the command
in a bit more depth than the program help.
<nowiki><pre>

Usage: </nowiki><code>[fossil add]</code><nowiki> FILE...

Make arrangements to add one or more files to the current checkout 
at the next commit.


Usage: </nowiki><code>[fossil all]</code><nowiki> (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.
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


Usage: </nowiki>[fossil cgi]<nowiki> 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.


Usage: </nowiki>[fossil changes]<nowiki>

Report on the edit status of all files in the current checkout.
See also the "status" and "extra" commands.


Usage: </nowiki>[fossil checkout]<nowiki> 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.


Usage: </nowiki>[fossil commit]<nowiki> ?-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" options is used.  All files that have
changed will be committed unless some subset of files is specified
on the command line.


Usage: </nowiki>[fossil clean]<nowiki> ?-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.


Usage: </nowiki>[fossil clone]<nowiki> URL FILENAME

Make a clone of a repository specified by URL in the local
file named FILENAME.


Usage: </nowiki>[fossil close]<nowiki> ?-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.


Usage: </nowiki>[fossil configure]<nowiki> 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.


COMMAND: deconstruct 
Usage: </nowiki>[fossil deconstruct]<nowiki> ?-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.


Usage: </nowiki>[fossil rm]<nowiki> FILE...
   or: fossil del FILE...
Remove one or more files from the tree.


Usage: </nowiki>[fossil descendants]<nowiki> ?BASELINE-ID?

Find all leaf descendants of the baseline specified or if the argument
is omitted, of the baseline currently checked out.


Usage: </nowiki>[fossil diff]<nowiki>|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


Usage: </nowiki>[fossil extra]<nowiki>

Print a list of all files in the source tree that are not part of
the current checkout.  See also the "clean" command.


Usage: </nowiki>[fossil help]<nowiki> COMMAND

Display information on how to use COMMAND


Usage: </nowiki>[fossil http]<nowiki> 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.


Usage: </nowiki>[fossil info]<nowiki> ?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.


Usage: </nowiki>[fossil leaves]<nowiki>

Find leaves of all branches.


Usage: </nowiki>[fossil ls]<nowiki>

Show the names of all files in the current checkout


Usage: </nowiki>[fossil merge]<nowiki> 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.


Usage: </nowiki>[fossil new]<nowiki> 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.


Usage: </nowiki>[fossil open]<nowiki> 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.


Usage: </nowiki>[fossil pull]<nowiki> ?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.


Usage: </nowiki>[fossil push]<nowiki> ?URL? ?-R|--repository REPOSITORY?

Push changes in the local repository over into a remote repository.
See the "pull" command for additional information.

Usage: </nowiki>[fossil rebuild]<nowiki> 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.


COMMAND: reconstruct 
Usage: </nowiki>[fossil reconstruct]<nowiki> REPOSITORY ORIGIN

Creates the REPOSITORY and populates it with the artifacts in the
indicated ORIGIN directory.


Usage: </nowiki>[fossil redo]<nowiki> ?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.


Usage: </nowiki>[fossil revert]<nowiki> ?--yes? ?-r REVISION? FILE

Revert to the current repository version of FILE, or to
the version associated with baseline REVISION if the -r flag
appears.  This command will confirm your operation unless the
file is missing or the --yes option is used.


Usage: </nowiki>[fossil server]<nowiki> ?-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.


COMMAND: settings
COMMAND: unset
Usage: </nowiki>[fossil setting]<nowiki> ?PROPERTY? ?VALUE? ?-global?
       fossil unset PROPERTY ?-global?

The "setting" 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.

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

   proxy            URL of the HTTP proxy.  If undefined or "off" 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.


Usage: </nowiki>[fossil status]<nowiki>

Report on the status of the current checkout.


Usage: </nowiki>[fossil sync]<nowiki> ?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.


Usage: </nowiki>[fossil tag]<nowiki> SUBCOMMAND ...

Run various subcommands to control tags and properties

    fossil tag add ?--raw? TAGNAME BASELINE ?VALUE?

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

    fossil tag branch ?--raw? ?--nofork? TAGNAME BASELINE ?VALUE?

        A fork will be created so that the new checkin
        is a sibling of BASELINE 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 BASELINE will
        be cancelled.

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

    fossil tag cancel ?--raw? TAGNAME BASELINE

        Remove the tag TAGNAME from BASELINE, and also remove
        the propagation of the tag to any descendants.

    fossil tag find ?--raw? TAGNAME

        List all baselines that use TAGNAME

    fossil tag list ?--raw? ?BASELINE?

        List all tags, or if BASELINE is supplied, list
        all tags and their values for BASELINE.

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


Usage: </nowiki>[fossil timeline]<nowiki> ?WHEN? ?BASELINE|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 BASELINE 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.


Usage: </nowiki>[fossil undo]<nowiki> ?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.


Usage: </nowiki>[fossil update]<nowiki> ?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.


Usage: </nowiki>[fossil user]<nowiki> 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.


Usage: </nowiki>[fossil version]<nowiki>

Print the source code version number for the fossil executable.


Usage: </nowiki>[fossil wiki]<nowiki> (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>

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