README
¶
projectmpl
Project boilerplate engine
Table of content
Usage
Projectmpl supports various provider to download the templates. It supports
git, downloading an archive (.zip/.tar.gz/.tar.xz/...) from internet,
or using a local directory.
Keeping the template
When downloading or cloning a template, projectmpl will create a temporary
directory and delete it once the operation completes. If you want to keep
the template (to play with it, or simply to keep a copy), make sure you pass
the --template.keep option. This option pairs well with --template.output
which defines where the template should be downloaded/cloned.
Template Creation
The root .projectmpl.yml file
To configure your template, place a .projectmpl.yml at the root of your template.
This is called the root configuration, and should contain some information about
your template such as its name, its version and a description.
It can also contain overrides for delimiters in the templates (defaults being
the go-style {{ .var }}) and variables.
name: "Example Projectmpl"
version: "0.1.0"
description: "An example template to show how projectmpl works"
Variable declaration
You can add a variables section to your root configuration (or to any
.projectmpl.yml file, or directly inline in your template files, see below) to
define the variables you want your user to define. There are three types of
input you can use:
Simple Input
If you just specify the name of your variable, it will result in a simple input.
variables:
name:
Selection
variables:
license:
values: ["MIT", "Apache License 2.0", "BSD 3", "FreeBSD", "GPL", "LGPL", "WTFPL", "None"]
This will result in a selection input where the user can choose one of the provided choices.
Boolean/Confirmation
variables:
test:
confirm: true
If you're using the confirm keyword, it will generate a simple yes/no input.
The value you give that confirm key becomes the default value.
Other options and help
You can also help your users by changing the prompt, adding a help text or providing a default value:
variables:
license:
values: ["MIT", "Apache License 2.0", "BSD 3", "FreeBSD", "GPL", "LGPL", "WTFPL", "None"]
prompt: Which license do you want for your project?"
help: "License file that will be added to your project"
default: "MIT"
name:
default: amazingproject
prompt: "What's the name of your project?"
help: "Used to render the README file and various configuration files"
Validation
You can mark any variable as required using the required keyword:
variables:
name:
default: amazingproject
prompt: "What's the name of your project?"
help: "Used to render the README file and various configuration files"
required: true
This will prevent the user from rendering your template with missing variables. Note that if you specified a default value for an input, it becomes impossible to not fill in that value. So the validator becomes obsolete.
Standard .projectmpl.yml files
If you place a .projectmpl.yml file in a sub-directory of your template, this
file will apply recursively to all the elements inside that directory and its
own sub-directories, meaning that you can override some variables, add new ones,
modify the delimiters, or completely ignore an entire directory.
For example you can completely ignore a director:
└──── change
├── override.go
└── .projectmpl.yml
copy: true
In this case, the file override.go won't be rendered (but will simply be
copied to the output directory). This would apply for every sub-directory,
except if a directory contains a .projectmpl.yml telling otherwise, or a
file with an inline configuration. The ignore option can also be used to
completely ignore a file or a directory.
ignore: true
Per-file configuration
You can also configure individual files by adding a front matter at the top of the file (that will obviously be removed when rendered).
Let's say I have a file that I don't want to render but simply copy to the output directory:
---
copy: true
---
# This shouldn't be rendered at all !
You can even add per-file variables, or modify the delimiters. In fact, it's
like an inline .projectmpl.yml that applies to a single file.
Conditional Rendering/Copy
You may want some files to not be copied or rendered according to what the user
answers to your prompt. You can use the if key (in a .projectmpl.yml
or inline in a file), with the name of one of your variables. For example if
you have a variable defined like this in your root config:
variables:
drone:
prompt: "Do you want to add a Drone config file?"
confirm: true
You can then add this at the top of the file:
---
if: drone
---
workspace:
base: /go
...
This file will be rendered if, and only if, the user answered yes to that
question. Note that if and copy can work together if you just want
to copy the file and not render it.
After render commands
You can define some actions to be run once your template has been rendered. You can only define those in the root configuration (not in sub-directory configuration files). These actions can be configured to be run only when a variable has been entered, just like the conditional rendering. Here is an example of initializing the git repository when the template has been rendered:
after:
- cmd: "git init"
echo: "Intialized git repo"
if: git
- cmd: "git config core.hooksPath .githooks"
echo: "Configured git hooks"
if: git
variables:
git:
confirm: true
prompt: "Initialize git repo and git hooks ?"
If the user answers yes to the question about git, then the repo will be
initialized. You can also specify that you want the output of the command to be
displayed to the user using the output: true. echo is used to display a nice
message (instead of the command output).
Note: Due to the potential misbehavior of template creators, the user needs
to pass the -c or --commands to execute those commands. Otherwise the
commands will be completely ignored.
Documentation
¶
There is no documentation for this package.
Source Files
Directories