Updating a project comes in two flavors. Updating to incorporate a new version of the template, or updating one or more specific responses to the questions used to hydrate the project.
Either way, the process starts with a single-line command in the directory containing your project:
>> copier update ./<project directory>
As LINCC Frameworks release new template features, you can keep your project up to date by running the copier
command which will do two things.
- Bring in any updates to the template.
- Provide an opportunity to update responses used to hydrate the project.
While that may sound trivial, Copier uses a (necessarily) complicated workflow to do this successfully. Take a look at the Copier documentation get an appreciation for complexity of the task.
Note
While the update is running, you'll likely be asked if you want to overwrite files where the changes can't be automatically merged. For example, you might see this on the command line:
>> copier update
...
identical README.md
identical tests
conflict .pre-commit-config.yaml
Overwrite .pre-commit-config.yaml? [Y/n]
Responding y
will allow Copier to attempt to update a file. While n
will usually result in the creation of a .rej
file - .pre-commit-config.yaml.rej
in this case. The contents will resemble a git merge conflict, and allow you to decide how to incorporate the template changes.
Remember, don't commit .rej
files, you should remove them as the merge conflicts are resolved.
Once Copier has finished, you should run git diff
to see what code has changed. If you don't like the new changes, you can always revert back to the previous state.
If you change any of the initial responses during the update you should take some time to review your project for any files or directories that are no longer needed.
For instance, if you change the package_name
response from "new_project" to "great_project", it is unlikely that Copier will be able to create a new directory structure, move and rename your existing files, and remove the old directory structure.
The pyproject.toml file is the primary configuration file for your project. When a project is initially hydrated from the template, a custom pyproject.toml file will be created. Generally Copier updates won't significantly affect this file, so be sure to take a close look at any differences.
If something looks incorrect, remember that changes made by Copier are only staged for commit, they are't permanent and can easily be unstaged.
By default, Copier will find and apply the latest tagged release of a template when creating or updating a project. However, there may be new template features that you want to incorporate into your project before they are tagged for release. Copier provides the --vcs-ref
flag for this purpose.
>> copier update --vcs-ref=HEAD
Here Copier will use the latest template from the main
branch and apply it to your project. Note that HEAD
can be replaced with any reasonable git tag such as a branch name or commit hash.
The documentation for Copier indicates that it is a bad idea to manually edit the file that records your responses to the template questions. If you decide that you answered one of the questions incorrectly or you just want to update the response, you can change it without having to edit the rest.
>> copier update --force --data <question_name>="new answer"
This tells copier to use the previous answers for all questions except the one you want to update. Copier will not attempt to update the template, and it will not review the responses to the questions.
For example, if you initialized your project by selecting pylint
as your preferred linter, but now would like to change to black
, you could use the following command:
>> copier update --force --data include_benchmarks=true
The full list of questions can be found here.
Depending on the response that is being updated there may be several files that are changed. See the note above about merge conflicts and .rej
files for more context.
Remember, the changes from these updates are only staged for commit, they aren't permanent and can easily be unstaged.
The maintainers of Copier have written good instructions and there's no point in reproducing it all here. For all the details about updating with Copier checkout the original documentation.
/source/contact