The protocol below extends Fossil 2.27. This is what it relies on. You can
try any of it with the fossil program in /work.
- Repository: one SQLite database file holding a project's whole
history: check-ins, forum threads, tickets, wiki pages, tags and logins.
fossil new FILEmakes one;fossil sql -R FILEqueries it. - Clone: a repository made from another with
fossil clone. Clones of one project share its project code and exchange artifacts withfossil push,pullandsync. Each repository has a server-code of its own, 40 random hex digits:fossil sql "SELECT value FROM config WHERE name='server-code'". - Artifact: each item Fossil stores (a check-in, a file, a forum post, a
tag change, a ticket change, a wiki page) is an artifact, named by the
hash of its content, and never changes. Editing one makes a new artifact
that names the one it edits. A prefix of a hash that is unique in the
repository names it too.
fossil artifact HASHprints one. - Check-in: the artifact recording one commit: its files, comment,
branch, parents, and the user Fossil records in it (the committing login,
or the one named with
--user).fossil commit,fossil timeline. - Tag:
fossil tag add NAME CHECK-IN VALUEwrites a tag change, an artifact of its own, stored under the namesym-NAME. Fossil shows one value per tag name on a check-in: a later tag change replaces the value shown. Every tag change stays in the repository, with the user who made it, as an event of typegin itseventtable. - Branch: a tag too.
fossil commit --branch NAMEstarts one. - Forum thread: a root post and the replies under it. Each post is an
artifact naming the thread's root post and the post it answers; an edit
names the post it edits. Only Fossil's web page writes a post; no
fossilcommand does. - Login and capabilities: each user of a repository is a login with
capability letters, such as
s(setup),a(admin),i(check in, and push anything),o(check out),3(write to the forum). Capabilities are the outer limit of what a login may do; they cannot limit a login to one branch, or to certain tags.fossil user capabilities LOGIN LETTERS. - Who sent an artifact: each repository records, for every artifact it
received, the login it came from (its
rcvfromtable). That record is not copied to clones. The user named inside an artifact is whatever the writer's own clone said, so it proves nothing on its own. - The after-receive hook: a command in the repository's
hookssetting (fossil hook add --command CMD --type after-receive). After artifacts arrive, by sync or from a web page, Fossil runs it with one line per artifact on standard input: its hash, a space, and Fossil's summary, which begins with its kind:check-in to BRANCH by USER on DATE,forum-post ROOT,forum-reply-to ROOT(the first 14 hex digits of the thread's root post),tag …,ticket …,wiki "NAME". Fossil does not wait for it, keeps nothing it prints and ignores its exit code. A hook is a hint: a program that missed one finds the work again by reading the repository. - Serving:
fossil serverserves a repository over HTTP, with its web pages, the forum among them.