diff --git a/README.md b/README.md index b6a9ff9ca..54c5002e6 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Documentation Status](https://readthedocs.org/projects/copier/badge/?version=latest)](https://copier.readthedocs.io/en/latest/?badge=latest) -A library for rendering project templates. +A library and CLI app for rendering project templates. - Works with **local** paths and **git URLs**. - Your project can include any file and `Copier` can dynamically replace values in any @@ -31,19 +31,19 @@ A library for rendering project templates. - Use it in your Python code: ```python - from copier import copy + from copier import run_auto # Create a project from a local path - copy("path/to/project/template", "path/to/destination") + run_auto("path/to/project/template", "path/to/destination") # Or from a git URL. - copy("https://github.com/copier-org/copier.git", "path/to/destination") + run_auto("https://github.com/copier-org/copier.git", "path/to/destination") # You can also use "gh:" as a shortcut of "https://github.com/" - copy("gh:copier-org/copier.git", "path/to/destination") + run_auto("gh:copier-org/copier.git", "path/to/destination") # Or "gl:" as a shortcut of "https://gitlab.com/" - copy("gl:copier-org/copier.git", "path/to/destination") + run_auto("gl:copier-org/copier.git", "path/to/destination") ``` - Or as a command-line tool: @@ -52,6 +52,43 @@ A library for rendering project templates. copier path/to/project/template path/to/destination ``` +## Basic concepts + +Copier is composed of these main concepts: + +1. **Templates**. They lay out how to generate the subproject. +1. **Questionaries**. They are configured in the template. Answers are used to generate + projects. +1. **Projects**. This is where your real program lives. But it is usually generated + and/or updated from a template. + +Copier targets these main human audiences: + +1. **Template creators**. Programmers that repeat code too much and prefer a tool to do + it for them. + + !!! tip + + Copier doesn't replace the DRY principle... but sometimes you simply can't be + DRY and you need a DRYing machine... + +1. **Template consumers**. Programmers that want to start a new project quickly, or + that want to evolve it comfortably. + +Non-humans should be happy also by using copier's CLI or API, as long as their +expectations are the same as for those humans... and as long as they have feelings. + +Templates have these goals: + +1. **[Code scaffolding]()**. Help + consumers have a working source code tree as quick as possible. All templates allow + scaffolding. +1. **Code lifecycle management**. When the template evolves, let consumers update their + projects. Not all templates allow updating. + +Copier tries to have a smooth learning curve that lets you create simple templates that +can evolve into complex ones as needed. + ## Browse or tag public templates You can browse public copier templates in GitHub using diff --git a/docs/comparisons.md b/docs/comparisons.md index 0b6dfbd86..8c395d333 100644 --- a/docs/comparisons.md +++ b/docs/comparisons.md @@ -1,16 +1,24 @@ # Comparing Copier to other project generators -The subject of project scaffolding has been around for some time, and Copier is just a -new one in a list of long established good projects. Here's a simple comparison. If you -find something wrong, please open a PR and fix it! We don't want to be biased, but it's -easy that we tend to be: +The subject of +[code scaffolding]() has been +around for some time, and there are long established good projects. + +Here's a simple comparison. If you find something wrong, please open a PR and fix these +docs! We don't want to be biased, but it's easy that we tend to be: + +!!! important + + Although Copier was born as a code scaffolding tool, it is today a code lifecycle + management tool. This makes it somehow unique. Most tools below are only scaffolders + and the comparison is not complete due to that. | Feature | Copier | Cookiecutter | Yeoman | | ---------------------------------------- | ---------------------------------------- | ------------------------------- | ------------- | | Can template file names | Yes | Yes | Yes | -| Configuration | Single or multiple YAML files | Single JSON file | JS module | +| Configuration | Single YAML file1 | Single JSON file | JS module | | Migrations | Yes | No | No | | Programmed in | Python | Python | NodeJS | | Requires handwriting JSON | No | Yes | Yes | @@ -20,16 +28,16 @@ easy that we tend to be: | Task hooks | Yes | Yes | Yes | | Template in a subfolder | Not required, but you choose | Yes, required | Yes, required | | Template package format | Git repo2, Git bundle, folder | Git or Mercurial repo, Zip file | NPM package | -| Template updates | Yes4 | No | No | -| Templating engine | [Jinja][]1 | [Jinja][] | [EJS][] | +| Template updates | **Yes**4 | No | No | +| Templating engine | [Jinja][] | [Jinja][] | [EJS][] | [jinja]: https://jinja.palletsprojects.com/ [ejs]: https://ejs.co/ --- -1 Copier configures Jinja to use `[[ brackets ]]` instead of -`{{ curly braces }}` by default, but that can be changed per template if needed. +1 The file itself can +[include other YAML files](configuring.md#include-other-yaml-files). 2 Git repo is recommended to be able to use advanced features such as template tagging and smart updates. diff --git a/docs/configuring.md b/docs/configuring.md index 4f5b6c3ac..bd656e067 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -16,13 +16,19 @@ Copier reads **settings** from these sources, in this order of priority: 1. [The `copier.yml` file](#the-copieryml-file). Settings here always start with an underscore (e.g. `_min_copier_version`). +!!! info + + Some settings are _only_ available as CLI arguments, and some others _only_ as + template configurations. Some behave differently depending on where they are + defined. [Check the docs for each specific setting](#available-settings). + Copier obtains **answers** from these sources, in this order of priority: 1. Command line or API arguments. 1. Asking the user. Notice that Copier will not ask any questions answered in the previous source. -1. The last answers file. -1. [The `copier.yml` file](#the-copieryml-file), where default values are defined. +1. [Answer from last execution](#the-copier-answersyml-file). +1. Default values defined in [the `copier.yml` file](#the-copieryml-file). ## The `copier.yml` file @@ -37,21 +43,25 @@ for two purposes: ### Questions For each key found, Copier will prompt the user to fill or confirm the values before -they become available to the project template. For example, this: +they become available to the project template. -```yaml -name_of_the_project: My awesome project -number_of_eels: 1234 -your_email: "" -``` +!!! example -Will result in a questionary similar to: + This `copier.yml` file: -
-🎤 name_of_the_project? Format: str My awesome project
-🎤 number_of_eels? Format: int 1234
-🎤 your_email? Format: str
-
+ ```yaml + name_of_the_project: My awesome project + number_of_eels: 1234 + your_email: "" + ``` + + Will result in a questionary similar to: + + 
+    🎤 name_of_the_project? Format: str My awesome project
+    🎤 number_of_eels? Format: int 1234
+    🎤 your_email? Format: str
+
#### Advanced prompt formatting @@ -82,9 +92,10 @@ Supported keys: - **multiline**: When set to `true`, it allows multiline input. This is especially useful when `type` is `json` or `yaml`. -- **when**: Condition that, if `False`, skips the question. If it is a boolean, it is - used directly. If it is a str, it is converted to boolean using a parser similar to - YAML, but only for boolean values. +- **when**: Condition that, if `false`, skips the question. If it is a boolean, it is + used directly (although it's a bit absurd in that case). If it is a string, it is + converted to boolean using a parser similar to YAML, but only for boolean values. + This is most useful when [templated](#prompt-templating). !!! example @@ -299,16 +310,20 @@ Remember that **the key must be prefixed with an underscore if you use it in - CLI flags: `-a`, `--answers-file` - Default value: `.copier-answers.yml` -File where answers will be recorded by default. Remember to add that file to your Git -template if you want to support updates. +File where answers will be recorded by default. + +!!! tip + + Remember to add that file to your Git template if you want to support + [updates](updating.md). Don't forget to read [the docs about the answers file](#the-copier-answersyml-file). -Example `copier.yml`: +!!! example -```yaml -_answers_file: .my-custom-answers.yml -``` + ```yaml + _answers_file: .my-custom-answers.yml + ``` ### `cleanup_on_error` @@ -326,7 +341,7 @@ running `copier update`, this setting has no effect. !!! info - It makes no sense to define this in `copier.yml`. + Not supported in `copier.yml`. ### `data` @@ -339,12 +354,14 @@ Give answers to questions through CLI/API. This cannot be defined in `copier.yml`, where its equivalent would be just normal questions with default answers. -Example CLI usage to take all default answers from template, except the user name, which -is overriden, and don't ask user anything else: +!!! example -```sh -copier -fd 'user_name=Manuel Calavera' copy template destination -``` + Example CLI usage to take all default answers from template, except the user name, + which is overriden, and don't ask user anything else: + + ```sh + copier -fd 'user_name=Manuel Calavera' copy template destination + ``` ### `envops` @@ -379,8 +396,8 @@ to know available options. By specifying this, your template will be compatible with both Copier 5 and 6. - Copier 6 will apply these older defaults if your [min_copier_version][] is older - than 6, but that will be removed later. + Copier 6 will apply these older defaults if your [min_copier_version][] is lower + than 6, but that will be removed in the future. ### `exclude` @@ -393,26 +410,20 @@ to know available options. The CLI option can be passed several times to add several patterns. -Example `copier.yml`: - -```yaml -_exclude: - - "*.bar" - - ".git" -``` - !!! info When you define this parameter in `copier.yml`, it will **replace** the default value. - In the above example, for instance, `"copier.yml"` will **not** be excluded. + In this example, for instance, `"copier.yml"` will **not** be excluded: -Example CLI usage to copy only a single file from the template: + !!! example -```sh -copier --exclude '*' --exclude '!file-i-want' copy template destination -``` + ```yaml + _exclude: + - "*.bar" + - ".git" + ``` !!! info @@ -421,6 +432,13 @@ copier --exclude '*' --exclude '!file-i-want' copy template destination Instead, CLI/API definitions **will extend** those from `copier.yml`. + + !!! example Example CLI usage to copy only a single file from the template + + ```sh + copier --exclude '*' --exclude '!file-i-want' copy ./template ./destination + ``` + ### `force` - Format: `bool` @@ -434,56 +452,33 @@ Also don't ask questions to the user; just use default values !!! info - It makes no sense to define this in `copier.yml`. + Not supported in `copier.yml`. ### `jinja_extensions` - Format: `List[str]` - CLI flags: N/A -- Default value: [] +- Default value: `[]` Additional Jinja2 extensions to load in the Jinja2 environment. Extensions can add filters, global variables and functions, or tags to the environment. -Examples of extensions you can use: - -- [`cookiecutter.extensions.JsonifyExtension`](https://cookiecutter.readthedocs.io/en/latest/advanced/template_extensions.html#jsonify-extension): - provides a `jsonify` filter, to format a dictionary as JSON. Note that Copier - natively provides a `to_nice_json` filter that can achieve the same thing. -- [`cookiecutter.extensions.RandomStringExtension`](https://cookiecutter.readthedocs.io/en/latest/advanced/template_extensions.html#random-string-extension): - provides a `random_ascii_string(length, punctuation=False)` global function. Note - that Copier natively provides the `ans_random` and `hash` filters that can be used - to achieve the same thing. -- [`cookiecutter.extensions.SlugifyExtension`](https://cookiecutter.readthedocs.io/en/latest/advanced/template_extensions.html#slugify-extension): - provides a `slugify` filter using - [python-slugify](https://github.com/un33k/python-slugify). -- [`copier_templates_extensions.TemplateExtensionLoader`](https://github.com/pawamoy/copier-templates-extensions): - enhances the extension loading mecanism to allow templates writers to put their - extensions directly in their templates. -- [`jinja_markdown.MarkdownExtension`](https://github.com/jpsca/jinja-markdown): - provides a `markdown` tag that will render Markdown to HTML using - [PyMdown extensions](https://facelessuser.github.io/pymdown-extensions/). -- [`jinja2_slug.SlugExtension`](https://pypi.org/project/jinja2-slug/#files): provides - a `slug` filter using [unicode-slugify](https://github.com/mozilla/unicode-slugify). -- [`jinja2_time.TimeExtension`](https://github.com/hackebrot/jinja2-time): adds a - `now` tag that provides convenient access to the - [arrow.now()](http://crsmithdev.com/arrow/#arrow.factory.ArrowFactory.now) API. - -Search for more extensions on GitHub using the -[jinja2-extension topic](https://github.com/topics/jinja2-extension), or -[other Jinja2 topics](https://github.com/search?q=jinja&type=topics), or -[on PyPI using the jinja + extension keywords](https://pypi.org/search/?q=jinja+extension). - -Example use in Copier configuration: +The following extensions are _always_ loaded: -```yaml -_jinja_extensions: - - jinja_markdown.MarkdownExtension - - jinja2_slug.SlugExtension - - jinja2_time.TimeExtension -``` +- [`jinja2_ansible_filters.AnsibleCoreFiltersExtension`](https://gitlab.com/dreamer-labs/libraries/jinja2-ansible-filters/): + this extension adds most of the + [Ansible filters](https://docs.ansible.com/ansible/2.3/playbooks_filters.html) to + the environment. + +You don't need to tell your template users to install these extensions: Copier depends +on them, so they are always installed when Copier is installed. + +!!! warning + + Including an extension allows Copier to execute uncontrolled code, thus making the + template potentially more dangerous. Be careful about what extensions you install. -!!! important "Note to template writers" +!!! info "Note to template writers" You must inform your users that they need to install the extensions alongside Copier, i.e. in the same virtualenv where Copier is installed. @@ -498,15 +493,55 @@ _jinja_extensions: pipx inject copier jinja2-time ``` - --- +!!! example - The following extensions are *always* loaded: + ```yaml + _jinja_extensions: + - jinja_markdown.MarkdownExtension + - jinja2_slug.SlugExtension + - jinja2_time.TimeExtension + ``` - - [`jinja2_ansible_filters.AnsibleCoreFiltersExtension`](https://gitlab.com/dreamer-labs/libraries/jinja2-ansible-filters/): - this extension adds most of the [Ansible filters](https://docs.ansible.com/ansible/2.3/playbooks_filters.html) to the environment. +!!! hint - You don't need to tell your template users to install these extensions: - Copier depends on them, so they are always installed when Copier is installed. + Examples of extensions you can use: + + - From [cookiecutter](https://cookiecutter.readthedocs.io/en/1.7.2/): + + - [`cookiecutter.extensions.JsonifyExtension`](https://cookiecutter.readthedocs.io/en/latest/advanced/template_extensions.html#jsonify-extension): + provides a `jsonify` filter, to format a dictionary as JSON. Note that Copier + natively provides a `to_nice_json` filter that can achieve the same thing. + - [`cookiecutter.extensions.RandomStringExtension`](https://cookiecutter.readthedocs.io/en/latest/advanced/template_extensions.html#random-string-extension): + provides a `random_ascii_string(length, punctuation=False)` global function. + Note that Copier natively provides the `ans_random` and `hash` filters that can + be used to achieve the same thing: + + !!! example + + ```jinja + {{ 999999999999999999999999999999999|ans_random|hash('sha512') }} + ``` + + - [`cookiecutter.extensions.SlugifyExtension`](https://cookiecutter.readthedocs.io/en/latest/advanced/template_extensions.html#slugify-extension): + provides a `slugify` filter using + [python-slugify](https://github.com/un33k/python-slugify). + + - [`copier_templates_extensions.TemplateExtensionLoader`](https://github.com/pawamoy/copier-templates-extensions): + enhances the extension loading mecanism to allow templates writers to put their + extensions directly in their templates. + - [`jinja_markdown.MarkdownExtension`](https://github.com/jpsca/jinja-markdown): + provides a `markdown` tag that will render Markdown to HTML using + [PyMdown extensions](https://facelessuser.github.io/pymdown-extensions/). + - [`jinja2_slug.SlugExtension`](https://pypi.org/project/jinja2-slug/#files): provides + a `slug` filter using [unicode-slugify](https://github.com/mozilla/unicode-slugify). + - [`jinja2_time.TimeExtension`](https://github.com/hackebrot/jinja2-time): adds a + `now` tag that provides convenient access to the + [arrow.now()](http://crsmithdev.com/arrow/#arrow.factory.ArrowFactory.now) API. + + Search for more extensions on GitHub using the + [jinja2-extension topic](https://github.com/topics/jinja2-extension), or + [other Jinja2 topics](https://github.com/search?q=jinja&type=topics), or + [on PyPI using the jinja + extension keywords](https://pypi.org/search/?q=jinja+extension). ### `migrations` @@ -529,7 +564,7 @@ Migrations will run in the same order as declared here (so you could even run a migration for a higher version before running a migration for a lower version if the higher one is declared before and the update passes through both). -They will only run when new version >= declared version > old version. And only when +They will only run when _new version >= declared version > old version_. And only when updating (not when copying for the 1st time). If the migrations definition contains Jinja code, it will be rendered with the same @@ -538,18 +573,18 @@ context as the rest of the template. Migration processes will contain the `$VERSION_FROM`, `$VERSION_TO`, `$VERSION_CURRENT` and `$STAGE` (before/after) environment variables -Example `copier.yml`: +!!! example -```yaml -_migrations: - - version: v1.0.0 - before: - - rm ./old-folder - after: - # [[ _copier_conf.src_path ]] points to the path where the template was - # cloned, so it can be helpful to run migration scripts stored there. - - invoke -r [[ _copier_conf.src_path ]] -c migrations migrate $VERSION_CURRENT -``` + ```yaml + _migrations: + - version: v1.0.0 + before: + - rm ./old-folder + after: + # {{ _copier_conf.src_path }} points to the path where the template was + # cloned, so it can be helpful to run migration scripts stored there. + - invoke -r {{ _copier_conf.src_path }} -c migrations migrate $VERSION_CURRENT + ``` ### `min_copier_version` @@ -570,26 +605,11 @@ generation will be aborted and an error will be shown to the user. features can be dropped or changed, so it's probably a good idea to ask the template maintainer to update it. -Example `copier.yml`: - -```yaml -_min_copier_version: "4.1.0" -``` - -### `only_diff` - -- Format: `bool` -- CLI flags: Just use `copier copy` to disable it, or `copier update` to enable it. -- Default value: `True` - -When doing an update, by default Copier will do its best to understand how the template -has evolved since the last time you updated it, and will try to apply only that diff to -your subproject, respecting the subproject's own evolution as much as possible. - -Update with `only_diff=False` to avoid this behavior and let Copier override any changes -in the subproject. +!!! example -It makes no sense to define this in `copier.yml`. + ```yaml + _min_copier_version: "4.1.0" + ``` ### `pretend` @@ -601,7 +621,7 @@ Run but do not make any changes. !!! info - It makes no sense to define this in `copier.yml`. + Not supported in `copier.yml`. ### `quiet` @@ -613,7 +633,7 @@ Suppress status output. !!! info - It makes no sense to define this in `copier.yml`. + Not supported in `copier.yml`. ### `skip_if_exists` @@ -624,18 +644,20 @@ Suppress status output. [Patterns](#patterns-syntax) for files/folders that must be skipped if they already exist. -For example, it can be used if your project generates a password the 1st time and you -don't want to override it next times: +!!! example -```yaml -# copier.yml -_skip_if_exists: .secret_password.yml -``` + For example, it can be used if your project generates a password the 1st time and + you don't want to override it next times: -```yaml -# .secret_password.yml.tmpl -[[make_secret()|tojson]] -``` + ```yaml + # copier.yml + _skip_if_exists: .secret_password.yml + ``` + + ```yaml + # .secret_password.yml.tmpl + {{999999999999999999999999999999999|ans_random|hash('sha512')}} + ``` ### `subdirectory` @@ -646,11 +668,18 @@ _skip_if_exists: .secret_password.yml Subdirectory to use as the template root when generating a project. If not specified, the root of the template is used. -Example `copier.yml`: +This allows you to keep separate the template metadata and the template code. -```yaml -_subdirectory: src -``` +!!! tip + + If your template is meant to be applied to other templates (a.k.a. recursive + templates), use this option to be able to use [updates](updating.md). + +!!! example + + ```yaml + _subdirectory: template + ``` ### `tasks` @@ -670,12 +699,12 @@ Example `copier.yml`: _tasks: # Strings get executed under system's default shell - "git init" - - "rm [[ name_of_the_project ]]/README.md" + - "rm {{ name_of_the_project }}/README.md" # Arrays are executed without shell, saving you the work of escaping arguments - - [invoke, "--search-root=[[ _copier_conf.src_path ]]", after-copy] + - [invoke, "--search-root={{ _copier_conf.src_path }}", after-copy] # You are able to output the full conf to JSON, to be parsed by your script, # but you cannot use the normal `|tojson` filter; instead, use `.json()` - - [invoke, end-process, "--full-conf=[[ _copier_conf.json() ]]"] + - [invoke, end-process, "--full-conf={{ _copier_conf.json() }}"] ``` ### `templates_suffix` @@ -686,19 +715,19 @@ _tasks: Suffix that instructs which files are to be processed by Jinja as templates. -Example `copier.yml`: +!!! example -```yaml -_templates_suffix: .my-custom-suffix -``` + ```yaml + _templates_suffix: .my-custom-suffix + ``` !!! warning Copier 5 and older had a different default value: `.tmpl`. If you wish to keep it, add it to your `copier.yml` to keep it future-proof. - Copier 6 will apply that old default if your [min_copier_version][] is older - than 6, but that will be removed later. + Copier 6 will apply that old default if your [min_copier_version][] is lower + than 6, but that will be removed in the future. ### `use_prereleases` @@ -721,7 +750,7 @@ the `v2.0.0a1` tag unless this flag is enabled. !!! info - It makes no sense to define this in `copier.yml`. + Not supported in `copier.yml`. ### `vcs_ref` @@ -735,12 +764,12 @@ to copy. This is stored automatically in the answers file, like this: ```yaml -_vcs_ref: v1.0.0 +_commit: v1.0.0 ``` !!! info - It makes no sense to define this in `copier.yml`. + Not supported in `copier.yml`. By default, copier will copy from the last release found in template git tags, sorted as [PEP 440](https://www.python.org/dev/peps/pep-0440/). @@ -773,7 +802,7 @@ will be used to load the last user's answers to the questions made in This makes projects easier to update because when the user is asked, the default answers will be the last ones he used. -The file **must be called exactly `[[ _copier_conf.answers_file ]].tmpl`** (or ended +The file **must be called exactly `{{ _copier_conf.answers_file }}.jinja`** (or ended with [your chosen suffix](#templates_suffix)) in your template's root folder) to allow [applying multiple templates to the same subproject](#applying-multiple-templates-to-the-same-subproject). @@ -784,10 +813,10 @@ The file must have this content: ```yaml # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY -[[_copier_answers|to_nice_yaml]] +{{_copier_answers|to_nice_yaml}} ``` -!!! info +!!! important Did you notice that `NEVER EDIT MANUALLY` part? [It is important](updating.md#never-change-the-answers-file-manually). @@ -822,7 +851,7 @@ All 3 templates are completely independent: matter their pre-commit configuration or the framework they rely on. Well, don't worry. Copier has you covered. You just need to use a different answers file -for each one. All of them contain a `[[ _copier_conf.answers_file ]].tmpl` file +for each one. All of them contain a `{{ _copier_conf.answers_file }}.jinja` file [as specified above](#the-copier-answersyml-file). Then you apply all the templates to the same project: diff --git a/docs/creating.md b/docs/creating.md index 86ded15d0..fca857ba6 100644 --- a/docs/creating.md +++ b/docs/creating.md @@ -3,18 +3,15 @@ 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 `.tmpl`** (or +without changes, **unless they end with `.jinja`** (or [your chosen suffix](configuring.md#templates_suffix)). In that case, the templating engine will be used to render them. -A slightly customized Jinja2 templating is used. The main difference is those variables -are referenced with `[[ name ]]` instead of `{{ name }}` and blocks are `[% if name %]` -instead of `{% if name %}`. To read more about templating see the +Jinja2 templating is used. Learn more about it by reading [Jinja2 documentation](https://jinja.palletsprojects.com/). -If a **YAML** file named `copier.yml` is found in the root of the project -(alternatively, a YAML file named `copier.yaml`), the user will be prompted to fill in -or confirm the default values. +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. ## Template helpers @@ -22,28 +19,23 @@ In addition to [all the features Jinja supports](https://jinja.palletsprojects.com/en/2.11.x/templates/), Copier includes: -### Builtin variables/functions +- 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. -- `now()` to get current UTC time. -- `make_secret()` to get a random string. - `_copier_answers` includes the current answers dict, but slightly modified to make it suitable to [autoupdate your project safely](configuring.md#the-answers-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 the current copier `ConfigData` object, also slightly - modified: +- `_copier_conf` includes a representation of the current copier + + [Worker][copier.main.Worker] object, also slightly modified: - It only contains JSON-serializable data. - - But you have to serialize it with `[[ _copier_conf.json() ]]` instead of - `[[ _copier_conf|tojson ]]`. + - But you have to serialize it with `{{ _copier_conf.json() }}` instead of + `{{ _copier_conf|to_json }}`. - ⚠️ It contains secret answers inside its `.data` key. - Modifying it doesn't alter the current rendering configuration. - -### Builtin filters - -- `anything|to_nice_yaml` to print as pretty-formatted YAML. - - Without arguments it defaults to: - `anything|to_nice_yaml(indent=2, width=80, allow_unicode=True)`, but you can modify - those. diff --git a/docs/generating.md b/docs/generating.md index b64a297ad..647623635 100644 --- a/docs/generating.md +++ b/docs/generating.md @@ -1,7 +1,9 @@ # Generating a project -**Warning:** Generate projects only from trusted templates as their tasks run with the -same level of access as your user. +!!! warning + + Generate projects only from trusted templates as their tasks run with the + same level of access as your user. As seen in the quick usage section, you can generate a project from a template using the `copier` command-line tool: @@ -13,7 +15,7 @@ copier path/to/project/template path/to/destination Or within Python code: ```python -copier.copy("path/to/project/template", "path/to/destination") +copier.run_auto("path/to/project/template", "path/to/destination") ``` The "template" parameter can be a local path, an URL, or a shortcut URL: @@ -21,9 +23,9 @@ The "template" parameter can be a local path, an URL, or a shortcut URL: - GitHub: `gh:namespace/project` - GitLab: `gl:namespace/project` -Use the `--data` command-line argument or the `data` parameter of the `copier.copy()` -function to pass whatever extra context you want to be available in the templates. The -arguments can be any valid Python value, even a function. +Use the `--data` command-line argument or the `data` parameter of the +`copier.run_auto()` function to pass whatever extra context you want to be available in +the templates. The arguments can be any valid Python value, even a function. Use the `--vcs-ref` command-line argument to checkout a particular git ref before generating the project.