mirror of
https://github.com/copier-org/copier.git
synced 2025-05-07 16:32:57 +00:00
9b0f2b6956
* Document behavior of generating destination path when copying * Update README.md Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr> * Update docs/generating.md Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr> * fix: run linting * Apply suggestions from code review * Apply suggestions from code review --------- Co-authored-by: Nathan Simpson <nsimpson@455-g7hgqf4ykt.cust.communityfibre.co.uk> Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>
81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
# Generating a project
|
|
|
|
!!! warning
|
|
|
|
Generate projects only from trusted templates as their tasks run with the
|
|
same level of access as your user.
|
|
|
|
As seen in the quick usage section, you can generate a project from a template using the
|
|
`copier` command-line tool:
|
|
|
|
```shell
|
|
copier copy path/to/project/template path/to/destination
|
|
```
|
|
|
|
Or within Python code:
|
|
|
|
```python
|
|
copier.run_copy("path/to/project/template", "path/to/destination")
|
|
```
|
|
|
|
If `path/to/destination` doesn't exist, Copier will create the directory and populate it
|
|
with the generated files. If `path/to/destination` exists, it must be writable (not
|
|
read-only).
|
|
|
|
The "template" parameter can be a local path, an URL, or a shortcut URL:
|
|
|
|
- GitHub: `gh:namespace/project`
|
|
- GitLab: `gl:namespace/project`
|
|
|
|
If Copier doesn't detect your remote URL as a Git repository, make sure it starts with
|
|
one of `git+https://`, `git+ssh://`, `git@` or `git://`, or it ends with `.git`.
|
|
|
|
Use the `--data` command-line argument or the `data` parameter of the
|
|
`copier.run_copy()` function to pass whatever extra context you want to be available in
|
|
the templates. The arguments can be any valid Python value, even a function.
|
|
|
|
Use the `--vcs-ref` command-line argument to checkout a particular Git ref before
|
|
generating the project.
|
|
|
|
[All the available options][copier.cli] are described with the `--help-all` option.
|
|
|
|
## Templates versions
|
|
|
|
By default, Copier will copy from the last release found in template Git tags, sorted as
|
|
[PEP 440](https://peps.python.org/pep-0440/), regardless of whether the template is from
|
|
a URL or a local clone of a Git repository.
|
|
|
|
### Copying dirty changes
|
|
|
|
If you use a local clone of a template repository that has had any uncommitted
|
|
modifications made, Copier will use this modified working copy of the template to aid
|
|
development of new template features.
|
|
|
|
If you would like to override the version of template being installed, the
|
|
[`--vcs-ref`][vcs_ref] argument can be used to specify a branch, tag or other reference
|
|
to use.
|
|
|
|
For example to use the latest master branch from a public repository:
|
|
|
|
```shell
|
|
copier copy --vcs-ref master https://github.com/foo/copier-template.git ./path/to/destination
|
|
```
|
|
|
|
Or to work from the current checked out revision of a local template (including dirty
|
|
changes):
|
|
|
|
```shell
|
|
copier copy --vcs-ref HEAD path/to/project/template path/to/destination
|
|
```
|
|
|
|
## Regenerating a project
|
|
|
|
When you execute `copier recopy $project` again over a preexisting `$project`, Copier
|
|
will just reapply the template on it, keeping answers but ignoring previous history.
|
|
|
|
!!! warning
|
|
|
|
This is not [the recommended approach for updating a project][updating-a-project],
|
|
where you usually want Copier to respect the project evolution wherever it doesn't
|
|
conflict with the template evolution.
|