64 lines
3.1 KiB
Markdown
64 lines
3.1 KiB
Markdown
# 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.
|