# 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 in
[**radicle-heartwood-lfs**](https://git.hswro.org/mab122/radicle-heartwood-lfs) (a fork of
Radicle's core node/CLI, `heartwood`). **Most people want to start there, not here** — that
repo has the full zero-to-usable setup guide. This repo is what you're reading if you want to
build/understand the transfer agent on its own, or you're following a link back from there.

`rad-lfs-transfer` is not meant to be invoked directly — `git lfs` spawns it automatically,
once a repository has been set up with `rad lfs init` (from the fork above).

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

## How it works

Every peer uses their own local IPFS node — there's no shared server:

- 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
[radicle-heartwood-lfs's `LFS-IPFS.md`](https://git.hswro.org/mab122/radicle-heartwood-lfs/src/branch/rad-lfs-ipfs/LFS-IPFS.md)
for the full rationale and how `rad seed`/`rad unseed` tie IPFS pinning to Radicle's existing
seeding lifecycle.

## Dependencies

On Arch Linux:

```sh
# To build and install
sudo pacman -S --needed rust git

# To actually use it (not needed to build/install — see "Requirements" below)
sudo pacman -S --needed kubo
```

On other distributions, install a Rust toolchain (e.g. via [rustup](https://rustup.rs)), Git,
and — only when you want to use LFS, not to build this — [Kubo](https://docs.ipfs.tech/install/).

## 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`) — `git-lfs` package on
  Arch (`sudo pacman -S --needed git-lfs`).

## Build & install

```sh
git clone ssh://git@git.hswro.org:9022/mab122/radicle-lfs-transfer.git
cd radicle-lfs-transfer
cargo install --path .
```

This installs the `rad-lfs-transfer` binary to `~/.cargo/bin` by default — make sure that's on
your `PATH`. If you're installing it alongside `radicle-heartwood-lfs` (the usual case), install
it to that project's shared root instead so everything ends up in one place:

```sh
cargo install --path . --force --locked --root ~/.radicle
```

(You normally don't need to clone this repo separately at all for that — `radicle-heartwood-lfs`
includes it as a git submodule and its own setup instructions cover installing both together.)

## 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.