radicle-lfs-transfer/README.md

radicle-lfs-transfer

A Git LFS custom transfer agent that backs large file storage with IPFS, for use with Radicle repositories.

This is the companion binary for the rad lfs support added to a fork of heartwood (Radicle's core node/CLI). It is not meant to be invoked directly — git lfs spawns it automatically once a repository has been set up with rad lfs init.

How it works

Instead of a shared, seed-hosted LFS server, every peer uses their own local IPFS node:

• On git add/git commit, a pre-commit hook (installed by rad lfs init) adds each staged LFS-tracked file to your local IPFS daemon, pins it, and records the resulting CID as a git note (refs/notes/rad-lfs) attached to the LFS pointer file's own git blob hash. That notes ref travels with the repository via Radicle's normal replication, alongside everything else.
• rad-lfs-transfer implements the other half: when git lfs push/pull runs, it's invoked per-object over stdin/stdout JSON (the standard Git LFS custom-transfer-agent protocol) and:
  • upload: confirms the object is already pinned in IPFS (it should be, from the pre-commit hook) or adds it if the hook was bypassed.
  • download: reconstructs the expected pointer blob hash from the requested oid/size, looks up its cid= note, and fetches the content from your local IPFS daemon (which will pull it from the wider IPFS network if it isn't local yet).

There is no central server anywhere in this design — see the companion heartwood fork's documentation for the full rationale and how rad seed/rad unseed tie IPFS pinning to Radicle's existing seeding lifecycle.

Requirements

• Only needed at runtime, not to build or install this binary: a local IPFS (Kubo) daemon reachable at http://127.0.0.1:5001 (or wherever KUBO_API_URL points). If it's not running when git lfs push/pull tries to use it, you'll get a clear error telling you to start one (ipfs daemon) — nothing fails silently, and nothing about building or installing this binary requires IPFS to be present at all.
• Git LFS installed (git-lfs on your PATH).

Build & install

cargo install --path .

This installs the rad-lfs-transfer binary to ~/.cargo/bin (make sure that's on your PATH — it's needed there so git lfs can find it once rad lfs init configures it).

Configuration

Environment variable	Default	Purpose
KUBO_API_URL	http://127.0.0.1:5001	Base URL of your local Kubo HTTP RPC API

You normally don't need to set this yourself — rad lfs init wires up everything else (the transfer-agent config, the pre-commit hook, and the notes-ref refspecs) automatically.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.