Fossil

was created by making edits to check-in 1 and then committing those edits.
We say that 2 is a <i>child</i> of 1
and that 1 is a <i>parent</i> of 2.  
Check-in 3 is derived from check-in 2, making
3 a child of 2.  We say that 3 is a <i>descendant</i> of both 1 and 2 and that 1
and 2 are both <i>ancestors</i> of 3.  







We call the graph of check-ins a <i>tree</i>.  Check-in 1 is the <i>root</i>
since it has no ancestors.  Check-in 4 is a <i>leaf</i> of the tree since
it has no descendants.  (We will give a more precise in the definition of
"leaf" later.)

Alas, reality often interferes with the simple linear development of a
project.  Suppose two programmers make independent modifications to check-in 2.
After both changes are checked in, we have a check-in graph that looks 
like figure 2:
................................................................................
tried to commit his changes, fossil would try to verify that check-in 2
was still a leaf.  Fossil would see that check-in 3 had occurred and would
abort Bob's commit attempt with a message "would fork".  This allows Bob
to do a "fossil update" which would pull in Alice's changes and merge them
together with his own changes.  After merging, Bob could then commit
check-in 4 as a child of check-in 3 and the result would be a linear graph
as shown in figure 1.  This is how CVS works.  This is also how fossil
works in "autosync" mode.

But it might be that Bob is off-network when he does his commit, so he
has no way of knowing that Alice has already committed her changes.
Or, it could be that Bob has turned off "autosync" mode in Fossil.  Or,
maybe Bob just doesn't want to merge in Alice's changes before he has
saved his own, so he forces the commit to occur using the "--force" option
to the fossil <b>commit</b> command.  For whatever reason, two commits against
check-in 2 have occurred and now the tree has two leaves.

So which version of the project is the "latest" in the sense of having
the most features and the most bug fixes?  When there is more than
one leaf in the graph, you don't really know.  So we like to have
graphs with a single leaf.

To resolve this situation, Alice can use the fossil <b>merge</b> command
to merge in Bob's changes in her local copy of check-in 3.  Then she
can commit the results as check-in 5.  This results in a tree as shown
in figure 3.

<center><table border=1 cellpadding=10 hspace=10 vspace=10>
<tr><td align="center">
<img src="branch03.gif" width=282 height=152><br>
Figure 3
</td></tr></table></center>
................................................................................
taken in figure 1 is better because it is much easier to visualize a
linear line of development and because the merging happens automatically
instead of as a separate manual step.  We will not take sides in that
debate.  We will simply point out that fossil enables you to do it either way.

<h2>Forking Versus Branching</h2>

Having more than one leaf in the check-in tree is usually
considered undesirable, and so forks are usually either avoided entirely,
as in figure 1, or else quickly resolved as shown in figure 3.
But sometimes, one does want to have multiple leaves.  For example, a project
might have one leaf that is the latest version of the project under
development and another leaf that is the latest version that has been
tested.
When multiple leaves are desirable, we call the phenomenon <i>branching</i>
................................................................................

Here is a list of definitions of key terms:


<blockquote><dl>
<dt><b>Branch</b></dt>
<dd><p>A branch is a set of check-ins that have the same value for their
branch property.</p></dd>
<dt><b>Leaf</b></dt>
<dd><p>A leaf is a check-in that has no children in the same branch.</p></dd>
<dt><b>Closed Leaf</b></dt>
<dd><p>A closed leaf is leaf that has the <b>closed</b> tag.  Such leaves
are intented to never be extended with descendants and hence are omitted
from lists of leaves in the command-line and web interface.</p></dd>
<dt><b>Open Leaf</b></dt>
................................................................................
but that child is in a different branch, so check-in 9 is a leaf.  Because
of the <b>closed</b> tag check-in 9, it is a closed leaf.

Check-in 2 of figure 3 is considered a "fork"
because it has two children in the same branch.  Check-in 2 of figure 5
also has two children, but each child is in a different branch, hence in
figure 5, check-in 2 is considered a "branch point".

