95 lines
4.5 KiB
Markdown
95 lines
4.5 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 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
|
|
|
|
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
|
|
[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.
|