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
```