radicle-heartwood-lfs/README.md

❤️🪵

Fork: Git LFS support, backed by IPFS

This is a fork of upstream radicle-dev/heartwood adding Git LFS (large file) support, with large file content stored on each contributor's own local IPFS node rather than a central server. Everything below the horizontal rule is upstream's own README, unchanged. See LFS-IPFS.md for the full design, troubleshooting, and background — this section is just the quick start.

The LFS byte-transfer logic lives in a separate, small companion repository: radicle-lfs-transfer, included here as a git submodule.

Dependencies (Arch Linux)

# To build and install rad/radicle-node/radicle-lfs-transfer
sudo pacman -S --needed rust git openssh base-devel

# To actually use Git LFS (not needed to build/install anything)
sudo pacman -S --needed git-lfs kubo

On other distributions: a Rust toolchain (e.g. via rustup), Git, OpenSSH, a C toolchain — and, only for using rad lfs, Git LFS and Kubo.

Zero to usable

# Clone with the submodule
git clone --branch rad-lfs-ipfs --recurse-submodules \
  ssh://git@git.hswro.org:9022/mab122/radicle-heartwood-lfs.git
cd radicle-heartwood-lfs

# Build & install rad, radicle-node, git-remote-rad, and rad-lfs-transfer to one place
cargo install --path crates/radicle-cli --force --locked --root ~/.radicle
cargo install --path crates/radicle-node --force --locked --root ~/.radicle
cargo install --path crates/radicle-remote-helper --force --locked --root ~/.radicle
cargo install --path radicle-lfs-transfer --force --locked --root ~/.radicle

# Add the install root to your PATH (e.g. in ~/.bashrc / ~/.zshrc)
export PATH="$HOME/.radicle/bin:$PATH"

# Verify
rad --version

From here, use rad exactly as upstream describes below (rad auth, rad init, etc). The only new commands are rad lfs init (run once per repository you want large-file support in) and rad lfs rekey (run after granting a new collaborator access to a private repository, so they can decrypt previously-committed LFS objects too) — see LFS-IPFS.md for that workflow and how private-repo content gets encrypted before it reaches IPFS. Nothing above requires IPFS; Git LFS support specifically needs a running ipfs daemon, and rad lfs init will tell you plainly if one isn't reachable rather than failing confusingly later.

Quickstart cheatsheet

One-time, per repository (with ipfs daemon already running in the background):

rad lfs init
git lfs track "*.psd"      # or whatever large-file patterns you need
git add .gitattributes

Day to day — same as plain Git LFS, just remember to push both the branch and the refs/notes/rad-lfs mapping (see the push gotcha below):

git add my-large-file.psd
git commit -m "Add asset"  # pre-commit hook pins it to IPFS, records the CID as a git note
git push rad <branch>      # pushes your commit
git push rad               # pushes the refs/notes/rad-lfs mapping (separate step, see below)

Someone else, cloning the repository for the first time:

rad clone rad:<repo-id>
cd <repo>
rad lfs init                # one-time, needs their own ipfs daemon running
git lfs pull                 # fetches large files via IPFS instead of git

Private repository? You'll just be prompted for your keystore passphrase on commit/ push/pull when needed (ssh-agent alone can't do the key-agreement encryption requires — see LFS-IPFS.md). After granting a new collaborator access, have an already-authorized collaborator run rad lfs rekey and push, so the newcomer can decrypt files committed before they were added:

rad id update --allow <did>   # or add them as a delegate
rad lfs rekey                 # run by someone already authorized
git push rad                  # publish the updated wrapped keys

The push gotcha, explained: rad lfs init only configures a push refspec for the notes ref, not the branch — so git push rad <branch> and bare git push rad each push only what their own refspec covers, and you need both after committing an LFS-tracked file. Forgetting the bare git push rad is the most common way to end up with "it works for me, but my collaborator gets no CID recorded for oid ..." — their clone has your commit but not your note yet.

Full design, encryption details, and a longer troubleshooting table: LFS-IPFS.md.

---

Radicle Heartwood Protocol & Stack

Heartwood is the third iteration of the Radicle Protocol, a powerful peer-to-peer code collaboration and publishing stack. The repository contains a full implementation of Heartwood, complete with a user-friendly command-line interface (rad) and network daemon (radicle-node).

Radicle was designed to be a secure, decentralized and powerful alternative to code forges such as GitHub and GitLab that preserves user sovereignty and freedom.

See the Radicle home page for general information, and the Zulip chat to talk to the project.

See the Protocol Guide for an in-depth description of how Radicle works.

Installation

Requirements

• Linux or Unix based operating system.
• Git 2.34 or later
• OpenSSH 9.1 or later with ssh-agent

📀 From binaries

Requires curl and tar.

Run the following command to install the latest binary release:

curl -sSf https://radicle.dev/install | sh

Or visit our download page.

📦 From source

Requires the Rust toolchain.

You can install the Radicle stack from source, by running the following commands from inside this repository:

cargo install --path crates/radicle-cli --force --locked --root ~/.radicle
cargo install --path crates/radicle-node --force --locked --root ~/.radicle
cargo install --path crates/radicle-remote-helper --force --locked --root ~/.radicle

Or directly from our seed node:

cargo install --force --locked --root ~/.radicle \
    --git https://seed.radicle.dev/z3gqcJUoA1n9HaHKufZs5FCSGazv5.git \
    crates/radicle-cli crates/radicle-node crates/radicle-remote-helper

Running

Systemd unit files are provided for the node under the /systemd folder. They can be used as a starting point for further customization.

For running in debug mode, see HACKING.md.

Feedback

If you have feedback, feel free to create issues using rad issue, join our Zulip, or email feedback@radicle.dev. Emails sent to this address are automatically posted to our public #feedback channel on Zulip, revealing the From header (which usually contains your name and email address). This allows us to discuss your feedback on Zulip, and, if necessary, respond to you via email.

Contributing

See CONTRIBUTING.md and HACKING.md for an introduction to contributing to Radicle.

License

Radicle is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.