/ Command-line Tools

A command-line utility that creates projects from cookiecutters

A command-line utility that creates projects from cookiecutters

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.
  • 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.

GitHub