Skip to content

Commit 4debab7

Browse files
committed
Add pipx install instructions + explanation
1 parent 227f82b commit 4debab7

1 file changed

Lines changed: 17 additions & 4 deletions

File tree

README.md

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,17 +48,26 @@ There are multiple scenarios to use this template:
4848
[Scenario 2](#scenario-2-apply-to-pre-existing-code): Applying the template to some pre-existing code
4949
[Scenario 3](#scenario-3-updating-a-template-made-package): Updating a package made with the template
5050

51-
In all three scenarios, you will need to install copier first:
51+
In all three scenarios, you will need to install Copier first, which we
52+
recommend doing with [`pipx`](https://github.com/pypa/pipx):
5253
```shell
54+
python3 -m pip install --user pipx
55+
python3 -m pipx ensurepath
5356
pipx install copier
5457
```
5558

59+
> [!NOTE]
60+
> Note that it is also possible to install Copier with regular `pip`, but that
61+
> Copier will then be installed in your common environment and may cause
62+
> conflicts with its dependencies, while `pipx` will install Copier in a
63+
> separate and dedicated environment.
64+
5665
### Scenario 1: Create a new package
5766

5867

5968
#### Step 1/2: Create the files and directory structure
6069

61-
Run `copier` with the template:
70+
Run `copier copy` with the template:
6271

6372
```shell
6473
# Notes:
@@ -155,7 +164,7 @@ containing your existing code rather than a new one:
155164
copier copy https://github.com/nlesc/python-template.git path/to/existing/code
156165
```
157166

158-
This works because if `path/to/destination` already exists, `copier` will
167+
This works because if `path/to/destination` already exists, Copier will
159168
update what is already there by either adding new files or updating
160169
existing files. Copier will ask to overwrite any files that resulted in
161170
conflicts. Especially if your files are already under version control, it is
@@ -171,14 +180,18 @@ created project using the `copier update` command. This has two effects:
171180
2. You can change any of your previous answers to apply these changes
172181
throughout your entire project.
173182

183+
> [!CAUTION]
184+
> Do not manually update answers in `.copier-answers.yml`,
185+
> as it will result in unexpected behavior.
186+
174187
```shell
175188
cd path/to/project
176189
copier update
177190
```
178191

179192
If you don't want to change any of your answers, but only want to update your
180193
project according to the latest template updates, you can provide the
181-
`--skip-answered` option. This tells copier to reuse all of your previous
194+
`--skip-answered` option. This tells Copier to reuse all of your previous
182195
answers, and simply bring in all updates from the template into
183196
your current project, such as updating which Python versions are supported.
184197
You will still be asked to answer any new questions that have been added to

0 commit comments

Comments
 (0)