Guide / Set up a project

Files Penstock reads and writes

A complete list of the files Penstock reads, writes and keeps, and where each one lives.

Free

In your project

File	What it is	Commit it?
`penstock.yaml` (also `.yml`, `.json`)	The project's settings. Read from every folder from the root down to the diagram.	Yes
`penstock.local.yaml`	This machine's settings, and the engine address you type into the Connection dialog.	No. Penstock adds it to `.gitignore`.
`.bpmnlintrc`	Your bpmnlint rules.	Yes
`.camunda/element-templates/`	Element templates, read from next to a diagram and every folder above it.	Yes
`penstockw`, `penstockw.cmd`, `penstock/wrapper/penstock-wrapper.properties`	The command line wrapper and the version it pins.	Yes
`penstock-baseline.json`	The problems the project already has. Written by `penstock check --update-baseline`.	Yes
`.penstock/runs/`	Traces of test-case runs. It has its own `.gitignore`.	No
`.penstock/images/`	Pictures from `penstock diff --images` and `penstock report`.	No
`penstock-report.md`	The pull request report written by `penstock report`.	No
`.bpmn`, `.dmn`, `.form`	Your diagrams, decisions and forms. Penstock edits them in place.	Yes

In your home folder

Penstock keeps its personal files in ~/.penstock. If the environment variable PENSTOCK_HOME is set, they are under that folder instead. Every tool on the machine shares them.

File	What it is
`preferences.json`	Your toolbar choices, whether the tour was seen, the width of the sidebar and the tab you left selected, Sketchy drawing, tree or flat view of the project model, and the last export format.
`license.json`	The signed licence token and a clock mark, never a key, a tier or a date you could edit. Readable only by you. See Buying and signing in.
`clock.json`, `pipeline.json`	The latest time the machine has seen, kept beside the licence so a clock set back is noticed, and the short-lived token of a pipeline run.
`trusted-projects.json`	The projects you have trusted to run a deploy hook, the project's command line and its lint rules. Trusting in one tool trusts in the others. Settings in your tool list them, and `penstock trust --list` prints them.
`connectors/<release>/`	The Camunda connector templates downloaded from GitHub.
`wrapper/dists/<version>/`	The command line versions the wrapper downloaded.
`test-builds.json`	A list of test builds a test-case run deployed, so the next run can remove what an interrupted one left.

Not in a file

The password or client secret for a deployment profile lives in the secret store of your tool. It is never written to a file.

Where the secret lives

JetBrains

The IDE password safe, once for each profile. Older versions also kept settings in .idea/bpmn-project.xml. That file is legacy. Penstock offers to move its settings into penstock.yaml.

VS Code

VS Code's secret storage, once for each workspace, profile and field. Nothing is written to a file.

Command line

There is none. Give the secret to a command through the environment: PENSTOCK_PASSWORD, PENSTOCK_CLIENT_SECRET or PENSTOCK_TOKEN.

How to remove everything

Remove Penstock from your tool. See below.
Delete ~/.penstock.
In your projects, delete the files above that you do not want.

Remove Penstock from your tool

JetBrains

Open Settings | Plugins and the Installed tab, choose Penstock, press Uninstall and restart the IDE. Your diagrams stay as they are.

VS Code

Open the Extensions view, find Penstock and press Uninstall. Your diagrams stay as they are. See Installing in VS Code.

Command line

Delete penstockw, penstockw.cmd and penstock/wrapper from your project. If you installed the command with npm, run npm uninstall -g @kern0x1b/penstock-cli. penstock init --hooks wrote a pre-commit hook into .git/hooks: delete that file too. Penstock keeps a few small files of its own in ~/.penstock, which you can delete.

What you see

After a few days of use, ~/.penstock holds preferences.json and license.json, and maybe connectors and trusted-projects.json.
Your projects hold penstock.yaml and, if you ran init, the wrapper files.

Common problems

My toolbar differs between two computers.: preferences.json is per machine. It does not sync.
I want the settings somewhere else.: Set PENSTOCK_HOME to another folder, for example on a shared drive. Then every tool uses that folder.
Git shows penstock.local.yaml as new.: Add it to .gitignore. penstock init does this for you.