Here is how to start a project with Pijul: first run the following command:
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
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
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,
initialised an empty pristine.
pijul add then updated the
tree, to tell Pijul to start tracking files "Cargo.toml" and
pijul record compared the (currently
empty) repository with the working copy, producing a patch as a result,
and applied this patch to the pristine.
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.