Expand description
§heroforge
A pure Rust client library for reading and writing Heroforge SCM repositories.
§Overview
heroforge provides a complete API for interacting with Heroforge repositories without
requiring the Heroforge CLI. It supports both reading from existing repositories and
creating new ones from scratch.
§Quick Start (Builder API)
use heroforge_core::Repository;
fn main() -> heroforge_core::Result<()> {
// Create a new repository
let repo = Repository::init("project.forge")?;
// Create initial commit using builder
let init = repo.commit_builder()
.message("Initial commit")
.author("admin")
.initial()
.execute()?;
// Add files using builder
let v1 = repo.commit_builder()
.message("Add project files")
.author("developer")
.parent(&init)
.file("README.md", b"# My Project\n")
.file("src/main.rs", b"fn main() {}\n")
.execute()?;
// Tag the release
repo.tags()
.create("v1.0.0")
.at_commit(&v1)
.author("developer")
.execute()?;
// Read files using builder
let readme = repo.files().on_trunk().read_string("README.md")?;
let rust_files = repo.files().at_tag("v1.0.0").find("**/*.rs")?;
// Sync to remote
repo.sync()
.to("quic://backup.example.com:4443/project")
.push()?;
Ok(())
}§Features
§File Operations
// List files on trunk
let files = repo.files().on_trunk().list()?;
// Read file from a branch
let content = repo.files().on_branch("feature").read("config.json")?;
// Find files at a tag
let rust = repo.files().at_tag("v1.0").find("**/*.rs")?;§Commit Operations
let hash = repo.commit_builder()
.message("Add feature")
.author("developer")
.parent("abc123")
.file("src/feature.rs", b"// new feature")
.execute()?;§Branch/Tag Operations
// Create branch
repo.branches()
.create("feature-x")
.from_branch("trunk")
.author("developer")
.execute()?;
// Create tag
repo.tags()
.create("v1.0.0")
.at_branch("trunk")
.author("developer")
.execute()?;§Filesystem Operations (Copy, Move, Delete, Find, Symlinks)
use heroforge_core::fs::{Find, Modify};
// Copy, move, delete files and directories
Modify::new(&repo)
.message("Reorganize project structure")
.author("developer")
.copy_file("README.md", "docs/README.md")
.copy_dir("src", "backup/src")
.move_file("old.txt", "archive/old.txt")
.move_dir("scripts", "tools")
.delete_file("temp.log")
.delete_dir("cache")
.execute()?;
// Find files with patterns and ignore rules
let rust_files = Find::new(&repo)
.pattern("**/*.rs")
.ignore("target/**")
.ignore_hidden()
.paths()?;
// Change permissions
Modify::new(&repo)
.message("Make scripts executable")
.author("developer")
.make_executable("scripts/deploy.sh")
.chmod_dir("bin", 0o755)
.execute()?;
// Create symlinks
Modify::new(&repo)
.message("Add symlinks")
.author("developer")
.symlink("lib/latest", "lib/v2.0")
.execute()?;
// Utility functions
use heroforge_core::fs::{exists, is_dir, du, count};
let file_exists = exists(&repo, "README.md")?;
let is_directory = is_dir(&repo, "src")?;
let size = du(&repo, "src/**/*")?;
let num_files = count(&repo, "**/*.rs")?;§Sync Operations (QUIC)
// Push over QUIC
repo.sync()
.to("quic://server:4443/repo")
.push()?;
// Pull from remote
repo.sync()
.from("quic://server:4443/repo")
.auth("user", "password")
.pull()?;Re-exports§
pub use error::FossilError;pub use error::Result;pub use repo::CheckIn;pub use repo::FileInfo;pub use repo::Repository;pub use server::Server;pub use sync::SyncBuilder;pub use sync::SyncProtocol;pub use sync::SyncResult;pub use fs::DirectoryEntry;pub use fs::FileHandle;pub use fs::FileKind;pub use fs::FileMetadata;pub use fs::FilePermissions;pub use fs::FileSystem;pub use fs::FileSystemStatus;pub use fs::FindResults;pub use fs::FsError;pub use fs::FsOperation;pub use fs::FsResult;pub use fs::OperationSummary;pub use fs::SavePoint;pub use fs::Transaction;pub use fs::TransactionMode;pub use fs::TransactionState;pub use fs::CommitConfig;pub use fs::CommitWorker;pub use fs::DEFAULT_COMMIT_INTERVAL;pub use fs::FsInterface;pub use fs::FsInterfaceStatus;pub use fs::MAX_FILE_SIZE;pub use fs::StagedFile;pub use fs::Staging;pub use fs::StagingState;pub use repo::BranchBuilder;pub use repo::BranchesBuilder;pub use repo::CommitBuilder;pub use repo::FileEntry;pub use repo::FileQuery;pub use repo::FileType;pub use repo::FilesBuilder;pub use repo::FindBuilder;pub use repo::FindResult;pub use repo::FsBuilder;pub use repo::FsOperation as RepoFsOperation;pub use repo::FsOpsBuilder;pub use repo::FsPreview;pub use repo::HistoryBuilder;pub use repo::Permissions;pub use repo::TagBuilder;pub use repo::TagsBuilder;pub use repo::UserBuilder;pub use repo::UsersBuilder;