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 <http://creativecommons.org/publicdomain/zero/1.0/>.

template layout 

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

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, wrapped by Scalasti, 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]:

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)

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.