Let me try to explain a very simple list of basic definitions, in the order you are likely to use them:
pijul init creates a “repository”, which you can see as an archive of all the changes you have applied to your project since the beginning, along with a list of files that Pijul is currently interested in.
pijul add Cargo.toml src/lib.rs would be the command I run if I want to let Pijul know that I want to track the two files named
src/lib.rs. If you have many more files to add, see
pijul add --help.
pijul record will create a change (also called a patch) and apply it to the repository. That command will ask you to create a signing key with
pijul key generate. Patches are signed by default in Pijul (this isn’t enforced very well at the moment, the Nest doesn’t show the validation, for example).
- See what you’ve done:
pijul log and
pijul change are probably your next steps.
- Changes are the central concept in Pijul. You can push them to the Nest: if you have created a repository called
foo in your account (let’s say
Justin is your login), you can do
pijul push Justin@ssh.pijul.com/foo to push your change there. This requires you to have uploaded your SSH public key first.
The next useful command you might need is
pijul unrecord, which actually “unapplies” rather than “unrecords” patches, since your patch still exists in
.pijul/changes after that.
As @joyously said, we also have a slightly confusing concept called “channels”. A channel is a name associated to an evolving set of patches. I personally don’t use them very often in public. They took me a significant effort to implement, as I had to write an entire database backend from scratch in order just to implement them. I initially wrote them to make it easier to Git user to start understand why they don’t need them (like “I’m not telling you patches are better than branches because I can’t have them, but rather because patches actually are better”). Here are two ways in which I found channels useful:
- In Rust, when I wanted to maintain versions of Thrussh (my SSH library) compatible with multiple versions of Tokio (while the Tokio ecosystem was transitioning to 1.0), and apply the same patches to both versions.
- There are times where I want to prepare a complicated patch, or squash multiple patches together, or review a patch submitted on the Nest. In these cases, I often find that forking my
main channel temporarily makes the operation easier.
Channels are a different from Git branches in multiple ways, the main one being that you can’t merge channels, whereas merging branches is the primary way through which a Git project progresses. While Git has many commands to deal with branches and try to simulate patch commutation, Pijul can deal with all that complexity (and more) by just applying and unapplying patches.
Most uses of Git branches are just patches in Pijul, since branches are usually meant to keep different features separate, merge them, and push them independently.