# radicle-lfs-transfer

A [Git LFS custom transfer agent][custom-transfer] that backs large file storage with
[IPFS](https://ipfs.tech), for use with [Radicle](https://radicle.xyz) repositories.

This is the companion binary for the `rad lfs` support added to a
[fork of `heartwood`](../radicle-heartwood-lfs) (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`.

[custom-transfer]: https://github.com/git-lfs/git-lfs/blob/main/docs/custom-transfers.md

## 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](https://git-lfs.com) installed (`git-lfs` on your `PATH`).

## Build & install

```sh
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](LICENSE-APACHE) or
[MIT license](LICENSE-MIT) at your option.