Guides

Registry (winreg)

Scope: What Belongs in winreg:#

Pinman's winreg: realm tracks Windows Registry keys and values. This covers what to track, the available CLI tools, blacklist maintenance, and the inventory/discovery/diagnostics modes. For schema authoring syntax see the Schema format reference.

Belongs here	Does NOT belong here
Pinball software settings — VPX, VPinMAME, DOF, B2S, PinUP, etc.	Display, audio, GPU, input, power settings → `winrt:` realm
User-installed tools — JoyToKey, AutoHotkey, DisplayFusion, PinVol	Open-ended discovery of the entire registry
Specific Windows tweaks — auto-login, startup apps, compatibility flags

When in doubt: if the setting is exposed by a Windows API (display resolution, audio volume, power plan), it belongs in winrt:. If it's a HKCU\Software\* or HKLM\SOFTWARE\* app setting, it belongs in winreg:.

Adding Registry Keys to Your Schema#

Define keys in schema YAML. Pinman auto-creates hive containers and backfills intermediate keys during import:

- program: VisualPinball
  items:
    - location: "winreg:/HKCU/Software/Visual Pinball"
      itemtype: winreg_key
      schema_props:
        include_match: ["*"]
        exclude_match: ["*Cache*", "*Temp*"]

# Standalone entry (Windows tweak, user tool)
- location: winreg:/HKCU/Software/Microsoft/GameBar
  label: Windows Game Bar Settings
  include_match: ["*"]

See the Schema format reference for full syntax.

CLI Tools#

Analysis and Inspection#

Command	Purpose
`pinman winreg inventory`	List `winreg:` schema entries and check if keys exist on this system
`pinman winreg search <pattern>`	Search keys/values in cached `.reg` files or live registry
`pinman winreg diff <file1> <file2>`	Compare two `.reg` files; `--live` to compare a file against the live registry
`pinman winreg watch`	Capture before/after snapshots around a specific action to see what changed
`pinman winreg stats`	Key and value counts by hive
`pinman winreg clear-cache`	Delete cached `.pkl` sidecar files from `extract/winreg/`

All inspection commands take -o human|json (and winreg show also -o reg); machine modes put the payload on stdout and chrome on stderr.

Blacklist Management#

Command	Purpose
`pinman winreg blacklist list`	List all key and value patterns
`pinman winreg blacklist audit`	Show per-pattern hit counts; find dead patterns (zero hits)
`pinman winreg blacklist test <pattern>`	Test a candidate pattern against cached data before adding it
`pinman winreg blacklist add/remove <pattern>`	Mutate the shared blacklist (force-gated: `--force`)
`pinman winreg blacklist optimize`	Remove patterns covered by a broader wildcard (`--dry-run` to preview)
`pinman winreg blacklist export`	Export patterns filtered by `--scope` (`--file` to save)
`pinman winreg blacklist check`	Find schema items blocked by a pattern (`--fix` to remove them)

Discovery and Diagnostics#

Command	Purpose
`pinman winreg discover baseline [--root-key PATH]`	Capture current registry state as a baseline (force-gated; overwrites)
`pinman winreg discover changes`	Show what changed since the last baseline

Registry Modes#

Mode 1 — Inventory#

pinman winreg inventory

Lists winreg: entries from your schema and checks whether each key actually exists on this system. Reports present/not-found status with value counts. Useful for verifying a schema on a new cabinet or after software changes.

Mode 2 — Discovery#

pinman winreg discover baseline
pinman winreg discover changes

Capture a broad registry snapshot, make changes (install software, adjust settings), then diff to see exactly what changed. Output is designed to help identify new keys worth adding to your schema. Uses relaxed blacklist filtering (discovery mode: verified patterns only) to preserve diagnostic signal.

Extraction Modes#

Captures (backups, checkpoints, compare-scans) use two modes:

Mode	Flag	Speed	What's captured	Blacklist
Scoped	default	< 1 s	All schema-tracked keys — not bounded by `allowed_subtrees`	Not applied — keys are explicitly chosen by the schema
Full	`--full`	~50 s	Scoped output + `allowed_subtrees` top-level subtrees, blacklist-filtered	Applied

