toolpath-git 0.1.3

Derive Toolpath provenance documents from git repository history
Documentation

toolpath-git

Derive Toolpath provenance documents from git repository history.

Git knows what changed but loses why — commit messages are unstructured, multi-actor provenance collapses into a single author, and abandoned approaches disappear entirely. This crate bridges that gap by converting git history into structured Toolpath documents where every commit becomes a step with typed actors, intent, and full diff provenance.

Overview

Uses git2 (libgit2 bindings). Each commit becomes a Step with the commit's diff as the raw change perspective, the author mapped to an actor string, and the commit message as intent.

  • Single branch produces a Path
  • Multiple branches produce a Graph of paths

Usage

use toolpath_git::{derive, DeriveConfig};

let repo = git2::Repository::open(".")?;
let config = DeriveConfig {
    remote: "origin".into(),
    title: None,
    base: None,
};

// Single branch -> Path document
let doc = derive(&repo, &["main".into()], &config)?;

// Multiple branches -> Graph document
let doc = derive(&repo, &["main".into(), "feature".into()], &config)?;

// Branch with start point
let doc = derive(&repo, &["main:HEAD~10".into()], &config)?;
# Ok::<(), anyhow::Error>(())

API

Function Description
derive(repo, branches, config) Main entry point. Single branch -> Path, multiple -> Graph
derive_path(repo, spec, config) Derive a Path from a single branch
derive_graph(repo, specs, config) Derive a Graph from multiple branches
list_branches(repo) List local branches with summary metadata
get_repo_uri(repo, remote) Get the repository URI from a remote
normalize_git_url(url) Normalize a git URL (strip .git, convert SSH to short form)
slugify_author(name, email) Create a URL-safe slug from author info

Branch specifications

Branches are specified as "name" or "name:start":

  • "main" -- all commits on main (with auto-detection of where to start)
  • "main:HEAD~10" -- last 10 commits on main
  • "feature:abc123" -- feature branch from commit abc123

The DeriveConfig.base field overrides per-branch starts globally.

Mapping

Git concept Toolpath concept
Commit Step
Branch Path
Commit hash step.id (first 8 chars)
Author step.actor as human:slug
Commit message meta.intent
Diff change[file].raw (unified diff)
Commit hash meta.source.revision
Remote URL path.base.uri

Part of Toolpath

This crate is part of the Toolpath workspace. See also: