What Pinman will and won't change

Short answer: out of the box, Pinman changes nothing on your machine. It reads and records. It writes only when you allow it, and it tells you before it writes if it can't.

---

Pinman's own files are always written#

Its database, captures and backups are Pinman's own files. Nothing below applies to them.

Machine read-only is on by default#

With Machine read-only on, applying, undoing or running a profile only previews: you see what would change, and nothing is written. A Machine read-only chip in the top bar shows it is on.

To write anyway:

• One action: check Disable read-only for this action, or add --allow-writes on the command line.
• Always: turn it off on the Config page, or run pinman config set machine_readonly false.

See Config.

How Pinman changes application data#

Pinman changes application data only when you start a write action:

• Profile Apply sets the values declared by a profile. Profile Run carries out the steps in a sequenced profile. Profile Undo restores the values saved before a profile was applied.
• A profile's p.file() target copies an entire asset file or directory to a tracked destination. It can copy any file format because Pinman compares and copies the bytes rather than editing settings inside the file.
• Restore can put back individual settings through their format adapters or replace a whole file with the bytes retained by a capture.
• Explorer and operator controls can change an individual tracked setting.

For the formats Pinman can edit as structured settings, see Supported file formats.

What Pinman records#

Pinman records each kind of change in the place suited to that operation:

• Before Profile Apply or Run writes anything, Pinman creates an Undo history record. When the operation finishes, Pinman adds a Journal entry describing the outcome.
• A Restore that puts anything back adds a Journal entry identifying the source capture and, when applicable, the Savepoint holding what it replaced.
• Pinman adds an individual Explorer or operator-control edit to the application log and re-reads the setting into the Head. These edits do not create profile history, a Journal entry or an Undo action.

The result of each operation reports refusals and failures. The application log contains additional diagnostic detail. Use pinman log show to inspect it and pinman profile history to inspect profile apply history.

Why a change can be refused#

Pinman checks before it writes and lists every reason at once, so fixing one never uncovers the next.

Reason	What it means	What to do
Read-only is on	You turned on Machine read-only (or Operator read-only).	Allow this one action, or turn it off in Config.
The kit marks it read-only	Whoever wrote the kit chose to protect this setting.	Leave it, or change the kit.
Windows won't allow it	The file is read-only, or you lack permission to change it or its folder.	Fix the file's setting or permissions, then try again.
Pinman can't change this format yet	Pinman reads this kind of file but does not write it.	Edit the file yourself.
A Pinman service isn't running	The change goes through a Pinman helper that is stopped.	Start Pinman's services, then try again.
No Savepoint holds it	Restore would replace a file or setting no Savepoint holds as it is now, so it could not be undone.	Take a Savepoint first, or choose to overwrite anyway.

In the Explorer, a lock on a setting means it would be refused. Hover over the lock to see why.

When something goes wrong part way#

• Undo is all or nothing. If any part would be refused, nothing is undone, and you see why.
• Restore skips what the kit marks read-only or what Pinman can't change, lists it, and restores the rest.
• Physical display revert (the countdown after changing monitor or screen settings) puts back everything it can, so a bad display setting never leaves you stuck.
• A file another program has open can only be found when Pinman tries to write it. Close the program and try again.