Modules and profiles

Keep capabilities small and compose the configuration your environment needs.

A module owns one capability and its input files. A profile selects modules for a purpose, such as a developer environment. Both live in your consumer repository.

A module is local configuration

The starter keeps Git configuration under modules/git/. Its module.conf declares a name, schema version, and actions; files/gitconfig is a module-owned asset. Etch reads literal configuration data rather than executing it as Python.

Repository-wide defaults.conf holds default provider options and explicit plugin paths. Actions can override supported defaults. Profiles live under profiles/.

Keep configuration readable

Etch formats module and profile files with two-space indentation. Short lists such as ['tmux', '-V'] stay on one line; longer lists split. Comments are retained.

./etch format
./etch format modules/git/module.conf
./etch format --check
./etch validate

format --check reports differences without changing files, so it works in CI. validate separately checks configuration declarations without inspecting or applying them; declared plugins are loaded as trusted Python code. .editorconfig helps your editor follow Etch’s style but does not change the formatter’s rules.

Select deliberately

./etch plan git
./etch plan --profile developer

Dependencies describe ordering and required selected modules. They do not silently select modules or fetch remote dependencies. Imports copy a module into the fixed modules/<name>/ destination and refuse an existing destination.

See the configuration reference and the import guide for current syntax and limits.