Skip to content

docs: include full _copier_conf attributes list #2127

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

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

docs: include full _copier_conf attributes list #2127

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7bf6fa1
docs: clarifying _copier_conf attributes reference
wgordon17 May 5, 2025
7a0a10d
style: autoformat with pre-commit
autofix-ci[bot] May 31, 2025
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
3 changes: 3 additions & 0 deletions copier/_main.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,6 +217,9 @@ class Worker:
When `True`, skip template tasks execution.
"""

# NOTE: attributes are fully documented in [creating.md](../docs/creating.md)
# make sure to update documentation upon any changes.

src_path: str | None = None
dst_path: Path = Path()
answers_file: RelativePath | None = None
Expand Down
53 changes: 33 additions & 20 deletions docs/creating.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,27 +95,40 @@ suitable to [autoupdate your project safely][the-copier-answersyml-file]:

### `_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 }
!!! note

The current commit hash from the template.
- `_copier_conf` contains JSON-serializable data.
- `_copier_conf` can be serialized with `{{ _copier_conf|to_json }}`.
- ⚠️ `_copier_conf` may contain secret answers inside its `.data` key.
- Modifying `_copier_conf` doesn't alter the current rendering configuration.

Attributes:

| Name | Type | Description |
| ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `answers_file` | `Path` | The path for [the answers file][the-copier-answersyml-file] relative to `dst_path`.<br>See the [`answers_file`][] setting for related information. |
| `cleanup_on_error` | `bool` | When `True`, delete `dst_path` if there's an error.<br>See the [`cleanup_on_error`][] setting for related information. |
| `conflict` | `Literal["inline", "rej"]` | The output format of a diff code hunk when [updating][updating-a-project] a file yields conflicts.<br>See the [`conflict`][] setting for related information. |
| `context_lines` | `PositiveInt` | Lines of context to consider when solving conflicts in updates.<br>See the [`context_lines`][] setting for related information. |
| `data` | `dict[str, Any]` | Answers to the questionnaire, defined in the template, provided via CLI (`-d,--data`) or API (`data`).<br>See the [`data`][] setting for related information.<br>⚠️ May contain secret answers. |
| `defaults` | `bool` | When `True`, use default answers to questions.<br>See the [`defaults`][] setting for related information. |
| `dst_path` | `Path` | Destination path where to render the subproject.<br>⚠️ When [updating a project][updating-a-project], it may be a temporary directory, as Copier's update algorithm generates fresh copies using the old and new template versions in temporary locations. |
| `exclude` | `Sequence[str]` | Specified additional [file exclusion patterns][patterns-syntax].<br>See the [`exclude`][] setting for related information. |
| `os` | `str` | The detected operating system, either `"linux"`, `"macos"`, `"windows"` or `None`. |
| `overwrite` | `bool` | When `True`, overwrite files that already exist, without asking.<br>See the [`overwrite`][] setting for related information. |
| `pretend` | `bool` | When `True`, produce no real rendering.<br>See the [`pretend`][] setting for related information. |
| `quiet` | `bool` | When `True`, disable all output.<br>See the [`quiet`][] setting for related information. |
| `sep` | `str` | The operating system-specific directory separator. |
| `settings` | `pydantic.BaseModel` | Specified settings that control copier's behavior.<br>See the [`settings`][] page for related information. |
Copy link
Contributor Author

Choose a reason for hiding this comment

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

@sisp Thoughts on the content for this one?

| `skip_answered` | `bool` | When `True`, skip questions that have already been answered.<br>See the [`skip_answered`][] setting for related information. |
| `skip_if_exists` | `Sequence[str]` | Specified additional [file skip patterns][patterns-syntax].<br>See the [`skip_if_exists`][] setting for related information. |
| `skip_tasks` | `bool` | When `True`, skip [template tasks execution][tasks].<br>See the [`skip_tasks`][] setting for related information. |
| `src_path` | `Path` | The absolute path to the (cloned/downloaded) template on disk. |
| `unsafe` | `bool` | When `True`, allow usage of unsafe templates.<br>See the [`unsafe`][] setting for related information. |
| `use_prereleases` | `bool` | When `True`, `vcs_ref`/`vcs_ref_hash` may refer to a prerelease version of the template.<br>See the [`use_prereleases`][] setting for related information. |
| `user_defaults` | `dict[str, Any]` | Specified user defaults that may override a template's defaults during question prompts. |
| `vcs_ref` | `str | None` | The VCS tag/commit of the template, `None` if the template is not VCS-tracked.<br>See the [`vcs_ref`][] setting for related information. |
Copy link
Contributor Author

Choose a reason for hiding this comment

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

@sisp we might have to disable autoformat for this PR (not sure if you can). Leaving the \ in str \| None caused the \ to actually print in the assembled docs, however removing it causes autoformat to think that it's a column separator and add extra whitespace which then breaks the table layout 🤦‍♂️

| `vcs_ref_hash` | `str | None` | The VCS commit hash of the template, `None` if the template is not VCS-tracked. |

### `_copier_python`

Expand Down
Loading