0
# Core Operations
1

2
The primary functions for template processing in Copier. These functions provide the essential operations for project generation and maintenance workflows.
3

4
## Capabilities
5

6
### Project Generation
7

8
Generate a new project from a template source (local path or Git repository).
9

10
```python { .api }
11
def run_copy(
12
    src_path: str,
13
    dst_path: StrOrPath = ".",
14
    data: AnyByStrDict | None = None,
15
    **kwargs: Any
16
) -> Worker:
17
    """
18
    Copy a template to a destination from zero.
19
    
20
    Parameters:
21
    - src_path (str): Template source path (local or Git URL)
22
    - dst_path (StrOrPath): Destination path for the new project
23
    - data (dict, optional): Answers to template questions
24
    - **kwargs: Additional configuration options
25
    
26
    Returns:
27
    Worker: Configured worker instance after generation
28
    """
29
```
30

31
Usage examples:
32

33
```python
34
from copier import run_copy
35

36
# Generate from Git repository
37
worker = run_copy(
38
    src_path="https://github.com/copier-org/copier.git",
39
    dst_path="./my-project",
40
    data={"project_name": "MyApp", "author": "Jane Doe"}
41
)
42

43
# Generate from local template
44
worker = run_copy(
45
    src_path="./my-template",
46
    dst_path="./new-project",
47
    data={"version": "1.0.0"}
48
)
49

50
# Use specific Git ref
51
worker = run_copy(
52
    src_path="https://github.com/user/template.git",
53
    dst_path="./project",
54
    vcs_ref="v2.0.0",
55
    data={"feature_enabled": True}
56
)
57
```
58

59
### Project Updates
60

61
Update an existing project when the template evolves, preserving local changes and applying template updates.
62

63
```python { .api }
64
def run_update(
65
    dst_path: StrOrPath = ".",
66
    data: AnyByStrDict | None = None,
67
    **kwargs: Any
68
) -> Worker:
69
    """
70
    Update a subproject from its template with evolution.
71
    
72
    Parameters:
73
    - dst_path (StrOrPath): Path to existing project to update
74
    - data (dict, optional): New or updated answers
75
    - **kwargs: Additional configuration options
76
    
77
    Returns:
78
    Worker: Configured worker instance after update
79
    """
80
```
81

82
Usage examples:
83

84
```python
85
from copier import run_update
86

87
# Update current directory project
88
worker = run_update()
89

90
# Update specific project with new data
91
worker = run_update(
92
    dst_path="./my-project",
93
    data={"new_feature": True, "version": "2.0.0"}
94
)
95

96
# Update to specific template version
97
worker = run_update(
98
    dst_path="./my-project",
99
    vcs_ref="v3.0.0"
100
)
101
```
102

103
### Project Regeneration
104

105
Regenerate a project from its template, discarding evolution but keeping user answers.
106

107
```python { .api }
108
def run_recopy(
109
    dst_path: StrOrPath = ".",
110
    data: AnyByStrDict | None = None,
111
    **kwargs: Any
112
) -> Worker:
113
    """
114
    Update a subproject from its template, discarding evolution.
115
    
116
    Parameters:
117
    - dst_path (StrOrPath): Path to existing project to regenerate
118
    - data (dict, optional): Updated answers for regeneration
119
    - **kwargs: Additional configuration options
120
    
121
    Returns:
122
    Worker: Configured worker instance after regeneration
123
    """
124
```
125

126
Usage examples:
127

128
```python
129
from copier import run_recopy
130

131
# Regenerate current directory project
132
worker = run_recopy()
133

134
# Regenerate with updated answers
135
worker = run_recopy(
136
    dst_path="./my-project",
137
    data={"template_version": "latest", "cleanup": True}
138
)
139
```
140

141
## Common Configuration Options
142

143
All core operations accept these common keyword arguments:
144

145
- `vcs_ref` (str): Git tag, branch, or commit to use
146
- `answers_file` (str): Path to answers file (default: ".copier-answers.yml")  
147
- `exclude` (list): File patterns to exclude from processing
148
- `skip_if_exists` (list): File patterns to skip if they exist
149
- `overwrite` (bool): Whether to overwrite existing files
150
- `defaults` (bool): Use default answers without prompting
151
- `pretend` (bool): Perform dry run without actual changes
152
- `quiet` (bool): Suppress output during processing
153
- `cleanup_on_error` (bool): Delete destination on error
154
- `unsafe` (bool): Allow potentially unsafe template features
155

156
## Return Value
157

158
All core operations return a `Worker` instance that can be used for:
159

160
- Accessing generated project metadata
161
- Retrieving template processing results
162
- Chaining additional operations
163
- Context manager usage for cleanup
164

165
```python
166
# Using returned worker
167
worker = run_copy("template/", "project/")
168
print(f"Template used: {worker.template}")
169
print(f"Answers: {worker.data}")
170

171
# Context manager usage
172
with run_copy("template/", "project/") as worker:
173
    # Additional processing
174
    pass
175
```