Concepts

Pinman and Git

If you already use git (even just through a GUI), you have most of the mental model for Pinman. Both tools answer the same core questions: what changed, when, and how do I get back? This guide maps what you know about git onto Pinman — and, just as usefully, shows where the analogy stops.

The one-line version#

Git versions a folder of files you control. Pinman versions a whole running PC — files, plus settings buried in places git can't see.

Git tracks a repository: a directory tree of text files you deliberately put under version control. Pinman tracks a system: the files and the Windows registry, device/runtime settings, and individual values inside config files — spread across a dozen apps that were never designed to be versioned at all.

Where the analogy works#

If these git ideas feel natural, the Pinman equivalents will too.

In git you…	In Pinman you…	Notes
commit a snapshot	take a checkpoint	A frozen point on the timeline. Records what's there and what changed.
commit with the files	take a savepoint	A checkpoint that also backs up copies of the actual file bytes — the kind you can fully restore from.
`git diff` two commits	Compare two saved points	A read-only view. It creates nothing, exactly like `diff`.
`git status` (what's uncommitted)	the Live view vs your latest saved point	Pinman's default screen: "what's different right now from the last save?"
`git log` history	a journaled timeline of notes and saved points	A line of frozen moments — and your own notes — that you can compare against.
`git checkout <file>` to revert one file	restore selected items from a savepoint	Surgical, not all-or-nothing (see below).

So the everyday rhythm is familiar: save a known-good point, change things, look at the diff, and put back the parts you didn't want.

A handy framing some of Pinman's own docs use: a checkpoint is a commit, a savepoint is a commit with the files attached, and Compare is git diff — a view, not a saved thing.

Where Pinman goes further than git#

These are the differences that matter in practice — and the reason Pinman exists rather than "just use git."

1. It versions the whole system, not a chosen folder#

Git only knows about files inside a repo, and really only does well with text. Pinman reaches into the places real-world configuration actually lives:

Files (like git) — INI, XML, SQLite, custom binary formats.
Windows registry keys and values.
Windows runtime / device settings — display resolution, audio routing, GPU settings — things that aren't files at all, but live API-driven settings.

To git, "my display is set to 1080p" is invisible. To Pinman it's a tracked item with a history, just like a line in a config file.

2. Settings inside files are first-class#

In git, a config file is one blob; a one-character change shows up as "this file changed," and you read the line-diff yourself. Pinman can go a level deeper and track individual entries — this key in cabinet.ini, this registry value, this display setting — each with its own before/after and change badge.

You choose the depth per save: a quick "did any known file change?" pass, or a thorough "open every file and track every setting inside" pass.

3. You point Pinman at what matters — via a schema#

Git tracks everything in the repo (minus .gitignore). Pinman is the reverse by default: a schema tells it which files, registry areas, and settings across the whole machine are worth watching — pulling a handful of meaningful settings out of an ocean of system state. You can still ask it to sweep up untracked stuff for discovery, but the normal mode is focused: signal, not noise.

4. Restore is surgical, and driven by intent — profiles#

This is the biggest departure.

In git, the easy, polished operations are branch, checkout, and merge — you move the whole working tree from one state to another. Reverting just a couple of settings while keeping everything else means cherry-picking, partial checkouts, or hand-editing — the stuff that trips up even confident GUI users.

Pinman inverts the defaults. Instead of "switch the whole tree," you define a profile: a reusable, named description of intended state — "Production mode" or "Demo mode" — that may span files, registry, and device settings at once. Applying a profile changes only the settings it covers and leaves everything else untouched. Switching your whole machine between two configurations becomes one deliberate action, not a merge.

Two ways to think about it:

A savepoint restore is like git checkout of selected items — "put these specific things back the way they were at that point."
A profile has no real git equivalent. It's closer to a saved, parameterized intent you can apply on demand — surgical by design, where git's surgical operations are the advanced ones.

And because a profile knows what it's supposed to set, Pinman continuously shows drift: where the live system has wandered from the intended state — something git has no concept of (git compares to commits, not to a declared intent).

5. There's exactly one "Live"#

Git's working tree is a real place you can dirty, stash, and juggle across branches. Pinman keeps a single Live view — your system as it actually is, right now — and every "what changed since…?" question is measured against that same live view. You can't get two screens disagreeing about whether a file changed, because there's only one source of "now."

Beyond versioning — the rest of the platform#

Version control is only half of Pinman. Git is a versioning engine that an ecosystem (GitHub, CI, hooks, LFS) grows around. Pinman ships these as built-in parts of one tool, aimed at running a real machine rather than shipping code.

Dashboard. A live "is my system healthy and in its intended state?" screen — readiness, drift summaries, recent changes at a glance. Git has no home screen; the closest ecosystem analog is a CI/dashboard you assemble yourself.
Diagnostics. Pinman can collect system data and analyze it — health checks and probes that report status, not just difference. Git tells you what changed; Pinman can also tell you whether things are actually working.
Software-aware tracking. Files and settings are associated with the applications that own them — this INI, that registry key, and these display settings all belong to "Application XYZ." Git sees an anonymous tree of paths; Pinman knows which app a setting serves, so a change reads as "you changed the emulator's fullscreen setting," not "line 42 of a file moved."
Bundles / packages. A bundle is a lens that groups everything belonging to one thing (e.g. a single game) — its files and its scattered settings — into one unit you can view, capture, or carry. A package is the portable form: install, update, or remove that unit cleanly on another machine. The loose git-world analogs (submodules, LFS, release archives) are separate, fiddly add-ons; here it's one concept.
AI / MCP interface. Everything Pinman does is exposed over a CLI, REST API, and MCP so an AI agent can safely inspect state, take a checkpoint, apply a change, and verify the result inside a bounded, auditable workflow. Git is scriptable, but it has no notion of safe, supervised write-authority for an agent over a whole system.
Multiple machines on a LAN. Each machine runs Pinman locally; one browser UI connects to several to inspect and manage them. This is operating a fleet of systems, not syncing a shared repo the way git's remotes do — different goal, different shape.
Surgical apply across tools. Tying it back to profiles: one action can push a coordinated change across files, registry, and device APIs at once. Git's ecosystem reaches this only via external config-management tooling (Ansible and friends); Pinman has it inline.

Where git is still the right tool#

The honesty section. Pinman is not trying to replace git for software work.

Branching and parallel lines of development — git's whole reason for being. Pinman has a linear timeline of saved points, not a branch graph. It's for managing one machine's state over time, not exploring divergent histories.
Merging two people's work — git's conflict resolution has no Pinman analog; Pinman assumes a single system with one true current state.
Source code — line-level diffs, blame, pull requests. Use git.
Distributed collaboration — push/pull/remotes. Pinman is about your machine (or a few machines you operate), not a shared remote history.

Rule of thumb: git versions the things you author; Pinman versions the system those things run on.

The 30-second summary#

	Git	Pinman
What it tracks	A chosen folder of files (text-first)	A whole PC: files + registry + device/runtime settings
Granularity	Whole files (you read the line-diff)	Down to individual settings inside files
What's in scope	Everything in the repo	Only what a schema points it at (discovery optional)
Snapshot	commit	checkpoint (savepoint = commit + the files)
Diff	`git diff`	Compare
Moving between states	branch / checkout / merge (whole tree)	apply a profile (surgical, intent-driven)
*Knows your intent?*	No — compares to commits	Yes — drift vs a declared profile
Branching / merging	Core strength	Not a goal — linear timeline
Collaboration	Distributed (push/pull)	Single system, one live state