Crate toolpath_git 

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)?;

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:

• toolpath – core types and query API
• toolpath-claude – derive from Claude conversations
• toolpath-dot – Graphviz DOT rendering
• toolpath-cli – unified CLI (cargo install toolpath-cli)
• RFC – full format specification

Structs

BranchInfo

Summary information about a local branch.

BranchSpec

Parsed branch specification.

DeriveConfig

Configuration for deriving Toolpath documents from a git repository.

Functions

derive

Derive a Toolpath Document from the given repository and branch names.

derive_graph

Derive a Toolpath Graph from multiple branch specifications.

derive_path

Derive a Toolpath Path from a single branch specification.

get_repo_uri

Get the repository URI from a remote, falling back to a file:// URI.

list_branches

List local branches with summary metadata.

normalize_git_url

Normalize a git remote URL to a canonical short form.

slugify_author

Create a URL-safe slug from a git author name and email.