was created by making edits to check-in 1 and then committing those edits.
We say that 2 is a <i>child</i> of 1
and that 1 is a <i>parent</i> of 2.  
Check-in 3 is derived from check-in 2, making
3 a child of 2.  We say that 3 is a <i>descendant</i> of both 1 and 2 and that 1
and 2 are both <i>ancestors</i> of 3.  

<a name="dag"></a>
<h2>DAGs</h2>

The graph of check-ins is a 
[http://en.wikipedia.org/wiki/Directed_acyclic_graph | directed acyclic graph]
and so we will
henceforth call it a <i>DAG</i>.  Check-in 1 is the <i>root</i> of the DAG
since it has no ancestors.  Check-in 4 is a <i>leaf</i> of the DAG since
it has no descendants.  (We will give a more precise in the definition of
"leaf" later.)

Alas, reality often interferes with the simple linear development of a
project.  Suppose two programmers make independent modifications to check-in 2.
After both changes are checked in, we have a check-in graph that looks 
like figure 2:
................................................................................
tried to commit his changes, fossil would try to verify that check-in 2
was still a leaf.  Fossil would see that check-in 3 had occurred and would
abort Bob's commit attempt with a message "would fork".  This allows Bob
to do a "fossil update" which would pull in Alice's changes and merge them
together with his own changes.  After merging, Bob could then commit
check-in 4 as a child of check-in 3 and the result would be a linear graph
as shown in figure 1.  This is how CVS works.  This is also how fossil
works in [concepts.wiki#workflow | "autosync"] mode.

But it might be that Bob is off-network when he does his commit, so he
has no way of knowing that Alice has already committed her changes.
Or, it could be that Bob has turned off "autosync" mode in Fossil.  Or,
maybe Bob just doesn't want to merge in Alice's changes before he has
saved his own, so he forces the commit to occur using the "--force" option
to the fossil <b>commit</b> command.  For whatever reason, two commits against
check-in 2 have occurred and now the DAG has two leaves.

So which version of the project is the "latest" in the sense of having
the most features and the most bug fixes?  When there is more than
one leaf in the graph, you don't really know.  So we like to have
graphs with a single leaf.

To resolve this situation, Alice can use the fossil <b>merge</b> command
to merge in Bob's changes in her local copy of check-in 3.  Then she
can commit the results as check-in 5.  This results in a DAG as shown
in figure 3.

<center><table border=1 cellpadding=10 hspace=10 vspace=10>
<tr><td align="center">
<img src="branch03.gif" width=282 height=152><br>
Figure 3
</td></tr></table></center>
................................................................................
taken in figure 1 is better because it is much easier to visualize a
linear line of development and because the merging happens automatically
instead of as a separate manual step.  We will not take sides in that
debate.  We will simply point out that fossil enables you to do it either way.

<h2>Forking Versus Branching</h2>

Having more than one leaf in the check-in DAG is usually
considered undesirable, and so forks are usually either avoided entirely,
as in figure 1, or else quickly resolved as shown in figure 3.
But sometimes, one does want to have multiple leaves.  For example, a project
might have one leaf that is the latest version of the project under
development and another leaf that is the latest version that has been
tested.
When multiple leaves are desirable, we call the phenomenon <i>branching</i>
................................................................................

Here is a list of definitions of key terms:


<blockquote><dl>
<dt><b>Branch</b></dt>
<dd><p>A branch is a set of check-ins that have the same value for their
"branch" property.</p></dd>
<dt><b>Leaf</b></dt>
<dd><p>A leaf is a check-in that has no children in the same branch.</p></dd>
<dt><b>Closed Leaf</b></dt>
<dd><p>A closed leaf is leaf that has the <b>closed</b> tag.  Such leaves
are intented to never be extended with descendants and hence are omitted
from lists of leaves in the command-line and web interface.</p></dd>
<dt><b>Open Leaf</b></dt>
................................................................................
but that child is in a different branch, so check-in 9 is a leaf.  Because
of the <b>closed</b> tag check-in 9, it is a closed leaf.

Check-in 2 of figure 3 is considered a "fork"
because it has two children in the same branch.  Check-in 2 of figure 5
also has two children, but each child is in a different branch, hence in
figure 5, check-in 2 is considered a "branch point".

<h2>Differences With Other DVCSes</h2>

Fossil keeps all check-ins on a single DAG.  Branches are identified with
tags.  This means that check-ins can be freely moved between branches
simply by altering the tags.

Most other DVCSes maintain a separate DAG for each branch.

lowercase hexadecimal number.  For example:

<blockquote><pre>
fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9
</pre></blockquote>

The full 40-character SHA1 hash is unwieldy to remember and type, though,
os Fossil also accepts a unique prefix of the hash, using any combination
of upper and lower case letters, as long as the prefix is at least 4
characters long.  Hence the following commands all 
accomplish the same thing as the above:

<blockquote><pre>
fossil info e5a734a19a9
fossil info E5a734A
................................................................................
also resolves branch names.

Note also that there can (in theory) be an ambiguity between tag names
and canonical names.  Suppose, for example, you had a check-in with
the canonical name deed28aa99a835f01fa06d5b4a41ecc2121bf419 and you
also happened to have tagged a different check-in with "deed2".  If
you use the "deed2" name, does it choose the canonical name or the tag
name?  In such cases, you can prefix the tag name with "tag:".  Hence


<blockquote>
fossil info tag:deed2
</blockquote>


Will refer to the most recent check-in tagged with "deed2" not to the
check-in whose canonical name begins with "deed2".

<h2>Timestamps</h2>

A timestamp in one of the formats shown below means the most recent
check-in that occurs no later than the timestamp given:

  *   <i>YYYY-MM-DD</i>
  *   <i>YYYY-MM-DD HH:MM</i>
  *   <i>YYYY-MM-DD HH:MM:SS</i>

The space between the day and the year can optionally be 
replaced by an uppercase <b>T</b> and the entire timestamp can
optinally be followed by "<b>utc</b>".

In its default configuration, Fossil interprets and displays all dates
in Universal Coordinated Time (UTC).  This tends to work the best for
distributed projects where participants are scattered around the globe.
But there is an open on the Admin/Timeline page of the web-interface to
switch to local time.  The "<b>utc</b>" suffix on an timestamp check-in
name is meaningless if Fossil is in the default mode of using UTC for

lowercase hexadecimal number.  For example:

<blockquote><pre>
fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9
</pre></blockquote>

The full 40-character SHA1 hash is unwieldy to remember and type, though,
so Fossil also accepts a unique prefix of the hash, using any combination
of upper and lower case letters, as long as the prefix is at least 4
characters long.  Hence the following commands all 
accomplish the same thing as the above:

<blockquote><pre>
fossil info e5a734a19a9
fossil info E5a734A
................................................................................
also resolves branch names.

Note also that there can (in theory) be an ambiguity between tag names
and canonical names.  Suppose, for example, you had a check-in with
the canonical name deed28aa99a835f01fa06d5b4a41ecc2121bf419 and you
also happened to have tagged a different check-in with "deed2".  If
you use the "deed2" name, does it choose the canonical name or the tag
name?  In such cases, you can prefix the tag name with "tag:".
For example:

<blockquote><tt>
fossil info tag:deed2
</tt></blockquote>

The "tag:deed2" name will refer to the most recent check-in 
tagged with "deed2" not to the
check-in whose canonical name begins with "deed2".

<h2>Timestamps</h2>

A timestamp in one of the formats shown below means the most recent
check-in that occurs no later than the timestamp given:

  *   <i>YYYY-MM-DD</i>
  *   <i>YYYY-MM-DD HH:MM</i>
  *   <i>YYYY-MM-DD HH:MM:SS</i>

The space between the day and the year can optionally be 
replaced by an uppercase <b>T</b> and the entire timestamp can
optionally be followed by "<b>utc</b>".

In its default configuration, Fossil interprets and displays all dates
in Universal Coordinated Time (UTC).  This tends to work the best for
distributed projects where participants are scattered around the globe.
But there is an open on the Admin/Timeline page of the web-interface to
switch to local time.  The "<b>utc</b>" suffix on an timestamp check-in
name is meaningless if Fossil is in the default mode of using UTC for

<tr><td>Sharding</td><td>Replicating</td></tr>
<tr><td>Huge community</td><td>Road less traveled</td></tr>
<tr><td>Complex</td><td>Intuitive</td></tr>
<tr><td>Separate web tools</td><td>Integrated Web interface</td></tr>
<tr><td>Lots of little tools</td><td>Single executable</td></tr>
<tr><td>Pile-of-files repository</td><td>Single file repository</td></tr>
<tr><td>Uses "<tt>rebase</tt>"</td><td>Immutable</td></tr>


<tr><td>GPL</td><td>BSD</td></tr>
</table></center></blockquote>

<h2>3.0 Discussion</h2>

<h3>3.1 Feature Set</h3>

................................................................................
to understand.  From another point of view, rebase can be used to
"rewrite history" - to do what
[http://en.wikipedia.org/wiki/Winston_Smith | Winston Smith] did for
a living in Orwell's novel
[http://en.wikipedia.org/wiki/Nineteen_Eighty-Four | 1984].

Fossil deliberately avoids rewriting history.  Fossil strives to follow
the accounting philosophy of never erasing anything.  Mistakes are fixed
by entering a correction, with an explanation of why the correction is
needed.  This can make the history of a project messy, but it also
makes it more honest.  The lack of a "rebase" function is considered
a feature of Fossil, not a bug.









<h3>3.9 License</h3>

Both Git and Fossil are open-source.  Git is under 
[http://www.gnu.org/licenses/gpl.html | GPL] whereas Fossil is
under the 
[http://en.wikipedia.org/wiki/BSD_licenses | two-clause BSD license].
The difference should not be of a concern to most users.  However,
some corporate lawyers have objections to using GPL products and
are more comfortable with a BSD-style license.

<tr><td>Sharding</td><td>Replicating</td></tr>
<tr><td>Huge community</td><td>Road less traveled</td></tr>
<tr><td>Complex</td><td>Intuitive</td></tr>
<tr><td>Separate web tools</td><td>Integrated Web interface</td></tr>
<tr><td>Lots of little tools</td><td>Single executable</td></tr>
<tr><td>Pile-of-files repository</td><td>Single file repository</td></tr>
<tr><td>Uses "<tt>rebase</tt>"</td><td>Immutable</td></tr>
<tr><td>Multiple [./branching.wiki#dag | DAGs]; one per branch</td>
    <td>All branches on one [./branching.wiki#dag | DAG]</td></tr>
<tr><td>GPL</td><td>BSD</td></tr>
</table></center></blockquote>

<h2>3.0 Discussion</h2>

<h3>3.1 Feature Set</h3>

................................................................................
to understand.  From another point of view, rebase can be used to
"rewrite history" - to do what
[http://en.wikipedia.org/wiki/Winston_Smith | Winston Smith] did for
a living in Orwell's novel
[http://en.wikipedia.org/wiki/Nineteen_Eighty-Four | 1984].

Fossil deliberately avoids rewriting history.  Fossil strives to follow
the accountants philosophy of never erasing anything.  Mistakes are fixed
by entering a correction, with an explanation of why the correction is
needed.  This can make the history of a project messy, but it also
makes it more honest.  The lack of a "rebase" function is considered
a feature of Fossil, not a bug.

<h3>3.9 Single DAG</h3>

Git maintains a separate directed acyclic graph (DAG) for each branch
of a repository.  Fossil maintains a single DAG for all branches.  In
Git, the branch that a specific check-in belongs to is determined by
which DAG it is part of.  In Fossil, the branch of a check-in is determined
by [./branching.wiki#tags | tags and properties] attached to the check-in.

<h3>3.10 License</h3>

Both Git and Fossil are open-source.  Git is under 
[http://www.gnu.org/licenses/gpl.html | GPL] whereas Fossil is
under the 
[http://en.wikipedia.org/wiki/BSD_licenses | two-clause BSD license].
The difference should not be of a concern to most users.  However,
some corporate lawyers have objections to using GPL products and
are more comfortable with a BSD-style license.

      integrated package.

  2.  <b>Web Interface</b> - 
      Fossil has a built-in and easy-to-use [./webui.wiki | web interface]
      that simplifies project tracking and promotes situational awareness.
      Simply type "fossil&nbsp;ui" from within any check-out and Fossil
      automatically opens your web browser in a page that gives detailed

      history and status information on that project.

  3.  <b>Autosync</b> -
      Fossil supports [./concepts.wiki#workflow | "autosync" mode]
      which helps to keep projects moving
      forward by reducing the amount of needless 
      [./branching.wiki | forking and merging] often
      associated with distributed projects.

      integrated package.

  2.  <b>Web Interface</b> - 
      Fossil has a built-in and easy-to-use [./webui.wiki | web interface]
      that simplifies project tracking and promotes situational awareness.
      Simply type "fossil&nbsp;ui" from within any check-out and Fossil
      automatically opens your web browser in a page that gives detailed
      [/timeline?n=100&y=ci | graphical history] and status information
      on that project.

  3.  <b>Autosync</b> -
      Fossil supports [./concepts.wiki#workflow | "autosync" mode]
      which helps to keep projects moving
      forward by reducing the amount of needless 
      [./branching.wiki | forking and merging] often
      associated with distributed projects.

    can type commands like the following to find out the status of
    your local tree:</p>

    <blockquote>
    <b>fossil info</b><br>
    <b>fossil status</b><br>
    <b>fossil changes</b><br>

    <b>fossil timeline</b><br>
    <b>fossil leaves</b><br>
    <b>fossil ls</b><br>
    <b>fossil branch list</b><br>
    </blockquote>

</blockquote><h2>Configuring Your Local Repository</h2><blockquote>
    
    <p>When you create a new repository, either by cloning an existing
................................................................................
    local configuration.  This is easily accomplished using the webserver
    that is built into fossil.  Start the fossil webserver like this:</p>
    
    <blockquote>
    <b>fossil ui </b><i> repository-filename</i>
    </blockquote>

    <p>(Note that this requires you to have checked out a local tree
    beforehand.)</p>

    <p>This starts a web server then automatically launches your
    web browser and makes it point to this web server.  If your system
    has an unusual configuration, fossil might not be able to figure out
    how to start your web browser.  In that case, first tell fossil
    where to find your web browser using a command like this:</p>

................................................................................
    your changes, type:</p>

    <blockquote>
    <b>fossil commit</b>
    </blockquote>

    <p>You will be prompted for check-in comments using whatever editor
    is specified by your VISUAL or EDITOR environment variable.  If you
    have GPG installed, you may be prompted for your GPG passphrase so
    that the check-in can be signed with your GPG signature.  After
    this your changes will be checked in.</p>

</blockquote><h2>Sharing Changes</h2><blockquote>

    <p>The changes you <b>commit</b> are only on your local repository.
    To share those changes with other repositories, do:</p>

    <blockquote>
................................................................................
    </blockquote>

    <p>When you pull in changes from others, they go into your repository,
    not into your checked-out local tree.  To get the changes into your
    local tree, use <b>update</b>:</p>

    <blockquote>
    <b>fossil update</b> <i>AID</i>
    </blockquote>


    <p>The <i>AID</i> is some unique abbreviation to the 40-character
    artifact identifier (AID) for a particular check-in.  If you omit


    the <i>AID</i> fossil moves you to the
    leaf version of the branch your are currently on.  If your branch
    has multiple leaves, you get an error - you'll have to specify the
    leaf you want using a <i>AID</i> argument.</p>

</blockquote><h2>Branching And Merging</h2><blockquote>

    <p>You can create branches by doing multiple commits off of the
    same base version.  To merge to branches back together, first
    <b>update</b> to the leaf of one branch.  Then do a <b>merge</b>
    of the leaf of the other branch:</p>

    <blockquote>
    <b>fossil merge</b> <i>AID</i>
    </blockquote>

    <p>Test to make sure your merge didn't mess up the code, then
    <b>commit</b> and possibly also <b>push</b> your changes.   Remember
    that nobody else can see your changes until you <b>commit</b> and
    if other are using a different repository you will also need to
    <b>push</b>.</p>






















<a name="serversetup"></a>
</blockquote><h2>Setting Up A Server</h2><blockquote>

    <p>The easiest way to set up a server is:</p>

    <blockquote>

    can type commands like the following to find out the status of
    your local tree:</p>

    <blockquote>
    <b>fossil info</b><br>
    <b>fossil status</b><br>
    <b>fossil changes</b><br>
    <b>fossil diff</b><br>
    <b>fossil timeline</b><br>

    <b>fossil ls</b><br>
    <b>fossil branch list</b><br>
    </blockquote>

</blockquote><h2>Configuring Your Local Repository</h2><blockquote>
    
    <p>When you create a new repository, either by cloning an existing
................................................................................
    local configuration.  This is easily accomplished using the webserver
    that is built into fossil.  Start the fossil webserver like this:</p>
    
    <blockquote>
    <b>fossil ui </b><i> repository-filename</i>
    </blockquote>

    <p>You can omit the <i>repository-filename</i> from the command above
    if you are inside a checked-out local tree.</p>

    <p>This starts a web server then automatically launches your
    web browser and makes it point to this web server.  If your system
    has an unusual configuration, fossil might not be able to figure out
    how to start your web browser.  In that case, first tell fossil
    where to find your web browser using a command like this:</p>

................................................................................
    your changes, type:</p>

    <blockquote>
    <b>fossil commit</b>
    </blockquote>

    <p>You will be prompted for check-in comments using whatever editor
    is specified by your VISUAL or EDITOR environment variable.</p>




</blockquote><h2>Sharing Changes</h2><blockquote>

    <p>The changes you <b>commit</b> are only on your local repository.
    To share those changes with other repositories, do:</p>

    <blockquote>
................................................................................
    </blockquote>

    <p>When you pull in changes from others, they go into your repository,
    not into your checked-out local tree.  To get the changes into your
    local tree, use <b>update</b>:</p>

    <blockquote>
    <b>fossil update</b> <i>VERSION</i>
    </blockquote>

    <p>The <i>VERSION</i> can be the name of a branch or tag or any
    abbreviation to the 40-character
    artifact identifier for a particular check-in, or it can be a
    date/time stamp.  (<a href="./checkin_names.wiki">More information</a>.)
    If you omit
    the <i>VERSION</i>, then fossil moves you to the
    latest version of the branch your are currently on.</p>



</blockquote><h2>Branching And Merging</h2><blockquote>

    <p>You can create branches by doing multiple commits off of the
    same base version.  To merge to branches back together, first
    <b>update</b> to the leaf of one branch.  Then do a <b>merge</b>
    of the leaf of the other branch:</p>

    <blockquote>
    <b>fossil merge</b> <i>VERSION</i>
    </blockquote>

    <p>The <i>VERSION</i> can be any of the forms allowed for <b>update</b>.
    After performing the merge, you will normally want to test it to
    make sure it does not break anything, then
    <b>commit</b> your chagnes.  In the default configuration, the <b>commit</b>
    command will also automatically <b>push</b> your changes, but that
    feature can be disabled.  (More information about 
    <a href="concepts.wiki#workflow">autosync</a> and how to disable it.)
    Remember that your coworkers can not see your changes until you 
    <b>commit</b> and <b>push</b> them.</p>

    <p>The merge command has options to cherrypick individual
    changes, or to back out individual changes.</p>

    <p>If a merge or update doesn't work out (perhaps something breaks or
    there are many merge conflicts) then you back up using:</p>

    <blockquote>
    <b>fossil undo</b>
    </blockquote>

    <p>This will back out the changes that the merge or update made to the
    working checkout.  There is also a <b>redo</b> command if you undo by
    mistake.  Undo and redo only work for changes that have
    not yet been checked in using <b>commit</b> and there is only a single
    level of undo/redo.</p>


<a name="serversetup"></a>
</blockquote><h2>Setting Up A Server</h2><blockquote>

    <p>The easiest way to set up a server is:</p>

    <blockquote>