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/>.
The g8 runtime looks for templates in two locations in a given GitHub project:
src/main/g8 directory is present it uses src/main/g8 (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 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"
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$
*/
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
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
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.
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 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)
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.