Content separation

The PolyForge repository holds scaffolding only: configuration fragments, per-language mise.toml files, and the wrapper scripts. Your actual work lives in its own repositories and is pulled in on demand.

This is the idea most worth stealing from the project.

The problem it solves

A workspace repository that also contains the work grows without bound. Two years in, cloning your environment onto a new laptop means cloning every half-finished experiment, every learning exercise, and every large asset you ever committed. The tooling and the content have completely different lifecycles, and jamming them into one repository forces them to share one.

So PolyForge splits them. .gitignore excludes:

Dev/Learn/
Dev/Templates/*/
Workspace/*/*/

Note the shape of the last two: the area directories are tracked (they carry their mise.toml), but their contents are not.

Three kinds of content, three owners

Kind	Its own repo	Restored to	Managed by
Learning track	one per language	Dev/Learn/<lang>	learn
Portfolio project	one per project	Workspace/<lang>/<name>	polyforge
Template	one per template	Dev/Templates/<name>	forge

The registry is the map

polyforge.registry.toml is committed. It carries no code — only names and where to find them:

polyforge.registry.toml

[learn.go]
repo = "git@github.com:youruser/learn-go.git"

[portfolio.wall-extraction]
repo = "git@github.com:youruser/wall-extraction.git"
lang = "Python"

The lang key on a portfolio entry is what tells get which Workspace/ subdirectory to restore into. Learning tracks do not need it — the section name is the language.

Template descriptions live here too, which is why forge list can show a description for a template you have not cloned yet.

Publish once, restore anywhere

Publishing needs the GitHub CLI, logged in. Restoring needs only git — a meaningful difference when you are setting up a machine where you have not authenticated gh yet.

# publish (needs gh)
learn publish go
polyforge publish          # from inside Workspace/Python/wall-extraction
forge new archon "archicad addons template"

# restore (needs only git)
learn get all
polyforge get all
forge get all

If the target already exists locally, get runs git pull instead of cloning — so get all is safe to re-run and doubles as “update everything”.

Commit the registry

Publishing writes to polyforge.registry.toml. If you do not commit and push that change, the next machine will not know the repository exists. Treat the registry commit as part of publishing.

What you give up

Your work is spread across many repositories instead of one. There is no single git log covering everything, and cross-project search needs a tool that spans repos.

In exchange, the environment stays a few kilobytes forever, each project has a real history of its own, and you can make one project public without exposing the rest.