Fossil

different in separate repositories.
The local state is not versioned and is not synchronized
with the global state.
The local state is not composed of artifacts and is not intended to be enduring.
This document is concerned with global state only.  Local state is only
mentioned here in order to distinguish it from global state.

<a id="names"></a>
<h2>1.0 Artifact Names</h2>

Each artifact in the repository is named by a hash of its content.
No prefixes, suffixes, or other information is added to an artifact before
the hash is computed.  The artifact name is just the (lower-case
hexadecimal) hash of the raw artifact.

Fossil currently computes artifact names using either SHA1 or SHA3-256.  It
is relatively easy to add new algorithms in the future, but there are no
plans to do so at this time.

When referring to artifacts in using tty commands or webpage URLs, it is
sufficient to specify a unique prefix for the artifact name.  If the input
prefix is not unique, Fossil will show an error.  Within a structural
artifact, however, all references to other artifacts must be the complete
hash.

Prior to Fossil version 2.0, all names were formed from the SHA1 hash of
the artifact.  The key innovation in Fossil 2.0 was adding support for
alternative hash algorithms.

<a id="structural"></a>
<h2>2.0 Structural Artifacts</h2>

A structural artifact is an artifact with a particular format
that is used to define the relationships between other artifacts in the
repository.
Fossil recognizes the following kinds of structural
artifacts:

is an implementation detail and might change in a future release.  For
the purpose of this article "file format" means the format of the artifacts,
not how the artifacts are stored on disk.  It is the artifact format that
is intended to be enduring.  The specifics of how artifacts are stored on
disk, though stable, is not intended to live as long as the
artifact format.

<a id="manifest"></a>
<h3>2.1 The Manifest</h3>

A manifest defines a check-in.
A manifest contains a list of artifacts for
each file in the project and the corresponding filenames, as
well as information such as parent check-ins, the username of the
programmer who created the check-in, the date and time when
the check-in was created, and any check-in comments associated

clear-signing prefix.  The <b>Z</b> card is
a sanity check to prove that the manifest is well-formed and
consistent.

A sample manifest from Fossil itself can be seen
[/artifact/28987096ac | here].

<a id="cluster"></a>
<h3>2.2 Clusters</h3>

A cluster is an 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.

the <b>Z</b> card of a manifest.  The argument to the <b>Z</b> card is the
lower-case hexadecimal representation of the MD5 checksum of all
prior cards in the cluster.  The <b>Z</b> card is required.

An example cluster from Fossil can be seen
[/artifact/d03dbdd73a2a8 | here].

<a id="ctrl"></a>
<h3>2.3 Control Artifacts</h3>

Control artifacts are used to assign properties to other artifacts
within the repository.
Allowed cards in a control artifact are as follows:

<blockquote>
<b>D</b> <i>time-and-date-stamp</i><br />

The <b>U</b> card is the name of the user that created the control
artifact.  The <b>Z</b> card is the usual required artifact checksum.

An example control artifact can be seen [/info/9d302ccda8 | here].


<a id="wikichng"></a>
<h3>2.4 Wiki Pages</h3>

A wiki artifact defines a single version of a
single wiki page.
Wiki artifacts accept
the following card types:

<blockquote>

of user George Krivov and is not currently used or generated by the 
implementation. Older versions of Fossil will reject a wiki-page
artifact that includes a <b>C</b> card.

An example wiki artifact can be seen
[/artifact?name=7b2f5fd0e0&txt=1 | here].

<a id="tktchng"></a>
<h3>2.5 Ticket Changes</h3>

A ticket-change artifact represents a change to a trouble ticket.
The following cards are allowed on a ticket change artifact:

<blockquote>
<b>D</b> <i>time-and-date-stamp</i><br />
<b>J</b> ?<b>+</b>?<i>name</i> ?<i>value</i>?<br />

on the <b>J</b> card replaces any previous value of the field.
The field name and value are both encoded using the character
escapes defined for the <b>C</b> card of a manifest.

An example ticket-change artifact can be seen
[/artifact/91f1ec6af053 | here].

<a id="attachment"></a>
<h3>2.6 Attachments</h3>

An attachment artifact associates some other artifact that is the
attachment (the source artifact) with a ticket or wiki page or
technical note to which
the attachment is connected (the target artifact).
The following cards are allowed on an attachment artifact:

A single <b>U</b> card gives the name of the user who added the attachment.
If an attachment is added anonymously, then the <b>U</b> card may be omitted.

The <b>Z</b> card is the usual checksum over the rest of the attachment artifact.
The <b>Z</b> card is required.


<a id="event"></a>
<h3>2.7 Technical Notes</h3>

A technical note or "technote" artifact (formerly known as an "event" artifact)
associates a timeline comment and a page of text
(similar to a wiki page) with a point in time.  Technotes can be used
to record project milestones, release notes, blog entries, process
checkpoints, or news articles.
The following cards are allowed on an technote artifact:

A single <b>W</b> card provides wiki text for the document associated with the
technote.  The format of the <b>W</b> card is exactly the same as for a
[#wikichng | wiki artifact].

The <b>Z</b> card is the required checksum over the rest of the artifact.

<a id="forum"></a>
<h3>2.8 Forum Posts</h3>

Forum posts are intended as a mechanism for users and developers to
discuss a project.  Forum posts are like messages on a mailing list.

The following cards are allowed on an forum post artifact:

<blockquote>

A single <b>W</b> card provides wiki text for the forum post.
The format of the <b>W</b> card is exactly the same as for a
[#wikichng | wiki artifact].

The <b>Z</b> card is the required checksum over the rest of the artifact.


<a id="summary"></a>
<h2>3.0 Card Summary</h2>

The following table summarizes the various kinds of cards that appear
on Fossil artifacts. A blank entry means that combination of card and
artifact is not legal. A number or range of numbers indicates the number
of times a card may (or must) appear in the corresponding artifact type.
e.g. a value of 1 indicates a required unique card and 1+ indicates that one
or more such cards are required.

4) [#forum | Forum Posts] must have either one H-card or one
   I-card, not both.

5) [#forum | Forum Post] P-cards may have only a single parent
   hash. i.e. they may not have merge parents.

<a id="addenda"></a>
<h2>4.0 Addenda</h2>

This section contains additional information which may be useful when
implementing algorithms described above.

<a id="outofordercards"></a>
<h3>4.1 Relaxed Card Ordering Due To An Historical Bug</h3>

All cards of a structural artifact should be in lexicographical order.
The Fossil implementation verifies this and rejects any structural
artifact which has out-of-order cards.  Futhermore, when Fossil is
generating new structural artifacts, it runs the generated artifact
through the parser to confirm that all cards really are in the correct
order before committing the transaction.  In this way, Fossil prevents