go-libfossil: Artifact [a01eca1e08]

Artifact a01eca1e085205fe835dfd6e729aa9c2b381cb37a1d0495b5905e1784ac17211:

File docs/site/content/docs/migration-from-fossil.md — part of check-in [6273a0750d] at 2026-07-22 23:03:24 on branch trunk — fix: correct go.mod module path to go-libfossil (#76) (#117)
* fix: correct go.mod module path to go-libfossil (#76)
The module directive still declared github.com/danmestas/libfossil after the repository was renamed to go-libfossil. pkg.go.dev/godoc scraping matches the declared module path against its hosting path, so the stale path broke SDK doc generation.
Rename the module path across all four in-repo modules (root, the two db/driver submodules, observer/otel, and docs/site) and every internal import, plus the release workflow, the doc-generation script, and the docs.
No tag has been published under the go-libfossil path yet, so the cross-module requires cannot resolve from the proxy. Add replace directives pointing the in-repo requires at their local directories so GOWORK=off builds and the CI matrix resolve without a published version. These replaces are ignored by downstream consumers and can be dropped once new-path tags are cut.
* Guard releases against replace directives; regenerate SDK docs
The go-libfossil rename bridges the in-repo modules with `replace` directives. Go refuses a main module that carries them, so a tag cut while they are present breaks `go install .../cmd/libfossil@<tag>` and every `@version` fetch of the driver submodules. Add a Release workflow step that fails the job before anything is published if any tracked go.mod still contains a replace directive, so the bridge is a CI-enforced TODO rather than a silent landmine. The step comment records what unblocks a release: re-tag the submodules with the corrected module paths, bump the root requires, then drop the replace blocks.
Regenerate the SDK reference docs. The previous pass only substituted URLs over the pre-existing generated files, leaving stale signatures (Repo.Timeline was still documented as taking LogOpts rather than TimelineOpts). Note that gomarkdoc must be run outside a git worktree — inside one it silently strips every source link.
Also reword the README rename note, which read as though the import path had not changed, and re-sort the ncruces require block. (user: [email protected], size: 6773) [annotate] [blame] [check-ins using]

title: Migration from Fossil

weight: 30

This guide is for users of upstream Fossil SCM (the C binary distributed by fossil-scm.org) who are evaluating libfossil — a pure-Go implementation of the Fossil repository format and sync protocol.

It is intentionally honest about gaps. If a capability is not listed under "Command coverage" below, assume it is not implemented yet.

For a structural overview of how libfossil is organised — the package layout, storage model, and pluggable axes — see Architecture.

Repo format compatibility

libfossil reads and writes the same on-disk .fossil SQLite repository format as upstream Fossil. A repository created by either tool can be opened by the other at the file level — there is no import/export step and no data migration is needed. Both implementations share the same blob table layout, manifest/control artifact encoding, and delta chain representation.

One caveat: features introduced in very recent upstream Fossil releases (bleeding-edge artifact card types, new Fossil-specific SQL functions used in triggers) may not yet be parsed by libfossil. Stable Fossil repositories from the last several years round-trip cleanly.

Binary name and invocation

The compiled binary is named libfossil (not fossil) to avoid $PATH collisions when both tools are installed on the same machine:

go install github.com/danmestas/go-libfossil/cmd/libfossil@latest

libfossil uses a subcommand-grouped syntax: the top-level group is repo, and individual operations live beneath it. Upstream Fossil uses a flat command style. Examples:

Upstream Fossil	libfossil
`fossil clone URL repo.fossil`	`libfossil repo clone URL repo.fossil`
`fossil ci -m "msg" file.txt`	`libfossil -R repo.fossil repo ci -m "msg" file.txt`
`fossil timeline`	`libfossil -R repo.fossil repo timeline`

The -R <path> flag selects the repository and is a global flag (before the repo subcommand group).

Command coverage

The following repo subcommands are implemented today. Every entry below corresponds to a registered Kong command in cli/repo.go in the libfossil source tree.

Repository creation

repo new — create a new, empty repository file.
repo clone — clone a remote Fossil server over HTTP(S).

Working tree and checkout

repo open — materialize a checkout in a directory (creates .fslckout).
repo co — check out a named version.
repo ls — list files in a version.
repo status — show pending changes in the working directory.
repo add — stage files for addition.
repo rm — stage files for removal.
repo rename — rename a tracked file.
repo revert — undo staging changes.
repo ci — commit staged changes.

History and inspection

repo timeline — repository history.
repo diff — show changes vs. a version.
repo annotate / repo blame — annotate file lines with commit history.
repo cat — output artifact content.
repo hash — hash files (SHA1 or SHA3-256).
repo info — repository statistics.
repo resolve — resolve a symbolic name to a UUID.
repo schema — operate on the synced table schema.
repo query — run ad-hoc SQL against the repository DB.

Branching and merging

repo branch — list/create branches.
repo tag — tag operations.
repo merge — merge a divergent version into the current checkout.
repo conflicts — list unresolved merge conflicts.
repo mark-resolved — mark a conflict as resolved.
repo bisect — binary-search commits for bug introductions.
repo undo / repo redo — undo/redo the last operation.
repo stash — stash working changes.

Collaboration and admin

repo user — user management.
repo invite — generate an invite token for a user.
repo config — get/set/list repository configuration.
repo wiki — wiki page operations.
repo uv — unversioned file operations.
repo extract — extract files from a version.
repo delta — create/apply delta operations.
repo verify — verify repository integrity.

Known gaps vs. upstream Fossil CLI

The following upstream commands have no libfossil equivalent today:

fossil ui / fossil server / fossil http — no web UI or HTTP admin server is shipped.
fossil sync / fossil push / fossil pull — there is no CLI verb; sync is exposed via the Go API (Repo.Sync, Repo.XferHandler) but not as a subcommand.
fossil update — merging a newer trunk into a checkout has no dedicated CLI command; use repo co plus repo merge as needed.
fossil search — no CLI front-end for full-text search.
fossil fts-config / FTS index management — no CLI command.

What's not supported yet

Beyond the gaps listed above, several broader features of upstream Fossil are not yet exposed by libfossil:

Web UI / HTTP admin — no equivalent of fossil ui. The sync protocol handler exists as Repo.XferHandler() for programmatic embedding, but the HTML UI, wiki viewer, ticket tracker, and forum are not implemented.
Interactive conflict resolution — there is no guided merge tool. Conflicts are listed via repo conflicts and cleared with repo mark-resolved, but resolution itself happens in your editor.
Full-text search CLI — internal/search contains indexing and query primitives, but no CLI command surfaces them. Use the Go API directly.
Ticket and forum subsystems — not implemented.
Mirror / export bridges to Git, svn, and other systems — not implemented.

If any of these are load-bearing for your workflow, stay on upstream Fossil for now.

Interop patterns

Where libfossil shines is in environments where the upstream C binary is inconvenient to run:

CGo-free CI pipelines — libfossil links statically with a pure-Go SQLite driver (db/driver/modernc), so clone/sync steps work on stripped container images and cross-compiled targets with no system dependencies.
Embedding in Go services — the Repo handle can be used directly from a Go program to read history, extract artifacts, or accept pushes over a custom transport (WebSocket, NATS, libp2p).
WASI / browser deployments — the db/driver/ncruces SQLite driver compiles to WebAssembly, enabling repo access from edge runtimes.

See examples/ (planned) for concrete starting points. Until those land, cmd/libfossil/main.go is the shortest working example of wiring the CLI package into a binary.