6.4 KiB
(｡•̀ᴗ-)✧ NOTE: open preview to the side in your code editor to view this doc formatted nicely
BIG! (ﾉ◕ヮ◕) url for the radicle repo: https://radicle.network/nodes/iris.radicle.network/rad%3Az3pNdxS2udZaPJjFvAMNA6sxEVvVi
radicle — getting started (team member edition)
radicle is a decentralized alternative to github. instead of pushing your code to github's servers, you push to your local node, which then syncs peer-to-peer with your teammates. no central server, no single point of failure.
wait — same folder as github?
yes. you'll be working in the same local repo directory you already use. radicle doesn't replace your existing github setup — it adds a second destination called rad alongside your existing origin (github).
think of it like having two remotes:
origin → github's servers (the old way)
rad → your local node (the radicle way)
when you push or pull, you need to be explicit about which one you're talking to — otherwise git won't know. more on this below.
install
in your terminal, paste:
curl -sSLf https://radicle.dev/install | sh
downloads and installs the radicle CLI + node binaries into ~/.radicle/bin and updates your PATH automatically.
create your identity
rad auth
generates a cryptographic keypair that identifies you on the network. think of it as your github username — but instead of an account on a server, it's a key that only you hold. you'll set an alias and an optional passphrase to protect it.
rad self
shows your DID (decentralized identifier) — your unique identity on the radicle network. share this with your team so they know it's you.
get the repo
instead of cloning with a github URL, you clone using the repo's RID (repository ID) — a stable identifier that doesn't depend on any server, like a github URL but owned by no one:
rad clone rad:3Az3pNdxS2udZaPJjFvAMNA6sxEVvVi
this sets up a rad remote automatically in that repo directory. you can verify with:
git remote -v
# rad rad://3Az3pNdxS2udZaPJjFvAMNA6sxEVvVi/... (fetch)
# rad rad://3Az3pNdxS2udZaPJjFvAMNA6sxEVvVi/... (push)
💡 not sure what remotes, branches, or patches are? scroll down to "how code collaboration works in radicle" for a plain english explainer.
pushing & pulling — always be explicit
this is the most important thing to get right. because you have two remotes (origin for github, rad for radicle), always specify which one you mean:
git push origin main # → github, as usual
git push rad main # → radicle network
git pull origin main # ← from github
git pull rad main # ← from radicle
never just git push or git pull without specifying — git will guess, and it'll probably guess wrong.
during the transition period, push to both when you want your changes in both places:
git push origin main && git push rad main
daily workflow
git checkout -b my-feature # create a branch for your changes
# ... do your work ...
git add .
git commit -m "did a thing" # save a snapshot
git push rad main # push to radicle
local git work — branching, committing, writing issues and patches — all works offline.
syncing with the network
your node only needs to be running when you want to sync with teammates. start it before pushing or pulling:
rad node start # connect to the network and sync with peers
git pull rad main # pull latest changes from radicle
git push rad main # push your branch so teammates can see it
you don't need it running constantly — only when you want to push, pull, or sync patches and issues.
open a patch (radicle's version of a PR)
once your branch is ready, open a patch with a special git push — this tells radicle to create a patch rather than just push a branch:
git push rad HEAD:refs/patches
this opens your editor (same as writing a git commit message) — the first line becomes the patch title, the rest is the description. your maintainer and teammates will see it once their nodes sync. patches are stored as git objects so they work offline too.
collaboration
rad patch list # see all open patches
rad patch checkout <patch-id> # check out someone's patch locally to review it
rad issue list # see open issues
rad issue open # create a new issue
issues and patches are both local-first — you can read and write them without an internet connection, and they'll sync when you're back online.
how code collaboration works in radicle
commits & branches
a commit is a saved snapshot of your code at a point in time. a branch is a line of commits — a separate workspace where you can make changes without touching the main codebase.
it's highly recommended to work on a branch for bigger tasks, never directly on main:
git checkout -b my-feature # create and switch to a new branch
# ... make changes ...
git add .
git commit -m "did a thing" # save a snapshot
remotes
a remote is just a pointer to where your code lives outside your local machine. you probably already know origin — that's github. radicle adds a second remote called rad, which points to your local node instead of a server.
git push origin main # → github
git push rad main # → radicle (your node, syncs to the network)
git pull origin main # ← from github
git pull rad main # ← from radicle
always be explicit. never rely on git's default remote while you're running both.
patches (radicle's version of pull requests)
a pull request (or PR) on github is a way of saying "i've made changes on my branch — please review and merge them into main." radicle calls these patches.
unlike github PRs which live on github's servers, patches are stored as git objects — they live inside the repo itself, work offline, and don't depend on any server to exist.
once you've pushed your branch, open a patch with:
git push rad HEAD:refs/patches
this opens your editor — first line is the patch title, the rest is the description. your teammates can check it out locally to review, and the maintainer merges it when it's ready.
stuck? jump into the radicle zulip chat #support channel.