Skip to content

Commit 0448326

Browse files
committed
docs: Add section explaining task behavior with copier copy and copier update
1 parent ad81126 commit 0448326

1 file changed

Lines changed: 43 additions & 0 deletions

File tree

README.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,49 @@ The following tools must be installed:
6262
git commit -m "feat: Bootstrap repository from template"
6363
```
6464

65+
### ⚠️ Tasks Behavior with Different Copier Commands
66+
67+
This template uses **conditional tasks** to manage optional features (LICENSE file, GitHub integration). Understanding their behavior is important for safe updates:
68+
69+
#### Initial Project Generation (`copier copy`)
70+
Tasks execute **after** files are created:
71+
- `include_license=false``LICENSE` file is removed
72+
- `github_integration=false``.github/` directory (with issue templates and workflows) is removed
73+
74+
#### Project Updates (`copier update`)
75+
**Tasks are executed again** during updates. This means:
76+
- ✅ Safe to run with `--defaults` (keeps your previous answers)
77+
- ⚠️ **Dangerous if you change boolean settings** (e.g., setting `github_integration=false`)
78+
79+
**Example problematic scenario:**
80+
```bash
81+
# Initial generation with github_integration=true
82+
copier copy --data-file config.yml /template /my-project
83+
84+
# Later: modify workflows, add custom issues templates
85+
# Then update but accidentally change github_integration to false:
86+
copier update --data github_integration=false
87+
# Result: 🔴 rm -rf .github deletes ALL custom workflows and templates!
88+
```
89+
90+
#### Safe Update Practices
91+
1. **Keep boolean settings unchanged:**
92+
```bash
93+
# Good: Reuse all previous answers
94+
copier update --defaults
95+
```
96+
97+
2. **Only change settings if there are no customizations in those directories:**
98+
```bash
99+
# OK if .github/ hasn't been customized
100+
copier update --data github_integration=false
101+
```
102+
103+
3. **If you need to disable a feature with customizations:**
104+
- Manually move/backup custom files from `.github/` or `LICENSE`
105+
- Then run the update
106+
- Restore your customizations afterward
107+
65108
### 📦 Answers Files Explained
66109
| File | Purpose |
67110
|------|---------|

0 commit comments

Comments
 (0)