What is Cookiecutter ?

Cookiecutter is a Command Line Interface tool to create an application boilerplate from a template. It uses a templating system Jinja2 to replace or customize folder and file names, as well as file content.

While Cookiecutter is built in Python and the examples shown in this article are in Python too, it can be used with any other programming language.

Mind that, to make your own Cookiecutter template you need to learn some Jinja, and to implement hooks you do need Python.

Why Cookiecutter ?

I use Cookiecutter to save time constructing a new repository, to avoid forgetting mandatory files like Readme or Changelog; and to lower the entry level to new collaborators, new team members, freelancers, partners.

In the case of connectors, which are rather simple programs, the code reuse is very high and most files are left almost unchanged from the generated ones, making it also a very powerful tool to save time increasing reusability.

How to use it ?

Cookiecutter can be used either with a Git repository, with a folder or even a Zip file. Also, if working with repositories, you can start your template from any branch. Some example calls:

cookiecutter my_local_template/
cookiecutter https://github.com/your_account/template_py.git
cookiecutter https://bitbucket.org/your_project/template_py.git --checkout develop

To try it out for real you can do the following with a repository available at Audrey R, Greenfeld’s account, creator of Cookiecutter:

pip install — user cookiecutter
cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git

This example uses a template meant for Python packages to be published in Pypi (the Python Package Index) . If you execute it, you will be asked for a few values, for example:

full_name [Audrey Roy Greenfeld]: Sage
version [0.1.0]: 1.0.0rc1
use_pytest [n]: y
Select command_line_interface:
1 — Click
2 — No command-line interface
Choose from 1, 2 [1]: 1

A Cookiecutter repository template looks something like this:

• cookiecutter.json
  — hooks
  | — pre_get_project.py
  | — post_get_project.py
  — [ README.md ]
  — [ CHANGELOG.md ]
  — {{cookiecutter.project_slug}}
  | — < your repository template here >

Cookiecutter.json is the key file in your template. It is a JSON with variables and choices, we will talk about it in the next section.

Hooks are python scripts with rules applicable before and after the repository generation. Personally I use the pre-hook to validate the choices you make and the post-hook to remove undesired files depending on those choices.

{{cookiecutter.project_slug}}/< your repository template here >
Here you will put your repository template with all the structure and content you want to replicate, placing template variables between double curly brackets {{ }} — and Jinja2 ifs and loops.

README.md and CHANGELOG.md are not mandatory, but I really recommend you to have them to explain in detail the choices available in the Json file and to to keep track of the template evolution.

This Readme and Changelog will not be present in the generated repository, there should be another Readme and Changelog within .

You can begin your own either from a bare repository adding all things you want, or copy an existing repository and start replacing names and content for variables, or removing undesired elements.

That's it! Thanks for reading!