Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Updating !include documentation for clarity #1496

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: Updating !include documentation for clarity #1496

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d9f6330
Updating !include documentation for clarity
Feb 2, 2024
82c2fcc
Correcting explanation, giving minimal example
Feb 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 38 additions & 13 deletions docs/configuring.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -383,19 +383,7 @@ cannot use Jinja templating in your answers.
The `copier.yml` file supports multiple documents as well as using the `!include` tag to
include settings and questions from other YAML files. This allows you to split up a
larger `copier.yml` and enables you to reuse common partial sections from your
templates. When multiple documents are used, care has to be taken with questions and
settings that are defined in more than one document:

- A question with the same name overwrites definitions from an earlier document.
- Settings given in multiple documents for `exclude`, `skip_if_exists`,
`jinja_extensions` and `secret_questions` are concatenated.
- Other settings (such as `tasks` or `migrations`) overwrite previous definitions for
these settings.

!!! hint

You can use [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
to sanely include shared code into templates.
templates.

!!! example

Expand Down Expand Up @@ -432,6 +420,43 @@ settings that are defined in more than one document:
- "pyproject.toml"
```

The structure of includes is quite restrictive: they must come at the top of the yaml
file, and end with `---` on a new line.

!!! example

This is an _invalid_ copier.yml file:

```yaml title="copier-invalid.yml"
version:
type: str
help: What is the version of your Python project?

!include copier-other.yml
```

This is invalid twice over: we haven't put the `!include` directive at the top
Copy link

@ssteinerx ssteinerx Feb 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about just demonstrating and immediately annotating the correct syntax:

!include copier-other.yml
---

Please note that the !include directive MUST be the first line in the file.

The line after the directive must contain only three dashes and a newline character as shown above.

Anything else is invalid and will not work.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please note that the !include directive MUST be the first line in the file.

The line after the directive must contain only three dashes and a newline character as shown above.

Anything else is invalid and will not work.

That's not correct. The !include directive can appear anywhere in copier.yml as long as it's placed in a separate YAML document. For instance:

  • copier.yml; 
    q1: hello
---
!include q2.yml
  • q2.yml: 
    q2: world

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, so the first example like this:

!include copier-other.yml
---

actually works because the !include is in the implicit "first document" and the -- marks the end of the first contained document and the beginning of the second.

Can there also be any number of !includes in the file, as long as there's only one per document?

Is this valid?

---  # explicit, optional "start of first document"
!include include1.yml
--- # end first, begin second document
!include include2.yml
--- # end second, begin third document
!include include3.yml
--- # and so forth...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes

of the file, and we haven't included `---` in a new line after it.

!!! hint

When working with multiple documents, you can use [`exclude`][exclude]
to exclude them from the rendered project.

When multiple documents are used, care has to be taken with questions and
settings that are defined in more than one document:

- A question with the same name overwrites definitions from an earlier document.
- Settings given in multiple documents for `exclude`, `skip_if_exists`,
`jinja_extensions` and `secret_questions` are concatenated.
- Other settings (such as `tasks` or `migrations`) overwrite previous definitions for
these settings.

!!! hint

You can use [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
to sanely include shared code into templates.

## Conditional files and directories

You can take advantage of the ability to template file and directory names to make them
Expand Down