Fossil

Glossary
Login

There are several terms-of-art in Fossil that have specific meanings which are either not immediately obvious to an outsider or which have technical associations that can lead someone to either use the terms incorrectly or to get the wrong idea from someone using those terms correctly. We hope to teach users how to properly “speak Fossil” with this glossary.

Each definition is followed by a bullet-point list of clarifying details. These are not part of the definition itself.

Project

A collection of one or more computer files that serve some conceptually unified purpose, which purpose changes and evolves over time, with the history of that project being a valuable record.

Repository

A single file that contains all historical versions of all files in a project, which can be cloned to other machines and synchronized with them. Jargon: repo.

~/museum/ where one stores valuable fossils work/ projects from $DAYJOB home/ personal at-home projects other/ clones of Fossil itself, SQLite, etc.
scale=0.8
box "~/museum/" fit
move right 0.1
line right dotted
move right 0.05
box invis "where one stores valuable fossils" ljust

arrow down 50% from first box.s then right 50%
box "work/" fit
move right 0.1
line dotted
move right 0.05
box invis "projects from $DAYJOB" ljust

arrow down 50% from 2nd vertex of previous arrow then right 50%
box "home/" fit
move right 0.1
line dotted right until even with previous line.end
move right 0.05
box invis "personal at-home projects" ljust

arrow down 50% from 2nd vertex of previous arrow then right 50%
box "other/" fit
move right 0.1
line dotted right until even with previous line.end
move right 0.05
box invis "clones of Fossil itself, SQLite, etc." ljust

Version / Revision / Hash / UUID

These terms all mean the same thing: a long hexadecimal SHA hash value that uniquely identifies a particular check-in.

We’ve listed the alternatives in decreasing preference order:

You will find all of these synonyms used in the Fossil documentation. Some day we may settle on a single term, but it doesn’t seem likely.

Check-in

A version of the project’s files that have been committed to the repository; as such, it is sometimes called a “commit” instead. A check-in is a snapshot of the project at an instant in time, as seen from a single check-out’s perspective. It is sometimes styled “CHECKIN”, especially in command documentation where any valid check-in name can be used.

Check-out

A set of files extracted from a repository that represent a particular check-in of the project.

Embedded Documentation

Serving as an alternative to Fossil’s built-in wiki, the embedded documentation feature stores the same type of marked-up text files, but under Fossil’s powerful version control features.

Capability

Fossil includes a powerful role-based access control system which affects which users have permission to do certain things within a given repository. You can read more about this complex topic here.

Some people — and indeed certain parts of Fossil’s own code — use the term “permissions” instead, but since operating system file permissions also play into this, we prefer the term “capabilities” (or “caps” for short) when talking about Fossil’s RBAC system to avoid a confusion here.


  1. ^ A pre-Fossil 2.0 style SHA1 hash is 160 bits, not the 128 bits many people expect for a proper UUID, and even if you truncate it to 128 bits to create a “good enough” version prefix, the 6 bits reserved in the UUID format for the variant code cannot make a correct declaration except by a random 1:64 chance. The SHA3-256 option allowed in Fossil 2.0 and higher doesn’t help with this confusion, making a Fossil version hash twice as large as a proper UUID. Alas, the term will never be fully obliterated from use since there are columns in the Fossil repository format that use the obsolete term; we cannot change this without breaking backwards compatibility.
  2. ^ You may sometimes see the term “snapshot” used as a synonym for a check-in or the version number identifying said check-in. We must warn against this usage because there is a potential confusion here: the stash command uses the term “snapshot,” as does the undo system to make a distinction with check-ins. Nevertheless, there is a conceptual overlap here between Fossil and systems that do use the term “snapshot,” the primary distinction being that Fossil will capture only changes to files you’ve added to the repository, not to everything in the check-out directory at the time of the snapshot. (Thus the extras command.) Contrast a snapshot taken by a virtual machine system or a snapshotting file system, which captures changes to everything on the managed storage volume.