Getting started

Here is how to start a project with Pijul: first run the following command:

pijul init

In the project's directory. This creates a directory called ".pijul", and initialises a few things.

Then, add a few files to track. For a Rust project, this could be for instance:

pijul add Cargo.toml src/

Finally, create a patch by recording your changes:

pijul record

Let's see what happened under the hood in this simple example:


Pijul works in four different places of your hard drive: a working copy, where you can edit files, a set of patches, a tree, which is the set of files currently tracked by Pijul, and a pristine, which is a representation of the current recorded version of the repository.

The changes between the pristine and the working copy are used to produce patches, which can be then applied to the pristine. Patches encode edits made to files of the repository (line insertions and deletions), as well as file additions, deletions and name changes.

At any time, the pristine can be output into the working copy, for instance after receiving new patches, or to cancel changes and reset the working copy to its recorded state.

So, the first command of the above example, pijul init, initialised an empty pristine. pijul add then updated the tree, to tell Pijul to start tracking files "Cargo.toml" and "src/". Finally, pijul record compared the (currently empty) repository with the working copy, producing a patch as a result, and applied this patch to the pristine.

Next steps

In the next chapter, we will see how to exchange patches with others.

Collaboration with Pijul doesn't have to be centralised, and is not even made easier by centralisation, as patches allow for a completely distributed workflow, which can happen even by email exclusively.

However, the authors of Pijul provide a free web service called the Nest, as one way to share patches with collaborators.