# 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](https://rust-lang.org)
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 identities](identities.md).

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
```

If you need to check what parts of repository aren't recorded, you can use:

```
pijul diff --short --untracked
```


## 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). Information about the configuration hierarchies used by pijul can be found
in the [manual section on configuration](configuration.md).

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.

## Ignoring files

You may want pijul to ignore some files (binary, extra dependencies for examples).
This can be done by creating a `.ignore` file in the root directory.

## 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](./working_with_others.html), 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.