Includes and Layering

Includes & Layering

Compose templates from other templates.

includes in template.lua

return {
  id = "layered_cpp_product",
  -- ...
  includes = { "layered_cpp_base", "layered_ci_overlay" },
  merge = {
    file_conflicts = {
      ["src/main.cpp.pbt"] = "replace",
    },
    drop_paths = { "base-only.txt" },
  },
}

Alternatively: separate includes.lua in template root (list of IDs).

Merge order

1. Includes are loaded in order and resolved recursively
2. The current template is on top (highest priority)
3. Cycles (A → B → A) cause an error

merge configuration

Field	Effect
file_conflicts	Strategy for same relative path
drop_paths	Remove paths from merge result (including subdirs)
question_conflicts	How questions with the same key merge
pre_hook_conflict / post_hook_conflict	Hook collisions between includes

Strategies

Value	Meaning
replace	Overlay wins (default for files)
keep	Keep base
error	Abort with TempifyError

Wildcards: ["*.pbt"] = "keep" matches file extensions.

What gets merged?

Area	Behavior
Files & directories	Per file_conflicts
Questions	Per question_conflicts (default: replace)
layout.lua rules	Append
Scripts	Replace by name
pre / post hooks	Configurable; before_render / after_render from top template
Manifest metadata	ID/version/output from top template

Example in the repo

layered_cpp_base/     → README, main.cpp, base-only.txt
layered_ci_overlay/   → CI workflow, README overlay
layered_cpp_product/  → includes both, drops base-only, replaces main.cpp

tempify inspect layered_cpp_product

See also

template.lua Reference · Example Catalog