libfossil: 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 is to port existing behaviour into a library form (the fossil app is extremely monolithic in nature). This effort, officially called "libfossil", 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 enhance one's ability to access and manipulate fossil repositories. The f-apps page demonstrates what features are currently ported over.

The library has not yet reached core feature parity with fossil, but is far enough along to be able 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.

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

All of this code is an experiment, and it does not represent a commitment by anyone. It is alpha quality. What's there works but is subject to change and there is still a great deal of the higher-level SCM bits left to port in and refactor to make them usable via library-style interfaces. 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 (2021-11-01), 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 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.


Notable changes (newest at the top)...