1# ![Copier](https://github.com/copier-org/copier/raw/master/img/copier-logotype.png)
2
3[![codecov](https://codecov.io/gh/copier-org/copier/branch/master/graph/badge.svg)](https://codecov.io/gh/copier-org/copier)
4[![CI](https://github.com/copier-org/copier/workflows/CI/badge.svg)](https://github.com/copier-org/copier/actions?query=branch%3Amaster)
5[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
6![](https://img.shields.io/pypi/pyversions/copier)
7![](https://img.shields.io/pypi/v/copier)
8[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
9[![Documentation Status](https://readthedocs.org/projects/copier/badge/?version=latest)](https://copier.readthedocs.io/en/latest/?badge=latest)
10
11A library for rendering project templates.
12
13-   Works with **local** paths and **git URLs**.
14-   Your project can include any file and `Copier` can dynamically replace values in any
15    kind of text file.
16-   It generates a beautiful output and takes care of not overwrite existing files
17    unless instructed to do so.
18
19![Sample output](https://github.com/copier-org/copier/raw/master/img/copier-output.png)
20
21## Installation
22
231. Install Python 3.6.1 or newer (3.8 or newer if you're on Windows).
241. Install Git 2.24 or newer.
251. To use as a CLI app: `pipx install copier`
261. To use as a library: `pip install copier`
27
28## Quick usage
29
30-   Use it in your Python code:
31
32    ```python
33    from copier import copy
34
35    # Create a project from a local path
36    copy("path/to/project/template", "path/to/destination")
37
38    # Or from a git URL.
39    copy("https://github.com/copier-org/copier.git", "path/to/destination")
40
41    # You can also use "gh:" as a shortcut of "https://github.com/"
42    copy("gh:copier-org/copier.git", "path/to/destination")
43
44    # Or "gl:" as a shortcut of "https://gitlab.com/"
45    copy("gl:copier-org/copier.git", "path/to/destination")
46    ```
47
48-   Or as a command-line tool:
49
50    ```bash
51    copier path/to/project/template path/to/destination
52    ```
53
54## Browse or tag public templates
55
56You can browse public copier templates in GitHub using
57[the `copier-template` topic](https://github.com/topics/copier-template). Use them as
58inspiration!
59
60If you want your template to appear in that list, just add the topic to it! ��
61
62## Credits
63
64Special thanks go to [jpscaletti](https://github.com/jpscaletti) for originally creating
65`Copier`. This project would not be a thing without him.
66
67Many thanks to [pykong](https://github.com/pykong) who took over maintainership on the
68project, promoted it, and laid out the bases of what the project is today.
69
70Big thanks also go to [Yajo](https://github.com/Yajo) for his relentless zest for
71improving `Copier` even further.
72
73Thanks a lot, [pawamoy](https://github.com/pawamoy) for polishing very important rough
74edges and improving the documentation and UX a lot.
75