# ffizer
[![Crates.io](https://img.shields.io/crates/l/ffizer.svg)](http://creativecommons.org/publicdomain/zero/1.0/)
[![Crates.io](https://img.shields.io/crates/v/ffizer.svg)](https://crates.io/crates/ffizer)
[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
[![Build Status](https://travis-ci.com/ffizer/ffizer.svg?branch=master)](https://travis-ci.com/ffizer/ffizer)
[![Build Status](https://dev.azure.com/ffizer/ffizer/_apis/build/status/ffizer.ffizer)](https://dev.azure.com/ffizer/ffizer/_build/latest?definitionId=1)
[![codecov](https://codecov.io/gh/ffizer/ffizer/branch/master/graph/badge.svg)](https://codecov.io/gh/ffizer/ffizer)
[![Crates.io](https://img.shields.io/crates/d/ffizer.svg)](https://crates.io/crates/ffizer)
![GitHub All Releases](https://img.shields.io/github/downloads/ffizer/ffizer/total.svg)
ffizer is a files and folders initializer / generator. Create any kind (or part) of project from template.
keywords: file generator, project template, project scaffolding, quickstart, project initializer, project skeleton
- [ffizer](#ffizer)
- [Motivations](#motivations)
- [Main features](#main-features)
- [Sub features](#sub-features)
- [Limitations](#limitations)
- [Usages](#usages)
- [Install](#install)
- [via homebrew](#via-homebrew)
- [via github releases](#via-github-releases)
- [via cargo](#via-cargo)
- [Run](#run)
- [Self upgrade the executable](#self-upgrade-the-executable)
- [Apply a template](#apply-a-template)
- [Authoring a template](#authoring-a-template)
- [Templates](#templates)
- [Build](#build)
- [Alternatives](#alternatives)
- [Generic](#generic)
- [Specialized](#specialized)
<a id="markdown-motivations" name="motivations"></a>
## Motivations
<a id="markdown-main-features" name="main-features"></a>
### Main features
- [X] project generator as a standalone executable (no shared/system dependencies (so no python + pip + ...))
- [X] a simple and generic project template (no specialisation to one ecosystem)
- [X] template as simple as possible, like a
- [X] copy or clone with file/folder renames without overwrite
- [X] few search and replace into file
- [X] template hosted as a local folder on the file system
- [X] template hosted as a git repository on any host (not only public github)
- [X] at root of the repository
- [X] in subfolder of the repository
- [X] in any revision (branch, tag, commit)
- [X] template composed of other template
- [X] composite template are regular standalone template
- [X] composite template can be apply at root folder
- [X] a fast enough project generator
<a id="markdown-sub-features" name="sub-features"></a>
### Sub features
- [X] dry mode (usefull to test)
- [ ] chain commands (eg: 'git init') (like a post-hook)
- [ ] raw command
- [ ] composite template include under conditions
- [X] file / folder ignored under conditions (ignores'item in ffizer.yaml are defined as handlerbar expression)
- [X] handlebars helpers
- [X] transform strings (toUpperCase, toLowerCase, Capitelize,...)
- [X] render content of GET url
- [X] render content from https://gitignore.io
- [ ] suggestions welcomes ;-)
- [ ] ability to update / diff / overwrite existing file
<a id="markdown-limitations" name="limitations"></a>
## Limitations
Some of the following limitations could change in the future (depends on gain/loss):
- no conditionals file or folder creation
- no framework X dedicated features
- no plugin and not extensible (without change the code)
- handlebars is the only template language supported (support for other is welcome)
<a id="markdown-usages" name="usages"></a>
## Usages
<a id="markdown-install" name="install"></a>
### Install
```sh
<a id="markdown-via-homebrew" name="via-homebrew"></a>
#### via homebrew
```sh
brew tap ffizer/ffizer
brew install ffizer-bin
ffizer upgrade
```
<a id="markdown-via-github-releases" name="via-github-releases"></a>
#### via github releases
Download the binary for your platform from [github releases](https://github.com/ffizer/ffizer/releases), then unarchive it and place it your PATH.
<a id="markdown-via-cargo" name="via-cargo"></a>
#### via cargo
```sh
cargo install ffizer
```
<a id="markdown-run" name="run"></a>
### Run
```txt
➜ ffizer --help
ffizer 0.10.0
https://github.com/ffizer/ffizer
ffizer is a files and folders initializer / generator. Create any kind (or part) of project from template.
USAGE:
ffizer [FLAGS] <SUBCOMMAND>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
-v, --verbose Verbose mode (-v, -vv (very verbose / level debug), -vvv) print on stderr
SUBCOMMANDS:
apply Apply a template into a target directory
help Prints this message or the help of the given subcommand(s)
upgrade Self upgrade ffizer executable
```
<a id="markdown-self-upgrade-the-executable" name="self-upgrade-the-executable"></a>
#### Self upgrade the executable
```sh
➜ ffizer upgrade --help
ffizer-upgrade 0.10.0
https://github.com/ffizer/ffizer
Self upgrade ffizer executable
USAGE:
ffizer upgrade
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
```
<a id="markdown-apply-a-template" name="apply-a-template"></a>
#### Apply a template
```sh
➜ ffizer apply --help
ffizer-apply 0.10.0
https://github.com/ffizer/ffizer
Apply a template into a target directory
USAGE:
ffizer apply [FLAGS] [OPTIONS] --destination <dst_folder> --source <uri>
FLAGS:
-h, --help Prints help information
--offline in offline, only local templates or cached templates are used
-V, --version Prints version information
--x-always_default_value should not ask for valiables values, always use defautl value or empty
(experimental)
OPTIONS:
--confirm <confirm> ask confirmation 'never' or 'always' [default: never]
-d, --destination <dst_folder> destination folder (created if doesn't exist)
--rev <rev> git revision of the template [default: master]
--source-subfolder <subfolder> path of the folder under the source uri to use for template
-s, --source <uri> uri / path of the template
```
- use a local folder as template
```sh
ffizer apply --source $HOME/my_templates/tmpl0 --destination my_project
```
- use a remote git repository as template
```sh
ffizer apply --source https://github.com/ffizer/template_sample.git --destination my_project
```
output
```sh
Configure variables
project_name: my_project
Plan to execute
- mkdir "my_project/"
- mkdir "my_project/dir_1"
- copyraw "my_project/dir_1/file_1_1.txt"
- mkdir "my_project/dir_2_my_project"
- copyraw "my_project/dir_2_my_project/file_1_2.txt"
- copyraw "my_project/file_1.txt"
- copyrender "my_project/file_2.txt"
- keep "my_project/file_2.txt"
- copyrender "my_project/file_3.txt"
- copyraw "my_project/file_4_my_project.txt"
- copyrender "my_project/file_5_my_project.txt"
- copyraw "my_project/file_6.hbs"
```
<a id="markdown-authoring-a-template" name="authoring-a-template"></a>
### Authoring a template
see [Template Authoring - ffizer](https://ffizer.github.io/ffizer/book/template_authoring.html) *WIP*
<a id="markdown-templates" name="templates"></a>
## Templates
- [ffizer/templates_default: the default collections of templates for ffizer](https://github.com/ffizer/templates_default) (WIP)
- [davidB31 / cg-starter-multi-rust · GitLab](https://gitlab.com/davidB31/cg-starter-multi-rust) Project template for Multi-Bot in Rust on CodinGame.
- samples (used for test, demo)
templates_default)
- [test_1](tests/test_1/template)
- [test_2](tests/test_2/template) (demo of usage of gitignore.io)
- [ffizer/template_sample: a simple template for ffizer used for demo and test](https://github.com/ffizer/template_sample)
<a id="markdown-build" name="build"></a>
## Build
```sh
cargo install cargo-make --force
cargo make ci-flow
```
<a id="markdown-alternatives" name="alternatives"></a>
## Alternatives
<a id="markdown-generic" name="generic"></a>
### Generic
- [Cookiecutter](https://cookiecutter.readthedocs.io/), lot of templates, require python + pip + install dependencies on system (automatic)
- [Cookiecutter — Similar projects](https://cookiecutter.readthedocs.io/en/latest/readme.html#similar-projects)
- [sethyuan/fgen](https://github.com/sethyuan/fgen): A file generator library to be used to generate project structures, file templates and/or snippets. Templates are based on mustache. require nodejs
- [project_init](https://crates.io/crates/project_init) in rust, use mustache for templating but I have some issues with it (project template creation not obvious, github only) I could contributes but I have incompatible requirements.
- [skeleton](https://crates.io/crates/skeleton), good idea but no template file, more like a script.
- [porteurbars](https://crates.io/crates/porteurbars), very similar but I discovered it too late.
<a id="markdown-specialized" name="specialized"></a>
### Specialized
specialized to a platform, build tool,...
- [The web's scaffolding tool for modern webapps | Yeoman](http://yeoman.io/), nodejs ecosystem
- [JHipster - Generate your Spring Boot + Angular/React applications!](https://www.jhipster.tech/) require java, dedicated to java web ecosystem, optionnated template (not generic)
- [Giter8](http://www.foundweekends.org/giter8/) require java + [Conscript](http://www.foundweekends.org/conscript/index.html)
- [Typesafe activator](https://developer.lightbend.com/start/), require java, target scala ecosystem
- [Maven – Archetypes](https://maven.apache.org/guides/introduction/introduction-to-archetypes.html) require java + maven, target maven ecosystem
- [cargo-generate](https://github.com/ashleygwilliams/cargo-generate), limited capabilities, target rust/cargo ecosystem