Scoped mode is the default and sufficient for snapshots and profile operations. The blacklist has no effect on scoped extraction — if a key is in your schema, it will always be captured. This applies even if the key's registry path lies outside the allowed_subtrees full-sweep scope (e.g. HKCU\System\...): scoped extraction reads those keys directly via the Python winreg API and writes them to _schema.reg. They simply won't appear in the broader per-subtree .reg files produced by a full backup.

Full mode is for backups where you want the complete historical record. allowed_subtrees defines which top-level subtrees are swept; the blacklist trims noise from that broader dump.

Blacklist Maintenance#

The blacklist (winreg_blacklist.jsonc) suppresses noise — registry changes that occur autonomously and tell you nothing useful. Without it, consecutive backups with no intentional changes would look different because of timestamps, counters, and Windows housekeeping.

Goal state: Consecutive full backups with no intentional system changes should produce identical extract files for all hives, enabling hash-match skip (unchanged hives aren't re-backed-up).

Noise vs Signal#

The diagnostic test for any change: "Would seeing this change help answer what changed on my system?" If the only conclusion is "time passed" or "Windows ran a scheduled task," it's noise. If it could indicate a config change, hardware event, driver update, or service failure, it's signal — keep it.

Noise (blacklist): MRU timestamps, Group Policy cycle IDs, Defender scan times, network profile signatures, telemetry check-in times, disk space counters, audio driver debug logs.

Signal (keep even if not pinball-relevant): Reliability Monitor events, boot/recovery config, device enumeration, service configuration, driver keys.

Relevance is the schema's job. The blacklist removes noise from backups entirely. Signal that isn't pinball-relevant stays in the backup (available for troubleshooting) but outside the schema (not actively tracked).

Workflow: Adding New Patterns#

1. Find noise. Run two consecutive full backups with no intentional changes between them, then diff the extract files:

diff backup_000005/winreg/HKEY_LOCAL_MACHINE_SOFTWARE.reg \
     backup_000004/winreg/HKEY_LOCAL_MACHINE_SOFTWARE.reg

Any differences are noise not yet covered by the blacklist.

2. Triage by hive file. Check which extract files hash-differ. Focus on the big files first — HKLM_SOFTWARE (~94 MB) and HKLM_SYSTEM (~60 MB) have the most impact.

3. Identify the path. For each diff hunk, find the [HKEY_...\path\to\key] line above the changed value to get the full registry path. Categorize:

Category	Example	Pattern type
Timestamp values	`LastBackgroundTaskRunDate`	`value_pattern`
Counters	`BootVolFreeCap` (disk free space)	`value_pattern`
Debug log keys	`Count=NNNN` under `WhDbgInfo`	`key_pattern`
Volatile keys	`VolatileNotifications`	`key_pattern`
Audio level hex blobs	`{1e94c58f-...},2` GUID values	`value_pattern` with `re:` prefix

4. Choose pattern type conservatively.

key_pattern — blocks entire key and all values. Use only when the key name is clearly volatile ("debug", "volatile", "cache").
value_pattern — blocks a value name across all keys. Only use unambiguous names (e.g. BootVolFreeCap means one thing; Maintenance does not).
confidence: "verified" — definitively noise, zero false-positive risk.
confidence: "likely" — almost certainly noise but with slight ambiguity. These are excluded in discovery mode.

5. GUIDs and special characters. Value names containing { need the re: prefix: "re:\\{1e94c58f-.*". The .* suffix is required.

6. Verify. After adding patterns, re-run the consecutive backup diff to confirm the hive files now hash-match.

Use pinman winreg blacklist test to test a candidate against cached data before committing it to the file.

Prefer general patterns over specific values. *LastScan* catches a whole class; LastQuickScanEndTime plays whack-a-mole. Group by the Windows subsystem being suppressed (telemetry, session, cache, network, etc.).

Binary Hive Format#

Off by default. Enable with registry_binary_format: true in config. Requires admin elevation; falls back to text .reg without it.

Format	Default	Requirements	Human-readable	Blacklist applied
Text `.reg`	Yes	None	Yes	At extraction (pre-filtered)
Binary `.hiv`	No	Admin elevation	No	Post-parse only

When to prefer binary:

Maximum fidelity needed (diagnosis, troubleshooting) — binary preserves timestamps, security descriptors, default values losslessly
Extraction speed on large subtrees matters
Restore workflows — reg restore can roundtrip a .hiv back to the live registry

For normal operation, text .reg is the right choice: no admin required, human-readable, pre-filtered by blacklist so files stay small.