Skip to content

Commit 79cea70

Browse files
committed
update usage instruction to explain 3 ways to use copier
1 parent b805491 commit 79cea70

1 file changed

Lines changed: 57 additions & 6 deletions

File tree

README.md

Lines changed: 57 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -42,20 +42,29 @@ Use this [Copier](https://copier.readthedocs.io) template to generate an empty P
4242

4343
## How to use
4444

45-
### Step 1/3: Install `copier`
45+
There are multiple ways to use this template:
4646

47+
1. Creating a new package based on the template
48+
2. Applying the template's best practices to some pre-existing code
49+
3. Updating a package made with the template based on the latest template updates
50+
51+
In all three cases, you will need to install copier first:
4752
```shell
4853
pipx install copier
4954
```
5055

51-
### Step 2/3: Generate the files and directory structure
56+
### Option 1: Create a new package
57+
58+
59+
#### Step 1/2: Generate the files and directory structure
5260

5361
Run `copier` with the template:
5462

5563
```shell
5664
# Notes:
57-
# 1. See table below for explanation of each question
58-
# 2. The files will be generated in a new directory
65+
# 1. Make sure that `path/to/destination` is an empty directory
66+
# 2. See table below for explanation of each question
67+
# 3. The files will be generated in the specified destination directory
5968
copier copy https://github.com/nlesc/python-template.git path/to/destination
6069
```
6170

@@ -76,7 +85,7 @@ copier copy https://github.com/nlesc/python-template.git path/to/destination
7685
Once the project files have been generated, follow the steps outlined in
7786
[template/next_steps.md](template/next_steps.md).
7887

79-
### Step 3/3: Read about what was just generated
88+
#### Step 2/2: Read about what was just generated
8089

8190
Good job! You have now generated the skeleton for your package:
8291

@@ -135,7 +144,49 @@ Good job! You have now generated the skeleton for your package:
135144
```
136145

137146
For an explanation of what's there, read on in the [project_setup.md](template/project_setup.md) file.
138-
There are also instructions on how to [apply the template to an existing Python package](ADD_TO_EXISTING_PACKAGE.md).
147+
148+
### Option 2: Apply to pre-existing code
149+
150+
To apply the template to pre-existing code, you can use the same `copier copy`
151+
command as when creating a new package, except that you point to the folder
152+
containing your existing code rather than a new one:
153+
154+
```shell
155+
copier copy https://github.com/nlesc/python-template.git path/to/existing/code
156+
```
157+
158+
This works because if `path/to/destination` already exists, `copier` will
159+
update what is already there by either adding new files or updating
160+
existing files. Copier will ask to overwrite any files that resulted in
161+
conflicts. Especially if your files are already under version control, it is
162+
recommended to answer 'yes' for all files, you will still be able to review
163+
the changes suggested by the template.
164+
165+
### Option 3. Updating a template-made package
166+
167+
Copier provides the functionality for re-applying the template to a previously
168+
created project using the `copier update` command. This has two effects:
169+
170+
1. Your project will be updated according to the latest version of the template
171+
2. You can change any of your previous answers to apply these changes
172+
throughout your entire project.
173+
174+
```shell
175+
cd path/to/project
176+
copier update
177+
```
178+
179+
If you don't want to change any of your answers, but only want to update your
180+
project according to the latest template updates, you can provide the
181+
`--skip-answered` option. This tells copier to reuse all of your previous
182+
answers, and simply bring in all updates from the template into
183+
your current project, such as updating which Python versions are supported.
184+
You will still be asked to answer any new questions that have been added to
185+
the template since you last applied it.
186+
187+
```shell
188+
copier update --skip-answered
189+
```
139190

140191
## Examples
141192

0 commit comments

Comments
 (0)