cookiecutter 1.5.1

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, 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:

  # 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:

  # Create project in the current working directory, from the local
  # cookiecutter-pypackage/ template
  $ cookiecutter cookiecutter-pypackage/

• Or use it from 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:

  {
      "full_name": "Audrey Roy",
      "email": "audreyr@gmail.com",
      "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:

  default_context:
      full_name: "Audrey Roy"
      email: "audreyr@gmail.com"
      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:

  # 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:

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

Available Cookiecutters

Making great cookies takes a lot of cookiecutters and contributors. We’re so pleased that there are many Cookiecutter project templates to choose from. We hope you find a cookiecutter that is just right for your needs.

Community

The core committer team is @audreyr, @pydanny, @michaeljoseph, @pfmoore, and @hackebrot. We welcome you and invite you to participate.

Stuck? Try one of the following:

• See the Troubleshooting page.

• Ask for help on Stack Overflow.

• You are strongly encouraged to file an issue about the problem, even if it’s just “I can’t get it to work on this cookiecutter” with a link to your cookiecutter. Don’t worry about naming/pinpointing the issue properly.

• Ask for help on Gitter if you must (but please try one of the other options first, so that others can benefit from the discussion)

Development on Cookiecutter is community-driven:

• Huge thanks to all the contributors who have pitched in to help make Cookiecutter an even better tool.

• Everyone is invited to contribute. Read the contributing instructions, then get started.

Connect with other Cookiecutter contributors and users on Gitter:

• https://gitter.im/audreyr/cookiecutter (note: due to work and commitments, a core committer might not always be available)

Encouragement is unbelievably motivating. If you want more work done on Cookiecutter, show support:

• Thank a core committer for their efforts.

• Star Cookiecutter on GitHub.

• Join the Cookiecutter Gittip community.

Got criticism or complaints?

• File an issue so that Cookiecutter can be improved. Be friendly and constructive about what could be better. Make detailed suggestions.

• Keep us in the loop so that we can help. For example, if you are discussing problems with Cookiecutter on a mailing list, file an issue where you link to the discussion thread and/or cc at least 1 core committer on the email.

• Be encouraging. A comment like “This function ought to be rewritten like this” is much more likely to result in action than a comment like “Eww, look how bad this function is.”

Waiting for a response to an issue/question?

• Be patient and persistent. All issues are on the core committer team’s radar and will be considered thoughtfully, but we have a lot of issues to work through. If urgent, it’s fine to ping a core committer in the issue with a reminder.

• Ask others to comment, discuss, review, etc.

• Search the Cookiecutter repo for issues related to yours.

• Need a fix/feature/release/help urgently, and can’t wait? @audreyr is available for hire for consultation or custom development.

Support This Project

This project is maintained by volunteers. Support their efforts by spreading the word about:

Code of Conduct

Everyone interacting in the Cookiecutter project’s codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct.

A Pantry Full of Cookiecutters

Here is a list of cookiecutters (aka Cookiecutter project templates) for you to use or fork.

Make your own, then submit a pull request adding yours to this list!

Similar projects

• Paste has a create option that creates a skeleton project.

• Diecutter: an API service that will give you back a configuration file from a template and variables.

• Django’s startproject and startapp commands can take in a –template option.

• python-packager: Creates Python packages from its own template, with configurable options.

• Yeoman has a Rails-inspired generator system that provides scaffolding for apps.

• Pyramid’s pcreate command for creating Pyramid projects from scaffold templates.

• mr.bob is a filesystem template renderer, meant to deprecate tools such as paster and templer.

• grunt-init used to be built into Grunt and is now a standalone scaffolding tool to automate project creation.

• scaffolt consumes JSON generators with Handlebars support.

• init-skeleton clones or copies a repository, executes npm install and bower install and removes the .git directory.

• Cog python-based code generation toolkit developed by Ned Batchelder

• Skaffold python and json config based django/MVC generator, with some add-ons and integrations.