Concepts

Templates

The template system that scaffolds code into your projects.

What is a template

A template is a directory of .cs files that share a single declared C# namespace. That namespace acts as a token: when the template is applied, every occurrence is replaced with the target project's namespace.

Three sources

Source	Prefix	Example
Built-in	(none)	`base-entity`
GitHub	`github:`	`github:my-org/socotra-templates/audit-entity`
Local path	[object Object] or /	`./my-templates/audit-entity`

Provider chain

Resolution walks an ITemplateProvider chain in a fixed order; the first match wins. This is what lets you override a built-in template without forking the tool.

Order	Provider	Location	Use case
1	Project	`.socotra/templates/`	Per-repo customization, checked into Git
2	Global	`~/.socotra/registry/`	User-wide registry shared across projects
3	Built-in	(embedded)	Shipped inside the tool binary

Exporting a built-in template with socotra template export <name> drops a copy into the project scope, so future applies use your edited version instead of the embedded one.

Namespace and content tokens

In addition to namespace normalization, two content tokens are substituted in template files: {{Name}} resolves to PascalCase of the template name, and {{Namespace}} resolves to the full target namespace.

Project vs global scope

Every template subcommand accepts --global to switch the target scope. Without it, operations go to the project-local cache at .socotra/templates/ (committed to Git so teammates share the same templates). With --global, they go to the user-wide registry at ~/.socotra/registry/, which the built-in template cache also lives in as of v1.0.0-beta2. See authoring for the full pipeline.

Schema 1.0 · CLI 1.0

PreviousYAML schema Next Pipeline architecture