<strong>Achtung: RSI has effectively removed this project's maintainer from the programming world, and this project is no longer maintained. Since the SHA-related changes in Fossil, this library is no longer compatible with fossil (and getting it to work with fossil requires an as-yet-unknown amount of effort). Nonetheless, this library provides (IMO) a solid starting point (or at least a reference point) for anyone interested in starting a port-fossil-to-a-library effort.</strong>
<strong>Achtung: RSI has effectively removed this project's maintainer from the programming world, and this project is no longer maintained. Since the SHA3-related additions in Fossil, this library is no longer compatible with fossil (and getting it to work with fossil requires an as-yet-unknown amount of effort). Nonetheless, this library provides (IMO) a solid starting point (or at least a reference point) for anyone interested in starting a port-fossil-to-a-library effort.</strong>

# Update Feb. 2021:

Some momentum has been gain in the idea of reviving this project, the first major step of which requires updating its hash handling to deal with SHA3 hashes. That may or may not happen but... some momentum has been gained, which is significant in and of itself. A chat room and forum have been established for this effort but they are limited to developers. Please [get in touch][home-sgb] if you are a participant and need info about either. This project is *currently* only opened to active participants of the [Fossil SCM][home-fossil] project, as it requires a relatively good understanding of fossil and activity in that project acts as "proof of capability" for participating here.

[home-sgb]: https://wanderinghorse.net/home/stephan/
[home-fossil]: https://fossil-scm.org


<h1>libfossil: Fossil SCM Library API</h1>
# libfossil: Fossil SCM Library API

