portable github hosted project templates less assembly required
Porteurbars is a fast and simple command line interface for templatizing your development workflow. Templatize away your boilerplate and share your templates on github. Focus on your idea, not your idea's setup.
Porteurbars templates follow two simple conventions.
1) Porteurbars follows the 12-factor philosophy for how to configure your templates.
Porteurbars assumes a file at the root of a directory called default.env, containing
key value pairs that represent your templates environment variables. When applying a template,
this file will be read and the user will be prompted for each key that isn't defined in their
current environment. This works well on most systems and allows for promptless template execution
as you can specify and environment before running the program
bash
FOO=bar BAR=baz porteurbars user/repo target
2) Porteurbars assumes a directory exists called template in your template's
root directory, next to your default.env file. This directory will contain arbitrary
handlebars template files representing the your templatized project. Porteurbars will walk
through this directory evaluating templates and copying results to your target directory.
If Porteurbars detects the presence of a local file will differences for a given file, you will be
prompted for whether or not you wish to keep those local changes.
Just upload your templates to github. That's it.
Porteurbars defines a convention for writing templates with only two rules
1) create file at the root of a directory called default.env which stores
line-oriented key value pairs
bash
$ touch default.env
echo "FOO=bar" > default.env
2) create a directory called template under which you define a set of handlebars templates
Porteurbars supports the notion of rendering templates from file content as well as file paths so you can also templatize the location of your template files.
bash
$ mkdir template
echo "Hello {{FOO}}" > template/hello
Publishing a Porteurbars template is has simple has storing this work in a git repo. To share these templates with others you can simply push this repo to github.
Install the porteurbars binary and ensure it's on your execution path.
porteurbars requires one and optionally a second argument.
The first argument is a reference to a template. The simplest case is using a github user/repo. By default porteurbars will render this template in the current working directory
bash
$ porteurbars user/repo
If this is undesirable, you can provide a path to render into
bash
$ porteurbars user/repo target_path
porteurbars will clone this template repo and read the defined template variables from the default.env file. If any of these variables are not defined in your env, porteurbars will prompt you for a value falling back on a default if you do not provide one.
Finally porteurbars will apply that data to the handlebars templates and write all files to the target path.
This project is heavily influenced by giter8. porteurbars aims to solve some of the issues I've experienced with it. giter8 is a jvm-based cli. To install it you need to install another tool called conscript and before that you need to install a jvm. porteurbars comes with a single standalone static binary. giter8 uses a templating language many are not familiar with but can get acclimated to. porteurbars uses handlebars templates in order to be familiar to a larger audience. giter8 templates are just git repositories. porteurbars templates are as well.
Yeomon is a similar tool that is more focused providing a scaffold for templates authors to wrote node.js modules that serve as generators. porteurbars focuses on having template authors just create handlebars templates. Yeomon requires you to install the node runtime and also setup and account on npm to share your work. porteurbars only requires git repositories. For convenience to facilitate sharing it provides convenience for referencing github user repositories. Yeomon's focus and/or marketing targets front end web development. porteurbars generalizes the problem of templating any workflow.
Doug Tangren (softprops) 2016