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/lib.rs

Finally, create a patch by recording your changes:

pijul record

Alternatively, one can add and record files in a single record command. For example, importing all the files in a directory named d is done with:

pijul record d

First-Time Setup

Now that pijul is installed and working on your system, you can set your user name, full name, and e-mail address so you don’t have to set it each time you want to record a change.

You can put this information into one of several places; the one you probably want is $HOME/.config/pijul/config.toml (Linux), %AppData%\pijul\config.toml (Windows), or ~/.pijulconfig (MacOS).

Create the file and add the following lines to it:

[author]
name = "<username>"
full_name = "<full name>"
email = "<email address>"

From now on, pijul should pick this up when recording changes and pre-fill the author section for you.

Definitions

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

The differences between the pristine and the working copy are used to produce changes, which can be then applied to the pristine. Changes 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/lib.rs”. 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.