See also: [download], [building], [f-tools],
[DbFunctions], [SQLSnippets], [HackersGuide],
[http://fossil.wanderinghorse.net/repos/libfossil/doxygen/|doxygen docs] (refreshed from current sources relatively frequently), [https://docs.google.com/document/d/13gRSl6-bj3LV-OKgE-BsqvqF33UFYW3oa3A2OJC5QSY/view|"s2" script bindings]
See also: [](download), [](building), [](f-tools),
[](DbFunctions), [](SQLSnippets), [](HackersGuide),
[doxygen docs][doxygen-docs] (refreshed from current sources relatively frequently), ["s2" script bindings](https://docs.google.com/document/d/13gRSl6-bj3LV-OKgE-BsqvqF33UFYW3oa3A2OJC5QSY/view).


This source code repository houses an in-development library API for the [http://fossil-scm.org|Fossil SCM]. The primary goal is to port existing behaviour into a library form (the v1 app is extremely monolithic in nature). This effort, officially called "libfossil", intends to introduce no breaking changes, and the intention is to provide an alternative interface into fossil repositories, as opposed to a replacement for the core fossil application.
This source code repository houses an in-development library API for the [Fossil SCM][home-fossil]. The primary goal is to port existing behaviour into a library form (the v1 app is extremely monolithic in nature). This effort, officially called "libfossil", intends to introduce no breaking changes, and the intention is to provide an alternative interface into fossil repositories, as opposed to a replacement for the core fossil application.

This code currently doesn't do much which would interest non-Fossil hackers. It might be of interest to those wanting to follow or participate in the design of libfossil.

<strong>License:</strong> same as Fossil: the "2-Clause BSD" a.k.a. "FreeBSD License".
**License:** same as Fossil: the "2-Clause BSD" a.k.a. "FreeBSD License".

<h2>Status, TODOs, and Whatnot</h2>
## Status, TODOs, and Whatnot

All of this code is an <em>experiment</em>, and it does not represent a commitment by anyone that any of this code will some day end up living under the umbrella of the larger Fossil SCM project. If all goes well, that's the eventual goal, though. 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-tools] demonstrate what functionality is working.
All of this code is an <em>experiment</em>, and it does not represent a commitment by anyone that any of this code will some day end up living under the umbrella of the larger Fossil SCM project. If all goes well, that's the eventual goal, though. 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-tools) demonstrate what functionality is working.

The code changes can be followed via [/timeline | the timeline].
The code changes can be followed via [the timeline](/timeline).

The current public (and documented) API can be found in [/dir?name=include/fossil-scm | the header files], and occasionally that gets [http://fossil.wanderinghorse.net/repos/libfossil/doxygen/|exported to doxygen].
The current public (and documented) API can be found in [the header files](/dir?name=include/fossil-scm), and occasionally that gets [exported to doxygen][doxygen-docs].

TODOs, design discussions, etc... you might want to get a coffee/tee/beer before starting through [https://docs.google.com/document/d/12g0s5A2TPX7-y47Nsw235rvsjcuh49TnHfMDB4ASvlo/view|the list].
TODOs, design discussions, etc... you might want to get a coffee/tee/beer before starting through [the list](https://docs.google.com/document/d/12g0s5A2TPX7-y47Nsw235rvsjcuh49TnHfMDB4ASvlo/view).

<h2>"Rules" for Code Contributors</h2>
# "Rules" for Code Contributors

   *  <s>All code contributors must have a license waiver on file with DRH, as the hope is to eventually release this code as the next generation of Fossil. Non-code contributions are happily accepted from anyone.</s> (No longer needed!)
   *  When working on bits which themselves write to the repository, e.g. creating checkins, please be exceedingly careful not to corrupt the db :-D.
   *  Please try to conform to the overall coding style (as laid out by Fossil v1). We're not picky about whether or not spaces belong before/after an <tt>if</tt>, but the general overall style should be uniform.
   *  Please build with the highest possible warning level and enable fatal warnings (in GCC and similar compilers: <tt>-Wall -Werror</tt>).
   *  Please try to conform to the overall coding style (as 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 uniform.
   *  Please build with the highest possible warning level and enable fatal warnings (in GCC and similar compilers: `-Wall -Werror`).
   *  Don't bother using branches unless you really want to - the trunk has no stability guarantees and is very much in flux, so feel free to work there instead of a branch if you like.

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 <tt>[/finfo?name=f-apps/f-sanity.c|f-sanity.c]</tt>. See <tt>[/finfo?name=include/fossil-scm/fossil-cli.h|fossil-cli.h]</tt> for a mini-framework to bootstrap new apps and [f-tools].
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 <tt>[f-sanity.c](/finfo?name=f-apps/f-sanity.c)</tt>. See <tt>[fossil-cli.h](/finfo?name=include/fossil-scm/fossil-cli.h)</tt> for a mini-framework to bootstrap new apps and [f-tools].


<h2>News</h2>

Notable changes (newest at the top)...

   *  20130919: Realized i hadn't updated the news in a while. Future news will be posted as [/timeline?y=e|Events in the /timeline].
   *  20130919: Realized i hadn't updated the news in a while. Future news will be posted as [technotes in the /timeline](/timeline?y=e).
   *  20130901: <b>Milestone:</b> side-by-side (SBS) diff generation was ported in.
   *  20130831: <b>Milestone:</b> the basic diff-generation code has been ported in (context diffs only, not yet SBS).
   *  20130828: <b>Milestone:</b> we can now create new repos.
   *  20130825: Minor milestone: clients can now hook in to the crosslinking phase. This is the first step needed for generating native-language timeline views.
   *  20130824: Minor milestone: saved the first wiki changes today.
   *  20130822: <b>Milestone:</b> the "verify at commit" operation, which ensures that fossil can actually read back what the user would like to save before the transaction is committed, is in place and working (or not failing ;). This was the last missing piece of the lower-level SCM bits (or the last piece which was holding anything up - there might be more pieces to port once i get around to the 'rebuild' functionality).
   *  20130819: <em>Minor milestone</em>: we can now losslessly round-trip Event Artifacts to/from fossil. Event crosslinking was implemented.
   *  20130816: <b>Milestone:</b> manifest parsing is more or less complete, covering the whole range of control artifact types. Strict validation is done (including the Z-card hash) to ensure that bogus manifests cannot be read (and the generator does the same at several different levels). "Parsing," in this context means converting a raw Fossil manifest to a higher-level (OO) construct. That construct can then be output to a new manifest which is identical to the old one, providing a 100% loss-less round-trip conversion. (Such round-trips are useful only for testing/proof-of-concept, and are not needed in practice.)
   *  20130815: the past couple days have seen many incremental additions to the manifest machinery. We can now "round-trip" some artifact types, parsing them into a high-level form and re-generating them from that high-level form.
   *  20130812: Started the [f-tools].
   *  20130811: Got "manifest crosslinking" of control artifact (tag changes) ported in.
   *  20130810: <b>Milestone:</b> the library [/info/70666e1c11|saved its first tag] today! (The timestamp of the tag was intentionally falsified for testing purposes.)
   *  20130808: Restructured source tree and ported build configuration process to [http://msteveb.github.io/autosetup/|autosetup] (because that's what Fossil uses). Existing build files (not the sources) still require GNU Make on a Unix platform, though. Many thanks to Steve Bennett (autosetup's author) for his assistance.
   *  20130810: <b>Milestone:</b> the library [saved its first tag](/info/70666e1c11) today! (The timestamp of the tag was intentionally falsified for testing purposes.)
   *  20130808: Restructured source tree and ported build configuration process to [autosetup](https://msteveb.github.io/autosetup/) (because that's what Fossil uses). Existing build files (not the sources) still require GNU Make on a Unix platform, though. Many thanks to Steve Bennett (autosetup's author) for his assistance.
   *  20130804: ported in the symbol-to-uuid resolution bits from the main repo. These are what allow apps to use short-form UUIDs and symbolic names like "trunk," instead of having to use 40-byte UUIDs everywhere.
   *  20130803: most of the infrastructure for creating [http://fossil-scm.org/index.html/doc/trunk/www/fileformat.wiki|manifests and control artifacts] is in place, but we don't yet write them to the db.
   *  20130803: most of the infrastructure for creating [manifests and control artifacts](https://fossil-scm.org/index.html/doc/trunk/www/fileformat.wiki) is in place, but we don't yet write them to the db.
   *  20130801: ported in the delta generation/apply code and added script bindings for them.
   *  20130730: changed internal handling of DBs from 1 connection per db to a single main connection to an in-memory db and attaching the repo/config/checkout to that. Not yet sure if this is a feature or a bug, but it simplifies the internal tracking of db handles notably.
   *  20130728: it can now search for and open a checkout based on a directory name, analog to how v1 finds an open checkout.
   *  20130727: started work on a [/dir?ci=tip&name=th1ish|th1ish script engine binding] for v2. It is of course a work-in-progress but it is extended in parallel to the core lib because that simplifies testing and helps work the kinks out of the core API.
   *  20130727: started work on a [th1ish script engine binding](/dir?ci=tip&name=th1ish) for v2. It is of course a work-in-progress but it is extended in parallel to the core lib because that simplifies testing and helps work the kinks out of the core API.
   *  20130726: when opening a repo db, the library now validates that it is a repo db, and can distinguish between/report various types of errors, e.g. repo schema is out of data or the db is not a fossil repo.
   *  20130725: removed the per-instance allocator configuration - it is now library-wide. This simplifies buffer usage and makes it legal to use them before instantiating a fossil context.

[doxygen-docs]: https://fossil.wanderinghorse.net/repos/libfossil/doxygen/