Command line configuration
How the command line finds your repository settings, which commands use which part of them, and how an option on the command line and a setting combine. The fields of the file are in Repository settings; this page is about how plotwork reads it.
TL;DR
| Question | Answer |
|---|---|
| Where does the file go? | plotwork.config.json at the repository root, or .plotwork/config.json. |
| How is it found? | --config <file>, else the file PLOTWORK_CONFIG names, else the nearest plotwork.config.json or .plotwork/config.json from the diagram's folder up to the folder that holds .git. |
| Is a file required? | No. Without one, every command draws with the built-in defaults. Only check needs rules, and generate needs sources. |
| Does an option on the command line win? | Yes. A flag wins over the settings, and the settings win over the built-in defaults. A diagram's own header wins over the settings' defaults. |
| What else is configured? | Only environment variables, listed in Environment variables. There is no other file and no per-user setting. |
1. A minimal file
{ "$schema": "https://docs.plotwork.dev/schemas/plotwork.config.json", "defaults": { "direction": "down", "icons": "auto" }, "rules": { "requireTitle": true, "maxNodes": 40 }}With $schema, an editor completes the fields and underlines a mistake. The file needs no account and is never sent anywhere.
2. Which commands read what
| Section | Read by | What it does there |
|---|---|---|
defaults | sync, validate, check, render, outline, generate | Fills each header option a diagram leaves out, before the diagram is checked or drawn. |
rules | check | The style rules the diagrams are checked against. --org replaces them with an organisation's saved rules; the defaults still apply. |
sources | generate | The diagrams made from files of the repository. See Diagrams as code. |
brand | None | Read by hosted calls only. The command line draws in the built-in themes. |
read, import, import-source, export, and icons read no settings.
3. How the file is found
Each command looks for the settings of each file it reads, in this order, and uses the first it finds:
| Order | Where | Use it for |
|---|---|---|
| 1 | --config <file> | One run with other settings, such as a stricter rule set in CI. |
| 2 | The file PLOTWORK_CONFIG names | A CI job or a shell that always uses the same file. |
| 3 | plotwork.config.json, then .plotwork/config.json, in the file's folder and each folder above it, up to the folder that holds .git | The usual case: one file at the root of the repository. |
Because the search starts at each file, a repository of many packages can keep a settings file in a package's folder, and sync "**/*.md" applies the nearest one to each page. generate reads one file: the first found from the working folder up, and the paths in its sources start from that file's folder.
A file that does not check stops the command with exit code 2, and each problem is printed with its line and column in the file.
4. Options and settings together
| What | Order, first wins |
|---|---|
A header option of a diagram, such as direction | The diagram's header, then defaults, then the built-in default |
The theme of render | --theme, then defaults.theme, then light |
Whether render embeds the source | --no-embed-source, then defaults.embedSource, then embedded |
The pictures sync and generate write | A source's own schemes, then defaults.schemes, then light-and-dark (a light and a dark SVG); auto writes one SVG that follows the reader's setting |
The rules of check | --org or PLOTWORK_ORG, then rules |
A change to defaults changes the pictures of every diagram that leaves those options out, so sync --check reports them stale until sync redraws them. Change the file and run sync in the same commit.
See also
| Doc | Why |
|---|---|
| Repository settings | Every field of the file, the rules, and sharing rules across repositories |
| Environment variables | The variables the command line reads |
| Diagrams as code | The sources section and generate |
| Command reference | Every option of every command |