Giter8 is a command line tool to generate files and directories from templates published on github. It's implemented in Scala and runs through the Simple Build Tool launcher, but it can produce output for any purpose.
You can install giter8 and other Scala command line tools with
Conscript. This will setup Conscript in ~/bin/cs:
curl https://raw.github.com/n8han/conscript/master/setup.sh | sh
(See Conscript's readme for a non-unixy option.) Once cs is
on your path, you can install (or upgrade) giter8 with this command:
cs n8han/giter8
To make sure everything is working, try running g8 with no
parameters. This should download giter8 and its dependencies, then print
a usage message.
When it's time to upgrade to a new version of giter8, just run the
same cs command again.
Giter8 is also installable with the OS X package manager Homebrew:
$ brew update && brew install giter8
Template repositories must reside on github and be named with the
suffix .g8. We're keeping a list of templates on the wiki,
and you can query github to list all templates with a .g8 suffix
from the command line:
$ g8 --list
To apply a template, for example, softprops/unfiltered.g8:
$ g8 softprops/unfiltered.g8
The .g8 suffix is assumed:
$ g8 softprops/unfiltered
Either way, giter8 resolves this to the softprops/unfiltered.g8
repository and queries github for the project's template
parameters. You'll be prompted for each parameter, with its default
value in square brackets:
name [My Web Project]:
Enter your own value or press enter to accept the default. After all values have been supplied, giter8 fetches the templates, applies the parameters, and writes them to your filesystem.
If the template has a name parameter, it will be used to create base
directory in the current directory (typical for a new project).
Otherwise, giter8 will output its files and directories into
the current directory, skipping over any files that already exist.
Once you become familiar with a template's parameters, you can enter them on the command line and skip the interaction:
$ g8 softprops/unfiltered.g8 --name=my-new-website
Any unsupplied parameters are assigned their default values.
Giter8 accesses GitHub anonymously by default, but for private
templates you can supply a name and token or password in ~/.gh:
username=yourusername
token=yourtoken
The g8 runtime looks for templates in the src/main/g8 directory of a
given github project. This structure is used so that it is easy (but
not required) 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 n8han/giter8
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.
Every other file in that directory and below it is a template source.
StringTemplate, wrapped by Scalasti, is the engine
for 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 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.
Giter8 supplies an sbt plugin for testing templates before pushing
them to a github branch. If you used the n8han/giter8.g8 template
recommended above, it should already be configured. If you need to
upgrade an existing template project to the current plugin, it's
loaded in project/plugins/build.sbt:
addSbtPlugin("net.databinder" %% "giter8-plugin" % "0.3.0")
And settings must be applied in a build.sbt file in the project base:
seq(giter8Settings :_*)
When you enter sbt's interactive mode in the base directory of a
template project that is configured to use this plugn, the action
g8-test will apply the template in the default output directory
(under target/sbt-test) and run the scripted test for that project
in a forked process. You can supply the test scripted as
src/test/g8/test, otherwise >test is used. This is a good sanity
check for templates that are supposed to produce sbt projects.
But what if your template is not for an sbt project?
src/main/g8/default.properties
src/main/g8/TodaysMenu.html
You can still use sbt's interactive mode to test the template. The
lower level g8 action will apply default field values
to the template and write it to the same target/g8 directory.
As soon as you push your template to github (remember to name the
project with a .g8 extension) you can test it with the actual g8
runtime. When you're ready, add your template project to the
the wiki so other giter8 users can find it.
Nope. Lifty is an sbt processor, meaning it runs inside of sbt itself. You can't run sbt or any processor until you have a project to run it in. Giter8 addresses step 1 of sbt project creation. You could use giter8 create a Lift project, then run Lifty inside it for fine tuning. You can also use giter8 to produce things that are not sbt projects at all.