# plotwork sync

> Page: https://docs.plotwork.dev/cli/commands/sync. Index of every page: https://docs.plotwork.dev/llms.txt

Draw the pictures under every diagram fence of Markdown files; `--check` fails when one is stale. It is a command of the Plotwork command line, the npm package `@buun_group/plotwork`.

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Draw the pictures under every diagram fence of Markdown files; `--check` fails when one is stale. |
| How do I run it? | `npx -y @buun_group/plotwork@0.1.0 sync`, or `plotwork sync` once the package is installed. |
| What does it write? | The Markdown files and their SVGs, unless `--check` is given. |
| Does it use the network? | No. It reads and writes files on this machine only. |
| Does it read the repository settings? | Yes: the header defaults of the settings file apply to every diagram. See [Configuration](https://docs.plotwork.dev/cli/configuration.md). |
| How do I read this in a terminal? | `plotwork sync --help` |

## Synopsis

```sh
plotwork sync <files...> [--check] [--assets <dir>] [--prefix <text>] [--format text|github] [--config <file>]
```

## What it does

Draws every `diagram` fence of the Markdown files as a light and a dark SVG, and writes the picture block under the fence, so the diagram shows on GitHub, GitLab, and any Markdown viewer. A fence whose picture is already current is left as it is.

Each word is a Markdown file, a folder (every `.md` file under it), or a quoted glob such as `"docs/**/*.md"`. The command expands the glob itself, so it means the same in every shell, and never looks in `node_modules`, `.git`, or build output.

With `--check` it writes nothing and exits 1 when any picture is missing or stale, or any diagram has a mistake. That is the check to run in CI.

## Options

| Option | Default | What it does |
|---|---|---|
| `--check` | Off | Write nothing; exit 1 when a picture is missing or stale, or a diagram has a mistake. |
| `--assets <dir>` | `assets/diagrams` | The folder the SVGs are written to, relative to each Markdown file. |
| `--prefix <text>` | the Markdown file name | The start of each SVG file name and picture id. |
| `--format text\|github` | `text` | `github` prints each stale fence and each mistake as a GitHub annotation on its line. |
| `--config <file>` | `PLOTWORK_CONFIG`, else the nearest `plotwork.config.json` or `.plotwork/config.json` from the file up to the repository root | The repository settings file to read: header defaults, and the style rules check applies. |

## Examples

Draw every diagram of the README and the docs folder, and write the pictures.

```sh
plotwork sync README.md "docs/**/*.md"
```

Fail when any picture is stale, and write nothing.

```sh
plotwork sync --check "docs/**/*.md"
```

The same in a GitHub workflow, with an annotation on each stale fence.

```sh
plotwork sync --check --format github "**/*.md"
```

## Exit codes

| Code | When |
|---|---|
| `0` | Every picture is current (with `--check`), or every picture was written. |
| `1` | A picture is stale (with `--check`), or a diagram has a mistake and was not drawn. |
| `2` | 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. |

## See also

| Doc | Why |
|---|---|
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every command of the command line |
| [Markdown and GitHub](https://docs.plotwork.dev/markdown-and-github.md) | How a fence and its picture block look in a page |
| [CI usage](https://docs.plotwork.dev/cli/ci.md) | The check in every CI system |
| [Exit codes and output formats](https://docs.plotwork.dev/cli/exit-codes-and-output.md) | What every code and format means |