Cookiecutter is a cross-platform software tool that generates boilerplate for software projects from templates. These templates, called cookiecutters, can be used to define how a project's directories and files are named and organized as well as the content of its files. They can also facilitate, both manually and automatically, the run-time customization of the generated names and content.
The cookiecutter presented here, Cookiecutter Cookiecutter, defines a boilerplate template for creating cookiecutters themselves. The resulting boilerplate is a basic directory tree and a starter set of files for beginning a new cookiecutter project. Included in these files are:
- A store for defining template variables that, by default, prompt the user for input;
- Python scripts to run before or after generating boilerplate.
Boilerplate from Cookiecutter Cookiecutter can be generated by running shell or Python scripts. Furthermore, during boilerplate generation, Cookiecutter Cookiecutter itself can be sourced remotely via a direct download or locally via a cached copy from a prior download. The subsections that follow show the syntactic differences for each aforementioned approach.
The command cookiecutter generates boilerplate from a shell's command-line interface (CLI). The argument following cookiecutter specifies both the cookiecutter (which, in this case, references Cookiecutter Cookiecutter) and whether its source is remote or local.
-
Remote source:
# The following syntax options are semantically equivalent. # Option 1: URL $ cookiecutter https://github.com/djrlj694/cookiecutter-cookiecutter.git # Option 2: 'gh' prefix $ cookiecutter gh:djrlj694/cookiecutter-cookiecutter # Option 3: 'git+ssh' prefix $ cookiecutter git+ssh://git@github.com/djrlj694/cookiecutter-cookiecutter.git
-
Local source:
$ cookiecutter cookiecutter-cookiecutter/
The Python library cookiecutter.main provides an application programming interface (API) for calling Cookiecutter functions to generate boilerplate.
-
Remote source:
from cookiecutter.main import cookiecutter cookiecutter('https://github.com/djrlj694/cookiecutter-cookiecutter.git')
-
Local source:
from cookiecutter.main import cookiecutter cookiecutter('cookiecutter-cookiecutter/')
The cookiecutter.json file, located in the root directory of a cookiecutter repository (i.e., in the same directory as the cookiecutter itself), specifies run-time customization options for generating a new repository. These options are encoded as JSON key/value pairs. Each key denotes a template variable (e.g., {{cookiecutter.JSON_KEY}}), whereas each value denotes either a default value or an array of legal values for its respective key. Together with Jinja2 as a template language, cookiecutter.json can be used to customize the names of directories and files as well as the content within files.
Customization options defined in Cookiecutter Cookiecutter's cookiecutter.json are as follows:
| Key | Description | Value(s) | Default Value |
|---|---|---|---|
repo_name |
The repository's name as it would appear in documents (e.g., with spaces and mixed-case) | N/A | REPO_NAME |
repo_dir |
The GitHub-conforming name of the repository's root directory | N/A | A lower-case, hyphenated version of the value of repo_name |
repo_license |
The repository's optional (but highly recommended) open-source software licence | Not open source, Apache Software License 2.0, BSD-3, GNU GPL v3.0, MIT |
Not open source |
lead_name |
The name of the repository's lead author | N/A | LEAD_NAME |
lead_email |
The email address of the repository's lead author | N/A | USER@DOMAIN.TLD |
By default, the user is prompted to assign a value for each key. This cookiecutter feature may also be silenced. The subsections that follow show how.
$ cookiecutter --no-input ...cookiecutter(..., no_input=True)Cookiecutter Cookiecutter supports the 3 major operating systems:
- Linux
- macOS
- Windows
To use Cookiecutter Cookiecutter, the following software must first be installed on your system:
- Python 2.7, 3.4, 3.5, 3.3, or PyPy
- Cookiecutter Python package 1.6.0 or higher
For info on installing any of the prerequisite software, refer to the official installation document.
Currently, there are no known issues. If you discover any, please kindly submit a pull request.
Code and codeless (documentation, donations, etc.) contributions are welcome. To contribute yours, see CONTRIBUTING.md.
Cookiecutter Cookiecutter is released under the MIT License.
API documentation, tutorials, and other online references and made portions of this project possible. See REFERENCES.md for a list of some.