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.

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

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

# questions
project_name:
    type: str
    help: What is your project name?

module_name:
    type: str
    help: What is your Python module name?

print("Hello from {{module_name}}!")

# 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:

generated_project
    super_project
        world.py
    .copier-answers.yml

print("Hello from world!")

# 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, to see all the configurations options and their usage.

Template helpers

In addition to all the features Jinja supports, Copier includes:

All functions and filters from 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

[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.

3.6 KiB Raw Blame History

Creating a template

Minimal example

Template helpers

3.6 KiB

Raw Blame History