.\" Automatically generated by Pandoc 2.5
.\"
.TH "cookiecutter" "1" "" "cookiedough/cookiecutter" "Version 1.7"
.hy
.SH NAME
.PP
\f[B]cookiecutter\f[R] \[em] expands project templates
.SH SYNOPSIS
.PP
\f[B]cookiecutter\f[R] [\f[I]http://git\-repo/\f[R]]
.PP
\f[B]cookiecutter\f[R] [OPTIONS] \f[I]TEMPLATE\f[R] [EXTRA_CONTEXT\&...]
.SH DESCRIPTION
.PP
A command\-line utility that creates projects from cookiecutters
(project templates), e.g.\ creating a Python package project from a
Python package project template.
.SH OPTIONS
.PP
The \f[I]TEMPLATE\f[R] parameter can either be a remote repository
\f[I]http://git.example.com/co.git\f[R] (only Git/Mercurial supported),
a local checkout \f[I]./local\-template/\f[R], the name of any
\f[I]previously\-ran\-template\f[R], and a local or remote zip file
\f[I]http://fsl.example.com/repo.zip\f[R] even.
.TP
.B \-V, \-\-version
Show the version and exit.
.TP
.B \-\-no\-input
Do not prompt for parameters and only use cookiecutter.json file content
.TP
.B \-c, \-\-checkout \f[I]TRUNK\f[R]
branch, tag or commit to checkout after git clone
.TP
.B \-\-directory \f[I]DIR\f[R]
Directory within repo that holds cookiecutter.json file for advanced
repositories with multi templates in it
.TP
.B \-v, \-\-verbose
Print debug information
.TP
.B \-\-replay
Do not prompt for parameters and only use information entered previously
.TP
.B \-f, \-\-overwrite\-if\-exists
Overwrite the contents of the output directory if it already exists
.TP
.B \-s, \-\-skip\-if\-file\-exists
Skip the files in the corresponding directories if they already exist
.TP
.B \-o, \-\-output\-dir \f[I]PATH\f[R]
Where to output the generated project dir into
.TP
.B \-\-config\-file \f[I]FN\f[R]
User configuration file
.TP
.B \-\-default\-config
Do not load a config file.
Use the defaults instead
.TP
.B \-\-debug\-file \f[I]LOG\f[R]
File to be used as a stream for DEBUG logging
.SH USAGE
.SS Grab a Cookiecutter template
.PP
First, clone a Cookiecutter project template::
.IP
.nf
\f[C]
$ git clone git\[at]github.com:audreyr/cookiecutter\-pypackage.git
\f[R]
.fi
.SS Make your changes
.PP
Modify the variables defined in \f[C]cookiecutter.json\f[R].
.PP
Open up the skeleton project.
If you need to change it around a bit, do so.
.PP
You probably also want to create a repo, name it differently, and push
it as your own new Cookiecutter project template, for handy future use.
.SS Generate your project
.PP
Then generate your project from the project template::
.IP
.nf
\f[C]
$ cookiecutter cookiecutter\-pypackage/
\f[R]
.fi
.PP
The only argument is the input directory.
(The output directory is generated by rendering that, and it can\[cq]t
be the same as the input directory.)
.PP
\&..
note:: see :ref:\f[C]command_line_options\f[R] for extra command line
arguments
.PP
Try it out!
.SS Works directly with git and hg (mercurial) repos too
.PP
To create a project from the cookiecutter\-pypackage.git repo template::
.IP
.nf
\f[C]
$ cookiecutter gh:audreyr/cookiecutter\-pypackage
\f[R]
.fi
.PP
Cookiecutter knows abbreviations for Github (\f[C]gh\f[R]), Bitbucket
(\f[C]bb\f[R]), and GitLab (\f[C]gl\f[R]) projects, but you can also
give it the full URL to any repository::
.IP
.nf
\f[C]
$ cookiecutter https://github.com/audreyr/cookiecutter\-pypackage.git
$ cookiecutter git+ssh://git\[at]github.com/audreyr/cookiecutter\-pypackage.git
$ cookiecutter hg+ssh://hg\[at]bitbucket.org/audreyr/cookiecutter\-pypackage
\f[R]
.fi
.PP
You will be prompted to enter a bunch of project config values.
(These are defined in the project\[cq]s \f[C]cookiecutter.json\f[R].)
.PP
Then, Cookiecutter will generate a project from the template, using the
values that you entered.
It will be placed in your current directory.
.PP
And if you want to specify a branch you can do that with::
.IP
.nf
\f[C]
$ cookiecutter https://github.com/audreyr/cookiecutter\-pypackage.git \-\-checkout develop
\f[R]
.fi
.SS Works with private repos
.PP
If you want to work with repos that are not hosted in github or
bitbucket you can indicate explicitly the type of repo that you want to
use prepending \f[C]hg+\f[R] or \f[C]git+\f[R] to repo url::
.IP
.nf
\f[C]
$ cookiecutter hg+https://example.com/repo
\f[R]
.fi
.PP
In addition, one can provide a path to the cookiecutter stored on a
local server::
.IP
.nf
\f[C]
$ cookiecutter file://server/folder/project.git
\f[R]
.fi
.SS Works with Zip files
.PP
You can also distribute cookiecutter templates as Zip files.
To use a Zip file template, point cookiecutter at a Zip file on your
local machine::
.IP
.nf
\f[C]
$ cookiecutter /path/to/template.zip
\f[R]
.fi
.PP
Or, if the Zip file is online::
.IP
.nf
\f[C]
$ cookiecutter https://example.com/path/to/template.zip
\f[R]
.fi
.PP
If the template has already been downloaded, or a template with the same
name has already been downloaded, you will be prompted to delete the
existing template before proceeding.
.PP
The Zip file contents should be the same as a git/hg repository for a
template \- that is, the zipfile should unpack into a top level
directory that contains the name of the template.
The name of the zipfile doesn\[cq]t have to match the name of the
template \- for example, you can label a zipfile with a version number,
but omit the version number from the directory inside the Zip file.
.PP
If you want to see an example Zipfile, find any Cookiecutter repository
on Github and download that repository as a zip file \- Github
repository downloads are in a valid format for Cookiecutter.
.PP
Password\-protected Zip files
\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
.PP
If your repository Zip file is password protected, Cookiecutter will
prompt you for that password whenever the template is used.
.PP
Alternatively, if you want to use a password\-protected Zip file in an
automated environment, you can export the
\f[C]COOKIECUTTER_REPO_PASSWORD\f[R] environment variable; the value of
that environment variable will be used whenever a password is required.
.SS Keeping your cookiecutters organized
.PP
As of the Cookiecutter 0.7.0 release:
.IP \[bu] 2
Whenever you generate a project with a cookiecutter, the resulting
project is output to your current directory.
.IP \[bu] 2
Your cloned cookiecutters are stored by default in your
\f[C]\[ti]/.cookiecutters/\f[R] directory (or Windows equivalent).
The location is configurable: see :doc:\f[C]advanced/user_config\f[R]
for details.
.PP
Pre\-0.7.0, this is how it worked:
.IP \[bu] 2
Whenever you generate a project with a cookiecutter, the resulting
project is output to your current directory.
.IP \[bu] 2
Cloned cookiecutters were not saved locally.
.SH DOCS
.IP \[bu] 2
Documentation: https://cookiecutter.readthedocs.io
.IP \[bu] 2
GitHub: https://github.com/cookiecutter/cookiecutter
.IP \[bu] 2
PyPI: https://pypi.python.org/pypi/cookiecutter
.SH FILES
.TP
.B \f[B]\[ti]/.cookiecutterrc\f[R]
config store
.TP
.B \f[B]\[ti]/.cookiecutters/\f[R]
cache dir
.PP
These default paths are not XDG\-compliant
(https://github.com/cookiecutter/cookiecutter/issues/104).
\f[B]cookiedough\f[R](1) always overrides those settings, but also
provides a patch to permanently fix the builtin defaults to
\f[B]~/.config/cookiecutter/config\f[R] and
\f[B]~/.cache/cookiecutters/\f[R] respectively.
.SH ENV
.TP
.B \f[B]COOKIECUTTER_CONFIG\f[R]
Location of YAML file to use in place of
\f[C]\[ti]/.cookiecutterrc\f[R].
Can also be specified per \f[I]\-\-config\-file\f[R] option.
.SH SEE ALSO
.PP
\f[B]cookiedough\f[R](1), \f[B]python3\f[R](1)
.SH AUTHORS
cookiecutter project (audreyfeldroy, freakboy3742, stevepiercy,
terryjbates, pokoli, saxix, hackebrot, pfmoore, macrotim, kmike,
foobacca, luzfcb, ivanovmg), (c) BSDL\-3.