Project templates in rust
Latest commit 635f3ab Sep 26, 2018
Failed to load latest commit information.
.cargo config? Jun 5, 2018
ci ci Dec 19, 2017
man lockfile Aug 22, 2018
src diffs Sep 26, 2018
.gitattributes gitattributes Jan 13, 2018
.gitignore manpages Jan 13, 2018
.gitmodules re-add for travis ci May 7, 2017
.pi.toml more version control support Jun 15, 2017
.travis.yml ci again Jul 17, 2018 release May 4, 2017
Cargo.lock diffs Sep 26, 2018
Cargo.toml (cargo-release) version 3.1.18 Aug 22, 2018
Justfile diffs Sep 26, 2018
LICENSE release May 4, 2017 readme Jun 5, 2018 todo Jan 15, 2018
appveyor.yml crate name Jun 5, 2018 rustfmt Jan 18, 2018
rustfmt.toml formatted Jul 17, 2018

project init (pi)

Build Status Windows build status

pi is a command-line utility to initialize projects. It is written in rust.

It is intended to provide something like cookiecutter, but faster.

Reasons to use pi:

  • You want to automate the process of starting a new project, for all your projects.
  • You want project initialization that's quick

Reasons to use pi over cookiecutter:

  • Templates are smaller. Define files you need in a .toml.
  • Fast. pi is 30x faster than cookiecutter when rendering the sample vim plugin template.
  • pi uses mustache, a logic-less language, for templates.
  • pi can initialize a darcs, pijul, mercurial, or git repository inside your projects
  • pi provides opinionated templates for many languages
  • pi is extensible in Rust

Reasons to not use pi over cookiecutter:

  • cookiecutter uses jinja templates, which are far more sophisticated.
  • pi is newer and presumably more buggy
  • cookiecutter is extensible in Python

Benchmarks (with Haskell's bench):

Tool Language Time (vim example plugin) Time (rust library)
pi init rust 10.10 ms 8.809 ms
pi new rust 6.672 ms 8.653 ms
cookiecutter python 317.1 ms 316.9 ms



Enter the following in a command prompt:

curl -LSfs | sh -s -- --git vmchale/project-init

Binary releases

The easiest way for most users is simply to download the prebuilt binaries. You can find binaries for various platforms on the release page.


First, install cargo. Then:

 $ cargo install project_init

You will need to use the nightly release for this to work; if in doubt run

rustup run nightly cargo install project_init


pi reads from $HOME/.pi_templates/ and your current directory. So, if you place a template in the $HOME/.pi_templates/idris/, you can initialize a project anywhere with

 $ pi init idris treesod

There is a repo containing pi templates here.

You can also use pi with built-in templates, viz.

 $ pi new haskell really-good-project
Finished initializing project in really-good-project/

Or to fetch a template from github:

 $ pi git vmchale/haskell-ats ambitious-insane-project



Global configuration is via the $HOME/.pi.toml file. The following is an example:

license = "BSD3"         # set default license to BSD3 
version_control = "git"  # initialize new repositories with git
version = "0.1.0"        # start new projects at version 0.1.0

name = "Vanessa McHale"
email = ""
github_username = "vmchale"

# put any custom keys you want under a [[user]] table
website = ""

Project-specific config lives in $PROJECT_NAME/template.toml. The following is an example for a vim plugin:

license = "BSD3"        # overrides global value if set
with_readme = true      # add

files = ["syntax/{{ project }}.vim","plugin/{{ project }}.vim","doc/{{ project }}.txt"] # blank files
directories = ["doc","syntax","plugin"]
templates = ["vimball.txt"] # files to be processed

version = "0.1.0"
version_control = "darcs"

# put any custom keys you want below [[user]]
vim_org_username = "vmchale"

This will generate the following directory structure:

├── doc
│  └── vim-plugin.txt
├── plugin
│  └── vim-plugin.vim
├── syntax
│  └── vim-plugin.vim
└── vimball.txt

For a more in-depth example, see here. This is a template based off the recursion schemes generator.


pi uses mustache for templating, via the rustache crate.

You can find examples and help on the mustache page, or you can my look at the example repo.