Cookiecutter
A command-line utility that creates projects from cookiecutters (project templates), e.g. creating a Python package project from a Python package project template.
Features
Did someone say features?
-
Cross-platform: Windows, Mac, and Linux are officially supported.
-
Works with Python 2.7, 3.3, 3.4, 3.5, 3.6, and PyPy. (But you don't have to
know/write Python code to use Cookiecutter.) -
Project templates can be in any programming language or markup format:
Python, JavaScript, Ruby, CoffeeScript, RST, Markdown, CSS, HTML, you name
it. You can use multiple languages in the same project template. -
Simple command line usage:
.. code-block:: bash
# Create project from the cookiecutter-pypackage.git repo template # You'll be prompted to enter values. # Then it'll create your Python package in the current working directory, # based on those values. $ cookiecutter https://github.com/audreyr/cookiecutter-pypackage # For the sake of brevity, repos on GitHub can just use the 'gh' prefix $ cookiecutter gh:audreyr/cookiecutter-pypackage
-
Use it at the command line with a local template:
.. code-block:: bash
# Create project in the current working directory, from the local # cookiecutter-pypackage/ template $ cookiecutter cookiecutter-pypackage/
-
Or use it from Python:
.. code-block:: python
from cookiecutter.main import cookiecutter # Create project from the cookiecutter-pypackage/ template cookiecutter('cookiecutter-pypackage/') # Create project from the cookiecutter-pypackage.git repo template cookiecutter('https://github.com/audreyr/cookiecutter-pypackage.git')
-
Directory names and filenames can be templated. For example::
{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}.py
-
Supports unlimited levels of directory nesting.
-
100% of templating is done with Jinja2. This includes file and directory names.
-
Simply define your template variables in a
cookiecutter.json
file. For example:.. code-block:: json
{ "full_name": "Audrey Roy", "email": "[email protected]", "project_name": "Complexity", "repo_name": "complexity", "project_short_description": "Refreshingly simple static site generator.", "release_date": "2013-07-10", "year": "2013", "version": "0.1.1" }
-
Unless you suppress it with
--no-input
, you are prompted for input:- Prompts are the keys in
cookiecutter.json
. - Default responses are the values in
cookiecutter.json
. - Prompts are shown in order.
- Prompts are the keys in
-
Cross-platform support for
~/.cookiecutterrc
files:.. code-block:: yaml
default_context: full_name: "Audrey Roy" email: "[email protected]" github_username: "audreyr" cookiecutters_dir: "~/.cookiecutters/"
-
Cookiecutters (cloned Cookiecutter project templates) are put into
~/.cookiecutters/
by default, or cookiecutters_dir if specified. -
If you have already cloned a cookiecutter into
~/.cookiecutters/
, you
can reference it by directory name:.. code-block:: bash
# Clone cookiecutter-pypackage $ cookiecutter gh:audreyr/cookiecutter-pypackage # Now you can use the already cloned cookiecutter by name $ cookiecutter cookiecutter-pypackage
-
You can use local cookiecutters, or remote cookiecutters directly from Git
repos or from Mercurial repos on Bitbucket. -
Default context: specify key/value pairs that you want used as defaults
whenever you generate a project -
Inject extra context with command-line arguments:
.. code-block:: bash
$ cookiecutter --no-input gh:msabramo/cookiecutter-supervisor program_name=foobar startsecs=10
-
Direct access to the Cookiecutter API allows for injection of extra context.
-
Pre- and post-generate hooks: Python or shell scripts to run before or after
generating a project. -
Paths to local projects can be specified as absolute or relative.
-
Projects are always generated to your current directory.