libfossil: The (Unofficial) Fossil SCM Library API

(If you are reading this via, be aware that that's a read-only mirror. The canonical home is

See also: TODOs, download, building, f-apps, DB functions, SQLSnippets, HackersGuide, doxygen docs (refreshed from current sources relatively frequently)

This source code repository houses an in-development C99-compliant library API for the Fossil SCM. The primary goal of this project (which is not part of the main Fossil SCM project but is architected by a long-time Fossil contributor) is to port existing behavior into a library form (the fossil app is extremely monolithic in nature). This effort intends to provide an alternative interface into fossil repositories, as opposed to a replacement for the core fossil application. It does not aim to provide 100% feature-parity with the main app - see TODOs for details about features which are considered out of scope or otherwise unlikely. It's instead intended to support the creation of new ways to access and manipulate fossil repositories. The f-apps page demonstrates what features are currently ported over.

The library has reached feature parity with Fossil's core-most SCM features, and can already be used to create a wide range of custom mini-applications, e.g. custom reporting apps or custom timeline apps are trivial to create using the "fcli" API: see the f-apps for numerous examples.

The fnc project offers an ncurses-based front-end to browsing fossil repositories, powered by libfossil. fnc is developed closely with this project and a copy of fnc is included in this source tree (and vice versa: the libfossil amalgamation is included in that tree), but that remote one is the canonical version.

Maintainer: this project is primarily maintained by Stephan Beal, a long-time Fossil contributor.

License: same as Fossil: the "2-Clause BSD" a.k.a. "FreeBSD License".

Update Feb. 2021: Back from the Dead

After a 6-year forced hiatus due to chronic RSI, libfossil is again making some headway. In early Feb. 2021 its hashing support was brought up to date with regard to fossil's hardened SHA1 and SHA3-256 hashes. That was the major technical hurdle preventing further progress, so now they way is clear (or clearer) for bringing the library into the 2020's.

A chat room and forum have been established for this effort but they are currently limited to developers. Please get in touch if you are a participant and need info about either. This project is currently only opened to active participants of the Fossil SCM project (as committers and/or forum participants). That said, it does not require the same code release waiver which that project requires. If/when the project reaches a client-usable state, it will be opened up for wider participation.

Status, TODOs, and Whatnot

This library can currently be considered to be of beta quality. What's there works (and is used for driving libfossil's own development) but is subject to change as experience reveals what those changes need to be. In other words: the library currently provides no API stability guarantees. libfossil has the same "safety-net" features as Fossil itself in order to avoid repository corruption and we are unaware of any cases where libfossil has been responsible for any repository-level damage.

All of Fossil's core-most SCM features have been ported over to libfossil, but several "nice-to-have" features, such as the stash and undo support, are pending (waiting only on someone to be interested enough in their lack to do the port/reimplementation). Anyone looking for a project roadmap/timeline is asked respectfully to look elsewhere - there is no timebox on nor schedule for this project/experiment. That said: the f-apps demonstrate what functionality is working.

The code changes can be followed via the timeline.

The current public (and documented) API can be found in the header files, and occasionally that gets exported to doxygen.

As of this writing (2022-02-21), libfossil is known to build and work on a variety of compilers on Intel-like (32- and 64-bit), ARM (32- and 64-bit), and even SPARC64 platforms. The primary development systems are Linux on x86/64 and ARM (32- and 64-bit), but it also gets a good deal of BSD and Mac test exposure via the fnc project.

As of December 2021, the library is far enough along that the the library's provided client applications can be used for the majority of CLI-based "daily driver" fossil operations, e.g. merging, diffing, and checking in/out. The most significant outlier is that fossil is still required for network synchronization. (Note, however, that this project does not aim to replace the fossil web UI, and that interface provides many app-level features (as opposed to library-level ones) which will never be duplicated here.)

"Rules" for Code Contributors

There is nothing holy or sacred about this repo, so feel free to hack at will. Most of the library's sanity tests are packaged in f-sanity.c. See cli.h for a mini-framework to bootstrap new apps and f-apps.