0
# Copier
1
2
A library for rendering project templates from Git repositories with Jinja2 templating and interactive questionnaires. Copier enables developers to create, maintain, and evolve software project scaffolding from templates, supporting both local and remote Git-based templates with dynamic value replacement and project lifecycle management.
3
4
## Package Information
5
6
- **Package Name**: copier
7
- **Language**: Python
8
- **Installation**: `pip install copier`
9
10
## Core Imports
11
12
```python
13
from copier import run_copy, run_recopy, run_update
14
```
15
16
For advanced usage:
17
18
```python
19
from copier import Worker, Settings, VcsRef
20
from copier._types import Phase
21
```
22
23
For error handling:
24
25
```python
26
from copier.errors import (
27
CopierError, UserMessageError, UnsafeTemplateError,
28
ConfigFileError, PathError, TaskError
29
)
30
```
31
32
For CLI application:
33
34
```python
35
from copier._cli import CopierApp
36
```
37
38
For package version:
39
40
```python
41
from copier import __version__
42
```
43
44
## CLI Usage
45
46
```bash
47
# Install copier as a CLI tool
48
pipx install copier
49
# or
50
uv tool install copier
51
52
# Generate a project from a template
53
copier copy path/to/template path/to/destination
54
copier copy https://github.com/user/template.git ./my-project
55
56
# Update an existing project
57
copier update ./my-project
58
59
# Regenerate from template (discarding evolution)
60
copier recopy ./my-project
61
62
# Use specific template version
63
copier copy --vcs-ref=v2.0.0 template/ project/
64
65
# Provide answers without prompting
66
copier copy --data project_name="MyApp" template/ project/
67
```
68
69
## Basic Usage
70
71
```python
72
from copier import run_copy, run_recopy, run_update
73
74
# Generate a new project from a template
75
worker = run_copy(
76
src_path="https://github.com/copier-org/copier.git",
77
dst_path="./my-new-project",
78
data={"project_name": "MyProject", "author": "John Doe"}
79
)
80
81
# Update an existing project when template evolves
82
worker = run_update(
83
dst_path="./my-existing-project",
84
data={"new_feature": True}
85
)
86
87
# Regenerate project from template (discarding evolution)
88
worker = run_recopy(
89
dst_path="./my-existing-project"
90
)
91
```
92
93
## Architecture
94
95
Copier follows a three-tier architecture:
96
97
- **Template Processing**: Jinja2-based templating with custom extensions for dynamic file generation
98
- **Version Control Integration**: Git-based template versioning with support for tags, branches, and commits
99
- **User Interaction**: Interactive questionnaires with type validation and answer persistence
100
- **Project Lifecycle**: Support for initial generation, updates, and regeneration workflows
101
102
The Worker class serves as the main coordinator, managing template processing, user data collection, and file operations through a context manager pattern.
103
104
## Capabilities
105
106
### Core Operations
107
108
The primary functions for template processing: generating new projects, updating existing projects with template evolution, and regenerating projects from templates.
109
110
```python { .api }
111
def run_copy(
112
src_path: str,
113
dst_path: StrOrPath = ".",
114
data: AnyByStrDict | None = None,
115
**kwargs: Any
116
) -> Worker: ...
117
118
def run_update(
119
dst_path: StrOrPath = ".",
120
data: AnyByStrDict | None = None,
121
**kwargs: Any
122
) -> Worker: ...
123
124
def run_recopy(
125
dst_path: StrOrPath = ".",
126
data: AnyByStrDict | None = None,
127
**kwargs: Any
128
) -> Worker: ...
129
```
130
131
[Core Operations](./core-operations.md)
132
133
### Advanced Usage
134
135
The Worker class for fine-grained control over template processing, and Settings class for user configuration management.
136
137
```python { .api }
138
class Worker:
139
def __init__(
140
self,
141
src_path: StrOrPath | None = None,
142
dst_path: StrOrPath = ".",
143
**kwargs: Any
144
): ...
145
146
def run_copy(self) -> Worker: ...
147
def run_update(self) -> Worker: ...
148
def run_recopy(self) -> Worker: ...
149
150
class Settings:
151
defaults: dict[str, Any]
152
trust: set[str]
153
154
@classmethod
155
def from_file(cls, path: StrOrPath | None = None) -> Settings: ...
156
```
157
158
[Advanced Usage](./advanced-usage.md)
159
160
### Types and Enums
161
162
Type definitions, enums, and constants used throughout the copier API for type safety and configuration.
163
164
```python { .api }
165
class VcsRef(str, Enum):
166
CURRENT = ":current:"
167
168
class Phase(str, Enum):
169
PROMPT = "prompt"
170
TASKS = "tasks"
171
MIGRATE = "migrate"
172
RENDER = "render"
173
UNDEFINED = "undefined"
174
```
175
176
[Types and Enums](./types-enums.md)
177
178
### Error Handling
179
180
Comprehensive exception hierarchy for handling template processing errors, configuration issues, and user interaction problems.
181
182
```python { .api }
183
class CopierError(Exception): ...
184
class UserMessageError(CopierError): ...
185
class UnsafeTemplateError(CopierError): ...
186
class ConfigFileError(CopierError): ...
187
class PathError(CopierError): ...
188
class TaskError(CopierError): ...
189
```
190
191
[Error Handling](./error-handling.md)
192
193
### CLI Application
194
195
Command-line interface classes for running copier operations from the command line.
196
197
```python { .api }
198
class CopierApp:
199
"""Main CLI application class."""
200
201
@classmethod
202
def run(cls) -> None: ...
203
204
class CopierCopySubApp:
205
"""Copy subcommand application."""
206
207
class CopierRecopySubApp:
208
"""Recopy subcommand application."""
209
210
class CopierUpdateSubApp:
211
"""Update subcommand application."""
212
```
213
214
## Package Constants
215
216
```python { .api }
217
__version__: str # Package version string
218
```
219
220
## Common Type Aliases
221
222
```python { .api }
223
StrOrPath = Union[str, Path]
224
AnyByStrDict = dict[str, Any]
225
OptStrOrPath = Optional[StrOrPath]
226
JSONSerializable = Union[dict, list, str, int, float, bool, None]
227
```