arturopala/make-it-g8

A tool to convert any project into a giter8 template

Tool to convert your project into a giter8 template

Demo

Watch make-it-g8 live demonstration on YouTube.

Motivation

Creating new giter8 template is easy, but maintaining it later not as much. You have to do all the tedious placeholder replacing job again, and again, both in the content of the files and in the file paths.

The make-it-g8 tool provides both convenient way to create new g8 template, and to update it later multiple times without effort.

What is g8 template?

The giter8 template is an ordinary project having nested src/main/g8 folder where files or paths may contain placeholders, e.g. $name$.

Place it on GitHub and call with the g8 command line tool or sbt new command to spring your own project.

Advantages of using make-it-g8

• quick template creation with proper escaping of $ characters
• easy template parametrisation with multiple placeholder values
• derives automatically common placeholder variants: camel, snake, hyphen, package, packaged, etc.
• generates script to generate an example project and run test on it
• generates script updating the template after changes were made to the example project (covers full create-change-validate-update cycle)
• generates README.md with the template usage guide and an example project filetree diagram

Prerequisites

• Java >= 8
• SBT >= 1.3.x https://www.scala-sbt.org/release/docs/Setup.html
• giter8 (g8) >= 0.11.0 http://www.foundweekends.org/giter8/setup.html
• coursier launcher https://get-coursier.io/docs/cli-installation

Usage

Consider installing the tool locally with coursier

cs install --contrib make-it-g8

Run the tool locally in an interactive mode

Run after installation using:

make-it-g8

or launch using coursier:

cs launch com.github.arturopala:make-it-g8_2.12:1.23.0 -- --interactive

or run using local clone of the repository:

wget https://raw.githubusercontent.com/arturopala/make-it-g8/master/make-it-g8.sh
chmod u+x make-it-g8.sh
./make-it-g8.sh --interactive

Run the tool locally in a scripted mode

Run after installation using:

make-it-g8 -- --no-interactive --source {PATH} [--target {PATH}] [--name {STRING}] [--package {STRING}] [--description {STRINGURLENCODED}] [-K key=patternUrlEncoded]

or launch using coursier:

cs launch com.github.arturopala:make-it-g8_2.12:1.23.0 -- --source {PATH} [--target {PATH}] [--name {STRING}] [--package {STRING}] [--description {STRINGURLENCODED}] [-K key=patternUrlEncoded]

or run using local clone of the repository:

wget https://raw.githubusercontent.com/arturopala/make-it-g8/master/make-it-g8.sh
chmod u+x make-it-g8.sh
./make-it-g8.sh --source {PATH} [--target {PATH}] [--name {STRING}] [--package {STRING}] [--description {STRINGURLENCODED}] [-K key=patternUrlEncoded]

Options:

-s, --source  <arg>                        Source code path, absolute or
                                            relative
-p, --package  <arg>                       Source code base package name

-c, --clear                                Clear target folder
    --noclear                              Do not clear whole target folder,
                                            only src/main/g8 subfolder
-x, --custom-readme-header-path  <path>    Custom README.md header path
-d, --description  <arg>                   Template description
-f, --force                                Force overwriting target folder
    --noforce
-i, --interactive                          Interactive mode
    --nointeractive
-Kplaceholder=text [placeholder=text]...   Text chunks to parametrize
-n, --name  <arg>                          Template name
-r, --readme                               Create readme
    --noreadme                             Do not create/update readme
-t, --target  <arg>                        Template target path, absolute or
                                            relative
-h, --help                                 Show help message
-v, --version                              Show version of this program

Use as a library

make-it-g8 is hosted in The Maven Central repository

libraryDependencies += "com.github.arturopala" %% "make-it-g8" % "1.23.0"      

Example template created with make-it-g8

• https://github.com/arturopala/cross-scala.g8
• https://github.com/hmrc/template-play-frontend-fsm.g8

Development

Test

sbt test

Run locally

sbt run

sbt "run --interactive"

sbt run -Dmakeitg8.interactive=true 

make-it-g8's Issues

package command line parameter is required

Looking at the help the command line option --package is actually an optional paramenter, but looking at the code, it is a required option.

Read global git ignore file to create a local .gitignore

make-it-g8 currently checks whether there is a .gitignore file in the source directory. That's great but some people use a global gitignore file for things like ignoring target, .bloop, .metals and so on. Currently, make-it-g8 seems to completely ignore this. I think it would be a good idea to also read that ignore file if present. The location of the global gitignore file can be configured: git config --global core.excludesFile.
As a workaround, one can cp $(git config --global core.excludesFile) path/to/repo/.gitignore before running make-it-g8. Maybe that would, indeed, be a good idea for make-it-g8. It is already checking whether a .gitignore is present. It might as well offer to create one using the contents of $(git config --global core.excludesFile) if present. What do you think?