Here is how to start a project with Pijul: first run the following command:
In the project’s directory. This creates a directory called
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
Before recording, new users will need to generate a key using
pijul key generate <name>.
Users can read more about keys in the manual section on keys.
Finally, create a patch by recording your changes:
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
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
%AppData%\pijul\config.toml (Windows), or
~/.pijulconfig (MacOS). Information about the configuration hierarchies used by pijul can be found
in the manual section on configuration.
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.
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
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.