copier/docs/creating.md

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 provides all functions and filters from jinja2-ansible-filters. This includes the to_nice_yaml filter, which is used extensively in our context.

Variables (global)

The following variables are always available in Jinja templates:

_copier_answers

_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

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

Furthermore, the following keys are added:

os { #_copier_conf.os }

The detected operating system, either "linux", "macos", "windows" or None.

sep { #_copier_conf.sep }

The operating system-specific directory separator.

vcs_ref_hash { #_copier_conf.vcs_ref_hash }

The current commit hash from the template.

_copier_python

The absolute path of the Python interpreter running Copier.

_external_data

A dict of the data contained in [external_data][].

When rendering the template, that data will be exposed in the special _external_data variable:

• Keys will be the same as in [external_data][].
• Values will be the files contents parsed as YAML. JSON is also compatible.
• Parsing is done lazily on first use.

_folder_name

The name of the project root directory.

_copier_phase

The current phase, one of "prompt","tasks", "migrate" or "render".

!!! note

There is also an additional `"undefined"` phase used when not in any phase.
You may encounter this phase when rendering outside of those phases,
when rendering lazily (and the phase notion can be irrelevant) or when testing.

Variables (context-dependent)

Some variables are only available in select contexts:

_copier_operation

The current operation, either "copy" or "update".

Availability: exclude, tasks

Variables (context-specific)

Some rendering contexts provide variables unique to them:

• migrations

Loop over lists to generate files and directories

You can use the special yield tag in file and directory names to generate multiple files or directories based on a list of items.

In the path name, {% yield item from list_of_items %}{{ item }}{% endyield %} will loop over the list_of_items and replace {{ item }} with each item in the list.

A looped {{ item }} will be available in the scope of generated files and directories.

commands:
    type: yaml
    multiselect: true
    choices:
        init:
            value: &init
                name: init
                subcommands:
                    - config
                    - database
        run:
            value: &run
                name: run
                subcommands:
                    - server
                    - worker
        deploy:
            value: &deploy
                name: deploy
                subcommands:
                    - staging
                    - production
    default: [*init, *run, *deploy]

commands
    {% yield cmd from commands %}{{ cmd.name }}{% endyield %}
        __init__.py
        {% yield subcmd from cmd.subcommands %}{{ subcmd }}{% endyield %}.py.jinja

print("This is the `{{ subcmd }}` subcommand in the `{{ cmd.name }}` command")

If you answer with the default to the question, Copier will generate the following structure:

commands
    deploy
        __init__.py
        production.py
        staging.py
    init
        __init__.py
        config.py
        database.py
    run
        __init__.py
        server.py
        worker.py

Where looped variables cmd and subcmd are rendered in generated files:

print("This is the `config` subcommand in the `init` command")