# Configuration

Pijul is configured using `config.toml` files; users can take advantage of both global and repository-specific configuration.

## Global configuration

The location of Pijul's global configuration depends on the conventions of the user's operating system;
Pijul will first try to instantiate a global configuration in the user's configuration directory according to
[this table](https://docs.rs/dirs-next/2.0.0/dirs_next/fn.config_dir.html).
If pijul cannot access the conventional config location, it will fall back to the
[home directory](https://docs.rs/dirs-next/2.0.0/dirs_next/fn.home_dir.html), using `$HOME/.config/pijul`.
If that fails, `$HOME/.pijulconfig` will be tried as a last resort.

### Global configuration data

Pijul supports the following global config values:

| Key                | Description                                                    | Format                        |
|--------------------|----------------------------------------------------------------|-------------------------------|
| `colors`           | If Pijul should display colorful output                        | [Choice](#choice)             |
| `pager`            | If Pijul should use a pager (eg `less`) to display diff output | [Choice](#choice)             |
| `unrecord_changes` | How many changes to show when runnning `pijul unrecord`        | Number                        |
| `author`           | Set the default author details                                 | [Author](#author)             |
| `template`         | Set a default template when using `pijul record`               | [Template](#template)         |
| `ignore_kinds`     | Set default ignore files when using `pijul init --kind=<KIND>` | [Ignore kinds](#ignore-kinds) |

Here is an example of a fully-configured `config.toml`:
```toml
colors = "always"
pager = "always"
unrecord_changes = 1

[author]
name = "ferris"
full_name = "Ferris the Crab"
email = "ferris@example.com"
key_path = "/home/ferris/.ssh/id_ed25519.pub"

[template]
message = "/home/ferris/Documents/a_custom_message_for_me.txt"
description = "/home/ferris/Documents/a_custom_description_for_you.txt"

[ignore_kinds]
rust = [ "target" ]
```

#### Author

You can give Pijul some basic information to identify yourself using any of the following fields:
```toml
[author]
name = "<REMOTE USERNAME>"
full_name = "<DISPLAY NAME (optional)>"
email = "<EMAIL (optional)>"
key_path = "<PATH TO SSH PUBLIC KEY (optional)>"
```

Unlike many other version control systems, Pijul does not permanently assign these details to changes.
For more information please reference [the section on keys](keys.md).

#### Template

If you have a file containing some default text,
Pijul can automatically load those files into the relevant fields using the following configuration:
```toml
[template]
message = "<MESSAGE FILE PATH (optional)>"
description = "<DESCRIPTION FILE PATH (optional)>"
```

#### Ignore Kinds

Pijul can be configured to automatically set up the [`.ignore` file](#ignore) when running `pijul init --kind <KIND>`.
Here is an idea of what it might look like in practice:
```toml
[ignore_kinds]
rust = [ "target", "*.perf" ]
python = [ "dist", "build", "eggs" ]
```

## Repository configuration

Users can take advantage of repository-specific configuration by editing the appropriate toml file: `<repo>/.pijul/config`.
Repository-specific configuration settings have a higher precedence than global configuration settings.
Pijul supports the following repository config values:

| Value                | Description                                                      | Format              |
|----------------------|------------------------------------------------------------------|---------------------|
| `colors`             | If Pijul should display colorful output                          | [Choice](#choice)   |
| `pager`              | If Pijul should use a pager (eg `less`) to display diff output   | [Choice](#choice)   |
| `unrecord_changes`   | How many changes to show when runnning `pijul unrecord`          | Number              |
| `default_remote`     | The default remote to interact with                              | String              |
| `extra_dependencies` | Extra changes that should always be depended upon                | List[String]        |
| `remotes`            | Named remotes that can be interacted with                        | [Remotes](#remotes) |
| `hooks`              | Hooks to run before recording a change                           | [Hooks](#hooks)     |

Here is an example of a fully-configured `.pijul/config`:
```toml
colors = "always"
pager = "always"
unrecord_changes = 1
default_remote = "ferris@ssh.pijul.com:pijul/pijul"
extra_dependencies = [ "SXEYMYF7P4RZMZ46WPL4IZUTSQ2ATBWYZX7QNVMS3SGOYXYOHAGQC" ]

[remotes]
mirror = "ferris@ssh.example.com:pijul/pijul"

[hooks]
record = [ "cargo fmt" ]
```

#### Remotes

A remote is simply a named URL of a Pijul repository.
For more information please reference [pijul remote](reference/remote.md).

#### Hooks

A hook is a script run in the default shell before a command is executed.
Currently only `pijul record` is supported.
Here is an example:
```toml
[hooks]
record = [ "cargo fmt" ]
```

## Choice

A choice in Pijul can have 3 possible values:
1. `auto`
2. `always`
3. `never`

When no value is supplied, this will default to `auto`.
In that case, Pijul will automatically determine which choice to pick.
For example, if your global configuration contains `colors = "auto"`, Pijul automatically use colored output when appropriate.

## Ignore

Items in a repository can be ignored by editing a repository's `.ignore` file.
Pijul supports standard glob syntax in `.ignore` files.