Making your own templates 

Use CC0 1.0 for template licensing 

We recommend licensing software templates under CC0 1.0, which waives all copyrights and related rights, similar to the “public domain.”

If you reside in a country covered by the Berne Convention, such as the US, copyright will arise automatically without registration. Thus, people won’t have legal right to use your template if you do not declare the terms of license. The tricky thing is that even permissive licenses such as MIT License and Apache License will require attribution to your template in the template user’s software. To remove all claims to the templated snippets, distribute it under CC0, which is an international equivalent to public domain.

Template license
----------------
Written in <YEAR> by <AUTHOR NAME> <AUTHOR E-MAIL ADDRESS>
[other author/contributor lines as appropriate]

To the extent possible under law, the author(s) have dedicated all copyright and related
and neighboring rights to this template to the public domain worldwide.
This template is distributed without any warranty. See <https://creativecommons.org/publicdomain/zero/1.0/>.

template layout 

The g8 runtime looks for templates in two locations in a given GitHub project:

  • If the src/main/g8 directory is present it uses src/main/g8 (src layout)
  • If it does not exist, then the root directory is used (root layout)

src layout 

This src layout is recommended so that it is easy for the template itself to be an sbt project. That way, an sbt plugin can be employed to locally test templates before pushing changes to GitHub.

The easy way to start a new template project is with a Giter8 template made expressly for that purpose:

$ g8 foundweekends/giter8.g8

This will create an sbt project with stub template sources nested under src/main/g8. The file default.properties defines template fields and their default values using the Java properties file format.

default.properties 

default.properties file may be placed in project/ directory, or directly under the root of the template. Properties are simple keys and values that replace them.

StringTemplate is the engine that applies Giter8 templates, so template fields in source files are bracketed with the $ character. For example, a “classname” field might be referenced in the source as:

class $classname$ {

The template fields themselves can be utilized to define the defaults of other fields. For instance, you could build some URLs given the user’s GitHub id:

name = URL Builder
github_id=githubber
developer_url=https://github.com/$github_id$
project_url=https://github.com/$github_id$/$name;format="norm"$

This would yield the following in interactive mode:

name [URL Builder]: my-proj
github_id [githubber]: n8han
project_url [https://github.com/n8han/my-proj]:
developer_url [https://github.com/n8han]:

Dollar signs can be escaped to avoid resolution:

val foo = "foo"
val bar = "bar"
println(s"\$foo\$bar")

This would yield to:

val foo = "foo"
val bar = "bar"
println(s"$foo$bar")

Some variable names are prohibited since they’re tokens used by StringTemplate in its grammar, the complete list is here but the most common are:

"i", "i0", "if", "else", "elseif", "endif", "first", "length"
"strlen", "last", "rest", "reverse", "trunc", "strip", "trim"

Template comments 

Sometimes it’s useful to put a comment into a template that is intended for template maintainers, and should not be included in the generated output.

Wrapping comments between $! and !$ won’t make them appear in the output.

$! This comment won't appear in the output !$
// This comment will appear in the output
$!
This multiline comment won't appear either
No matter how
long it is

Internal $substitutions$ are ignored.

Even $invalid$ ones.

!$
/*
 * This comment is output and can contain $substitutions$
 */

Conditionals 

All fields have a property named truthy to be used in conditional expressions. "y", "yes", and "true" evaluate to true; anything else evaluates to false.

scala212 = yes
scala211 = no

These could be used in a template as follows:

$if(scala212.truthy)$
scalaVersion := "2.12.3"
$elseif(scala211.truthy)$
scalaVersion := "2.11.11"
$else$
scalaVersion := "2.10.6"
$endif$

These could also be used include/exclude files or directories:

src/main/g8
├── $name__normalize$
│   ├── $if(jvm.truthy)$jvm$endif$
│   │   └── src
│   │       └── main
│   │           └── scala
│   │               └── $organization__packaged$
│   │                   └── $name;format="Camel"$.scala

If you want to skip a directory from the path, but keep all nested directories and files, use . as the name of the directory. For example the next template:

src/main/g8
├── parent_folder
│   ├── $if(cond.truthy)$skip_folder$else$.$endif$
|   |   └── child_file

will be processed to

├── parent_folder
|   └── child_file

name field 

The name field, if defined, is treated specially by Giter8. It is assumed to be the name of a project being created, so the g8 runtime creates a directory based off that name (with spaces and capitals replaced) that will contain the template output. If no name field is specified in the template, g8’s output goes to the user’s current working directory. In both cases, directories nested under the template’s source directory are reproduced in its output. File and directory names also participate in template expansion, e.g.

src/main/g8/src/main/scala/$classname$.scala

package field 

The package field, if defined, is assumed to be the package name of the user’s source. A directory named $package$ expands out to package directory structure. For example, net.databinder becomes net/databinder.

verbatim field 

The verbatim field, if defined, is assumed to be the space delimited list of file patterns such as *.html *.js. Files matching verbatim pattern are excluded from string template processing.

Maven properties 

maven properties tell Giter8 to query the Central Maven Repository. Instead of supplying a particular version (and having to update the template with every release), specify a library and giter8 will set the value to the latest version according to Maven Central.

The property value format is maven(groupId, artifactId). Keep in mind that Scala projects are typically published with a Scala version identifier in the artifact id. So for the Unfiltered library, we could refer to the latest version as follows:

name = My Template Project
description = Creates a giter8 project template.
unfiltered_version = maven(ws.unfiltered, unfiltered_2.11)

To only use the latest stable release (excluding Milestone builds, Release candidates etc) specify a “stable” value in the property value format maven(groupId, artifactId, stable). To use the latest stable version for the Scalatest library we could refer to it as follows:

name = My Template Project
description = Creates a giter8 project template.
scalatest_version = maven(org.scalatest, scalatest_2.11, stable)

root layout 

There’s an experimental layout called root layout, which uses the root directory of the GitHub project as the root of template.

Since you can no longer include template fields in the files under project its application is very limited. It might be useful for templates that are not for sbt builds or templates without any fields.