Exit codes and output formats
What each exit code of the command line means, for every command, and what each --format prints. A script or a CI step reads the code; a person reads the text; a code scanner or a test view reads a report.
TL;DR
| Question | Answer |
|---|---|
| What are the exit codes? | 0 all is well, 1 a problem in a diagram, 2 a mistake in the command line. |
| Why two failure codes? | A CI step fails on both, and a script can tell a diagram that needs fixing from a command that needs fixing. |
| Where do mistakes go? | Standard error, each with its file, line, column, code, and a hint. Standard output holds the result: a source, a report, or a summary line. |
| Which formats are there? | text (the default), github, json, sarif, and junit, each on the commands that take it. export has its own formats for wikis. |
| Is the JSON report stable? | Yes. It carries a version, and its JSON Schema is published. A change that breaks a reader gets a new version. |
Exit codes
| Code | Meaning | Examples |
|---|---|---|
0 | All is well. | Every picture is current, every diagram is valid, the source was written. |
1 | A problem in a diagram. | A stale or missing picture, a syntax error, a broken style rule, a generated diagram that drifted, a picture with no source to read. |
2 | A mistake in the command line. | An unknown option, a missing operand, a glob that matches nothing, a settings file that does not check, generate with no sources. |
Each command says what the codes mean for it:
For every command, code 2 is a mistake in the command line: an unknown option, a missing operand, a file or glob that matches nothing, or a settings file that cannot be read. The last column says what else it means for that command.
| Command | 0 | 1 | 2 |
|---|---|---|---|
sync | Every picture is current (with --check), or every picture was written. | A picture is stale (with --check), or a diagram has a mistake and was not drawn. | Nothing more. |
validate | Every diagram is valid. | A diagram has an error, or a warning with --strict. | Nothing more. |
check | No rule at level error is broken. | A rule at level error is broken, a diagram has an error, or the saved rules could not be read. | Also when no rules are found, or --org is given with no key. |
render | The SVG was written. | The diagram has an error, or the file holds no diagram. | Nothing more. |
read | The source was printed or written. | The picture carries no source, the source has errors, or a hosted link could not be read. | Nothing more. |
outline | Every diagram was outlined. | A diagram has an error. | Nothing more. |
generate | Every diagram is in step (with --check), or every diagram was written. | A diagram drifted (with --check), or a diagram has an error. | Also when there are no settings, no sources, or --since names a ref git does not know. |
import-source | The source was printed or written. | Nothing could be imported from the file. | Also when the format or a value of --view, --chart, or --group-by is not one it knows. |
import | Everything converted. | A diagram or a fence could not be converted, or the file could not be read. | Also when the file is not .mmd, .mermaid, or Markdown. |
export | The text was printed or written. | The diagram has an error. | Also when --format is missing or --image is not an https address. |
publish | Every diagram was saved, and its link printed. | A diagram has a mistake (nothing is sent), the API refused one (its code and words are printed), or the API could not be reached. | Also when PLOTWORK_API_KEY is missing or refused, --personal and --org are both given, or --alias is given for a file with several diagrams. |
icons | The search ran, whether or not anything matched. | Not used. | No query was given. |
Output formats
| Format | Commands | What it prints |
|---|---|---|
text | sync, check, generate, import-source, import | Lines a person reads. Mistakes go to standard error with a line, a column, and a hint. |
github | sync, check, generate | GitHub workflow commands: each problem is an ::error or ::warning annotation on its file and line in the pull request. |
json | generate, import-source, import | One JSON document on standard output, for a script. generate writes its versioned report, whose JSON Schema is at https://docs.plotwork.dev/schemas/plotwork.report.json. |
sarif | generate | A SARIF 2.1.0 report for code scanning, such as GitHub code scanning or Azure DevOps. |
junit | generate | A JUnit XML report: one test case for each source, failed when its diagram drifted or has an error, for the test view of GitLab, Jenkins, CircleCI, or Azure Pipelines. |
confluence | export | Confluence storage format (XHTML): the format of Confluence's REST API and of a page's source in Data Center. |
confluence-wiki | export | Confluence wiki markup, which the Cloud editor takes through Insert, then Markup. |
notion | export | Markdown that Notion turns into an image block and a code block when it is pasted. |
text
The default. Each mistake is printed as the engine reports it: the code, the message, the line of the diagram with a caret under the column, and a hint. Under it, at file line names the line in the file, so an editor can jump to it. The last line is a summary, such as up to date: README.md or ok: 3 diagram(s) checked, 0 drifted, 0 error(s).
github
GitHub workflow commands (opens in a new tab). A line such as the one below becomes an error on line 12 of the file in the pull request's Files changed tab:
::error file=docs/architecture.md,line=12,title=Stale diagram::The picture under this diagram is missing or out of date.The file is named from the working directory, which in a workflow is the repository root. Run the command from the root, or the annotations will not find their files.
json
One JSON document on standard output and nothing else, so it can be piped to jq. import and import-source print the conversion with its diagnostics. generate prints its versioned report: each diagram, whether it drifted, what changed by meaning, its CODEOWNERS owners, and where the run happened. The schema is at plotwork.report.json (opens in a new tab).
sarif and junit
Reports from generate for tools that already show findings. SARIF goes to code scanning, where a drifted diagram is an alert on its file. JUnit goes to a test view: each source is a test case that fails when its diagram drifted or has an error. With --out <file> the report is written to the file and the terminal gets the text a person reads, so the log still says what drifted.
See also
| Doc | Why |
|---|---|
| CI usage | Each format in a pipeline |
| Command reference | Every command and its options |
| Troubleshooting | What to do about a failure |