mirror of
https://github.com/copier-org/copier.git
synced 2025-05-28 02:21:18 +00:00
76 lines
2.5 KiB
Markdown
76 lines
2.5 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 path/to/project/template path/to/destination
|
|
```
|
|
|
|
Or within Python code:
|
|
|
|
```python
|
|
copier.run_auto("path/to/project/template", "path/to/destination")
|
|
```
|
|
|
|
The "template" parameter can be a local path, an URL, or a shortcut URL:
|
|
|
|
- GitHub: `gh:namespace/project`
|
|
- GitLab: `gl:namespace/project`
|
|
|
|
Use the `--data` command-line argument or the `data` parameter of the
|
|
`copier.run_auto()` 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.
|
|
|
|
The exception to this is if you use a local clone of a template repository that has had
|
|
any modifications made, in this case 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`](../configuring/#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 --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:
|
|
|
|
```shell
|
|
copier --vcs-ref HEAD path/to/project/template path/to/destination
|
|
```
|
|
|
|
!!! tip
|
|
|
|
If there are uncommited changes in the local template, they will be included in the `HEAD`
|
|
ref
|
|
|
|
## Regenerating a project
|
|
|
|
When you execute `copier copy $template $project` again over a preexisting `$project`,
|
|
Copier will just "recopy" it, 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.
|