libfossil: The (Unofficial) Fossil SCM Library API

(If you are reading this via fossil-scm.org, be aware that that's a read-only mirror. The canonical home is https://fossil.wanderinghorse.net/r/libfossil.)

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 the way is clear (or clearer) for bringing the library into the 2020's.

The forum is open to new contributors, either anonymously or with self-created accounts. Developers are welcomed to join the /chat room, where there's normally at least one person lingering.

Developer access on this project is currently opened only to active participants of the Fossil SCM project (as committers and/or forum participants). It does not, however, require the same code release waiver which that project requires. If you would like developer access, please contact the primary maintainer.

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 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

• When working on bits which themselves write to the repository, e.g. creating checkins, please be exceedingly careful not to corrupt the db :-D. The library has several layers of defense against the injection of problematic control artifacts, but still... be careful.
• Please try to conform to the rough overall coding style (as initially laid out by Fossil v1). We're not picky about whether or not spaces belong before/after an if, but the general overall style should be more or less uniform.
• Please build with the highest possible warning level and enable fatal warnings (in GCC and similar compilers: -Wall -Werror -pedantic).
• The trunk currently has no stability guarantees and is very much in flux, so feel free to work there instead of a branch if you like. Insofar as possible/reasonable, using libfossil's own f-apps for working with the repository is recommended (e.g. using f-ci to perform checkins and f-merge for merging branches).

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.