Skip to content
This repository has been archived by the owner on May 11, 2023. It is now read-only.

Latest commit

 

History

History
209 lines (146 loc) · 7.63 KB

rad.1.adoc

File metadata and controls

209 lines (146 loc) · 7.63 KB
Raw

rad(1) Manual Page

Name

rad - command-line tooling for Radicle.

Synopsis

rad *

Description

The Radicle CLI is a set of tools designed for users of the radicle peer-to-peer code collaboration stack. The CLI provide the ability to manage radicle identities and publish projects to the radicle network.

Requirements

There are a few important requirements for running the Radicle CLI: first, a recent version of git (2.34.0 or later) must be installed. You can check your installation by running git --version. Second, ssh-agent must be installed and running. Finally, a recent version of OpenSSH (8.0 or later) should be installed. This is to allow for SSH signing functionality which radicle uses to authenticate the user.

Getting started

Let’s see how we can setup a new radicle identity and publish a project to the network.

Once the Radicle CLI is installed, users can create a new radicle identity and key pair. This is usually the first step, and is done via the rad-auth command:

$ rad auth

Follow the instructions by entering a name and password to protect your key pair. When you’ve completed the steps, your Peer ID will be displayed. This identifies your radicle key pair and device, as well as all the code you publish. Share it freely with collaborators.

You may now proceed to creating your first radicle project.

Radicle is built around git, and thus radicle projects must be initialized from git repositories. Navigate to a repository of your choosing and run the following command from within the repository:

$ rad init

You will be asked to enter some basic information about the project. Note that the project name will be determined by the directory name. The newly created project id will be displayed, which is a URN starting with 'rad:git:'. To display it at any time, run rad . from within a radicle project. You may also list all projects on your device with rad ls.

Besides registering the project in your local radicle state, a new remote named rad is added to the repository. This remote points to the project’s location in your local state.

It’s now time to publish your project to the network. To accomplish this, you can use the rad-push command. The first time you run this command, it will ask you where you want your project published, ie. to which seed, and save that choice to your git configuration.

Radicle seeds are peer-to-peer nodes that are accessible on the public internet. They function as replicas for radicle project data. If you would like to use your own seed, specify it with the --seed flag followed by a host, eg. rad push --seed seed.acme.com.

Once set, this seed will always be used when pushing this project. Radicle stores your chosen seed in git, under the 'rad.seed' key. You can view it or edit it with git config rad.seed, or by editing your local git configuration file, .git/config. See git config --help for more information.

With that said, we can run the push command:

$ rad push

This is equivalent to calling git push rad, which pushes your project refs to your local radicle state and then running rad sync, which synchronizes project data between your local state and the configured seed.

Once the command returns, your project source code and metadata should be fully synchronized with your seed.

You may run rad with no arguments to see what additional commands are available.

Contributing to a radicle project

Lets look at how you can contribute code to a project. First, get a hold of the project URN for which you’d like to make a contribution, eg. rad:git:hnrkyghsrokxzxpy9pww69xr11dr9q7edbxfo, and the seed on which this project is hosted, eg. willow.radicle.garden. Usually, the seed will be shown on the project profile, when browsing on the web.

You may then use rad-clone(1) to fetch a fresh copy of the project from the seed:

$ rad clone rad://willow.radicle.garden/hnrkyghsrokxzxpy9pww69xr11dr9q7edbxfo
Syncing project rad:git:hnrkyghsrokxzxpy9pww69xr11dr9q7edbxfo from https://willow.radicle.garden/
Initializing local checkout for rad:git:hnrkyghsrokxzxpy9pww69xr11dr9q7edbxfo (radicle-cli)
...

Note that when specifying a clone URL, the format is rad://<seed-host>/<project-id>. The project id is the URN without the rad:git: prefix.

If the project is found, it will be fetched and a working copy will be created, with the canonical branch checked out. We can inspect the repository and see that it is configured with the seed we have cloned it from:

$ cd radicle-cli
$ git config --local rad.seed
https://willow.radicle.garden/

We can also check what radicle remotes are configured:

$ rad remote
cloudhead hyn9diwfnytahjq8u3iw63h9jte1ydcatxax3saymwdxqu1zo645pe delegate

This tells us that there is one remote setup, which is one of the project delegates. A delegate is a peer who can sign on behalf of the project. These can be trusted within the context of a project. The name of the delegate as well as the id (also known as Peer ID) is shown.

Now let’s commit a change to the README:

$ vim README.md
$ git add README.md
$ git commit -m "Update README.md"

And push it to the seed:

$ rad push
Syncing project rad:git:hnrkyghsrokxzxpy9pww69xr11dr9q7edbxfo to https://willow.radicle.garden/
...

Your changes will be pushed to a sub-tree of the project on the seed node, which will be namespaced under your Peer ID. To check what your Peer ID is, run:

$ rad self
...
Peer ID  hybgwwnx3x94rk6afxygj35jh3fktnwirs44a1t5emdh4uxmiku18q
...

The remote seed now has two source trees: one by the project delegate, and one by you. Your master branch is further along the canonical branch by one commit.

You may share your Peer ID with a project maintainer to have them take a look at your contribution.

Merging project contributions

In the previous section we looked at the contributor flow. Now let’s look at how contributions can be merged back into the project by playing the role of a maintainer.

Project maintainers will most often be delegates, this helps as delegate branches are fetched by default via rad-clone(1) and automatically tracked.

As a maintainer, the first thing you will want to do is to find out if there is any code published on the seed node that you may be interested in. To do this, you can use rad-track(1) without specifying a peer. This will query the seed node and return the list of contributors and branches:

$ rad track --seed willow.radicle.garden
hybgwwnx3x94rk6afxygj35jh3fktnwirs44a1t5emdh4uxmiku18q bob
└── master 26fc90625774bc6e219bb15b51f5f9f51d26248b Update README.md
...

You may omit the --seed argument if it is the default seed for this project, but you must then pass the --remote flag to indicate that you’d like to query remote data.

Here we can see the earlier contribution we made and the id of the peer that made it. If we’re interested in viewing this commit and potentially merging it, we can start by tracking the remote peer from our working copy:

$ rad track hybgwwnx3x94rk6afxygj35jh3fktnwirs44a1t5emdh4uxmiku18q

This will setup a remote in our working copy, as well as a tracking branch named after the peer and project default branch, eg. peers/bob/master.

To see what changes were contributed, we can diff the remote branch against our master:

$ git diff master..peers/bob/master

If we’re happy with these changes, we can merge them and publish our new head:

$ git merge peers/bob/master
$ rad push

And we’re done!

Copyright

Copyright The Radicle Team <[email protected]> and contributors.