mirror of
https://github.com/copier-org/copier.git
synced 2025-05-06 16:02:57 +00:00
102 lines
3.6 KiB
Markdown
102 lines
3.6 KiB
Markdown
# Creating a template
|
|
|
|
A template is a directory: usually the root folder of a Git repository.
|
|
|
|
The content of the files inside the project template is copied to the destination
|
|
without changes, **unless they end with `.jinja`** (or [your chosen
|
|
suffix][templates_suffix]). In that case, the templating engine will be used to render
|
|
them.
|
|
|
|
Jinja2 templating is used. Learn more about it by reading
|
|
[Jinja2 documentation](https://jinja.palletsprojects.com/).
|
|
|
|
If a **YAML** file named `copier.yml` or `copier.yaml` is found in the root of the
|
|
project, the user will be prompted to fill in or confirm the default values.
|
|
|
|
## Minimal example
|
|
|
|
```tree result="shell"
|
|
my_copier_template # your template project
|
|
copier.yml # your template configuration
|
|
.git/ # your template is a Git repository
|
|
{{project_name}} # a folder with a templated name
|
|
{{module_name}}.py.jinja # a file with a templated name
|
|
{{_copier_conf.answers_file}}.jinja # answers are recorded here
|
|
```
|
|
|
|
```yaml title="copier.yml"
|
|
# questions
|
|
project_name:
|
|
type: str
|
|
help: What is your project name?
|
|
|
|
module_name:
|
|
type: str
|
|
help: What is your Python module name?
|
|
```
|
|
|
|
```python+jinja title="{{project_name}}/{{module_name}}.py.jinja"
|
|
print("Hello from {{module_name}}!")
|
|
```
|
|
|
|
```yaml+jinja title="{{_copier_conf.answers_file}}.jinja"
|
|
# Changes here will be overwritten by Copier
|
|
{{ _copier_answers|to_nice_yaml -}}
|
|
```
|
|
|
|
Generating a project from this template with `super_project` and `world` as answers for
|
|
the `project_name` and `module_name` questions respectively would create in the
|
|
following directory and files:
|
|
|
|
```tree result="shell"
|
|
generated_project
|
|
super_project
|
|
world.py
|
|
.copier-answers.yml
|
|
```
|
|
|
|
```python title="super_project/world.py"
|
|
print("Hello from world!")
|
|
```
|
|
|
|
```yaml title=".copier-answers.yml"
|
|
# Changes here will be overwritten by Copier
|
|
_commit: 0.1.0
|
|
_src_path: gh:your_account/your_template
|
|
project_name: super_project
|
|
module_name: world
|
|
```
|
|
|
|
Copier allows much more advanced templating: see the next chapter,
|
|
[configuring a template](configuring.md), to see all the configurations options and
|
|
their usage.
|
|
|
|
## Template helpers
|
|
|
|
In addition to
|
|
[all the features Jinja supports](https://jinja.palletsprojects.com/en/3.1.x/templates/),
|
|
Copier includes:
|
|
|
|
- All functions and filters from
|
|
[jinja2-ansible-filters](https://gitlab.com/dreamer-labs/libraries/jinja2-ansible-filters/).
|
|
|
|
- This includes the `to_nice_yaml` filter, which is used extensively in our
|
|
context.
|
|
|
|
- `_copier_answers` includes the current answers dict, but slightly modified to make
|
|
it suitable to [autoupdate your project safely][the-copier-answersyml-file]:
|
|
- It doesn't contain secret answers.
|
|
- It doesn't contain any data that is not easy to render to JSON or YAML.
|
|
- It contains special keys like `_commit` and `_src_path`, indicating how the last
|
|
template update was done.
|
|
- `_copier_conf` includes a representation of the current Copier
|
|
<!-- prettier-ignore -->
|
|
[Worker][copier.main.Worker] object, also slightly modified:
|
|
- It only contains JSON-serializable data.
|
|
- You can serialize it with `{{ _copier_conf|to_json }}`.
|
|
- ⚠️ It contains secret answers inside its `.data` key.
|
|
- Modifying it doesn't alter the current rendering configuration.
|
|
- It contains the current commit hash from the template in
|
|
`{{ _copier_conf.vcs_ref_hash }}`.
|
|
- Contains Operating System-specific directory separator under `sep` key.
|