Skip to content

Commit 30c9667

Browse files
committed
docs: Add --vcs-ref=HEAD and --trust requirements for GitHub integration testing
1 parent 0448326 commit 30c9667

1 file changed

Lines changed: 71 additions & 25 deletions

File tree

README.md

Lines changed: 71 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -42,17 +42,27 @@ The following tools must be installed:
4242
```
4343
Replace `/path/to/copier-template` with the path to this template, and `/path/to/your-repo` with your target repository.
4444

45+
**Note:** If you're testing with unreleased template changes, use `--vcs-ref=HEAD`:
46+
```bash
47+
copier copy --vcs-ref=HEAD /path/to/copier-template /path/to/your-repo
48+
```
49+
4550
3. **Generate non-interactively using the provided sample data file:**
4651
A sample data file is provided at `examples/config-basic.yml`.
4752
```bash
4853
copier copy --data-file examples/config-basic.yml /path/to/copier-template /path/to/your-repo
4954
```
5055
You can duplicate and modify that file to create variants (e.g., `data-with-ruff.yml`).
5156

57+
**Note:** This template uses conditional tasks (see [Tasks Behavior](#-tasks-behavior-with-different-copier-commands)), which require the `--trust` flag:
58+
```bash
59+
copier copy --trust --data-file examples/config-basic.yml /path/to/copier-template /path/to/your-repo
60+
```
61+
5262
4. **(Optional) Override specific values at the CLI:**
5363
You can still override one or more answers on the fly:
5464
```bash
55-
copier copy --data-file examples/config-basic.yml -d project_name=override_name /path/to/template /dest
65+
copier copy --trust --data-file examples/config-basic.yml -d project_name=override_name /path/to/template /dest
5666
```
5767

5868
5. **Review and commit the generated files:**
@@ -66,44 +76,80 @@ The following tools must be installed:
6676

6777
This template uses **conditional tasks** to manage optional features (LICENSE file, GitHub integration). Understanding their behavior is important for safe updates:
6878

79+
#### Task Execution Process
80+
Tasks always run at the end of both `copier copy` and `copier update` operations, **after** all files are generated. This means:
81+
- Files are created/updated first
82+
- Tasks execute based on your current answers
83+
- Any deletions from tasks are permanent for that operation
84+
6985
#### 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
86+
When you generate a new project with conditions set:
87+
-`include_license=true` → LICENSE file is kept
88+
-`include_license=false``LICENSE` file is **removed** after generation
89+
-`github_integration=true``.github/` files (templates, workflows) are kept
90+
-`github_integration=false``.github/` directory is **removed** after generation
7391

7492
#### 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`)
93+
**Tasks are executed again** during updates. This is important:
94+
- ✅ Safe with `--defaults` (keeps your previous answers as-is)
95+
- ✅ Safe if you keep boolean settings unchanged
96+
- ⚠️ **Dangerous if you change boolean settings** when you have customizations
97+
98+
#### Safe Update Commands
7899

79-
**Example problematic scenario:**
100+
**Recommended - Keeps all previous answers:**
80101
```bash
81-
# Initial generation with github_integration=true
82-
copier copy --data-file config.yml /template /my-project
102+
copier update --defaults --trust
103+
# Your github_integration and include_license settings remain unchanged
104+
```
83105

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!
106+
**Safe if no customizations in affected directories:**
107+
```bash
108+
copier update --trust --data github_integration=false
109+
# OK if you haven't customized .github/ subdirectories
88110
```
89111

90-
#### Safe Update Practices
91-
1. **Keep boolean settings unchanged:**
112+
#### Dangerous Update Scenario ⚠️
113+
114+
```bash
115+
# Initial generation WITH GitHub integration
116+
copier copy --trust --vcs-ref=HEAD \
117+
--data project_name=myproject \
118+
--data github_integration=true \
119+
/template /myproject
120+
121+
# Later: You customize workflows in .github/workflows/
122+
123+
# Then: Update but accidentally change github_integration to false
124+
copier update --trust --data github_integration=false
125+
# Result: 🔴 rm -rf .github DELETES ALL CUSTOM WORKFLOWS!
126+
```
127+
128+
#### Safe Alternative for Disabling Features
129+
130+
If you need to disable GitHub integration after customizing `.github/`:
131+
132+
1. **Manually back up your customizations:**
92133
```bash
93-
# Good: Reuse all previous answers
94-
copier update --defaults
134+
cp -r .github/workflows /tmp/my-workflows-backup
135+
cp LICENSE /tmp/my-license-backup # if customized
95136
```
96137

97-
2. **Only change settings if there are no customizations in those directories:**
138+
2. **Run the update to disable features:**
98139
```bash
99-
# OK if .github/ hasn't been customized
100-
copier update --data github_integration=false
140+
copier update --trust --data github_integration=false
101141
```
102142

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
143+
3. **Restore your customizations:**
144+
```bash
145+
cp -r /tmp/my-workflows-backup /path/to/.github/workflows
146+
```
147+
148+
4. **Commit your changes:**
149+
```bash
150+
git add .github/
151+
git commit -m "Restore custom workflows"
152+
```
107153

108154
### 📦 Answers Files Explained
109155
| File | Purpose |

0 commit comments

Comments
 (0)