Crate heroforge 

heroforge

A pure Rust client library for reading and writing Fossil SCM repositories.

Overview

heroforge provides a complete API for interacting with Fossil repositories without requiring the Fossil CLI. It supports both reading from existing repositories and creating new ones from scratch.

Features

Read Operations

• Open and read existing Fossil repositories
• Browse repository history and check-ins
• List and read files at any check-in
• Find files using glob patterns
• Navigate directory structures
• Access branch and tag information

Write Operations

• Create new repositories from scratch
• Commit files with full manifest generation
• Create and manage branches
• Add tags to check-ins
• Manage users and permissions

Quick Start

Reading from an existing repository

use heroforge::Repository;

fn main() -> heroforge::Result<()> {
    // Open a Fossil repository
    let repo = Repository::open("project.fossil")?;

    // Get the latest check-in on trunk
    let tip = repo.trunk_tip()?;
    println!("Latest: {} by {}", tip.hash, tip.user);
    println!("Comment: {}", tip.comment);

    // List all files
    let files = repo.list_files(&tip.hash)?;
    for file in &files {
        println!("  {}", file.name);
    }

    // Read a specific file
    let content = repo.read_file(&tip.hash, "README.md")?;
    println!("README:\n{}", String::from_utf8_lossy(&content));

    Ok(())
}

Creating a new repository

use heroforge::Repository;

fn main() -> heroforge::Result<()> {
    // Create a new repository
    let repo = Repository::init("new_project.fossil")?;

    // Create initial check-in
    let init_hash = repo.create_initial_checkin("admin")?;

    // Add some files
    let files: Vec<(&str, &[u8])> = vec![
        ("README.md", b"# My Project\n"),
        ("src/main.rs", b"fn main() { println!(\"Hello!\"); }\n"),
    ];
    let commit_hash = repo.commit(
        &files,
        "Initial project structure",
        "developer",
        Some(&init_hash),
        None, // stays on trunk
    )?;

    // Tag the release
    repo.add_tag("v1.0.0", &commit_hash, "developer")?;

    // Create a feature branch
    let branch_hash = repo.create_branch("feature-x", &commit_hash, "developer")?;

    Ok(())
}

Repository Structure

A Fossil repository is a SQLite database containing:

• Blobs: Compressed file contents and manifests
• Manifests: Check-in metadata (files, timestamps, comments, parents)
• Tags: Branch names, version tags, and other labels
• Events: Timeline of repository activity

Compatibility

Repositories created with heroforge are fully compatible with the Fossil CLI. You can use fossil ui to browse repositories created by this library, and heroforge can read repositories created by the Fossil CLI.

Error Handling

All operations return Result<T>, which wraps potential FossilError values. Common errors include:

• FossilError::NotARepository - The file is not a valid Fossil repository
• FossilError::ArtifactNotFound - Requested check-in, file, or tag doesn’t exist
• FossilError::AmbiguousHash - Hash prefix matches multiple artifacts

Re-exports

pub use error::FossilError;

pub use error::Result;

pub use repo::CheckIn;

pub use repo::FileInfo;

pub use repo::Repository;

Modules

artifact

error

hash

repo

Repository access and manipulation.

sync

Fossil repository synchronization.