How to migrate Activator template to Giter8 template

By @eed3si9n March 17, 2017

sbt new command is supported in sbt 0.13.13 and above, which integrates with open source Giter8 out of the box.
It is our recommendation to migrate any active Activator templates to a Giter8 template.

The details of template creation can be found in Making your own templates page. Please read it for the detail related to Giter8. The following outlines a typical migration from an Activator template to a Giter8 one.

step 1. move current files to a temporary directory

Suppose you’re porting activator-hello-akka template. First git clone the template to your machine.
Then create a temporary directory under /tmp (or somewhere else you like).

$ git clone
Cloning into 'activator-hello-akka'...
$ mkdir /tmp/hello-akka

Next move everything into the temp directory.

$ mv activator-hello-akka/* /tmp/hello-akka
$ ls /tmp/hello-akka
COPYING               LICENSE       build.sbt             project/              src/                  tutorial/

step 2. sbt new foundweekends/giter8.g8 –name=activator-abc

Next run sbt new to start a Giter8 template in the same directory.
This is so we can maintain the Git history.

$ sbt new foundweekends/giter8.g8 --name=activator-hello-akka

Template applied in ./activator-hello-akka

step 3. Place content files under src/main/g8

Next, move back the template content files into src/main/g8 directory.

$ rsync -a /tmp/hello-akka/ ./activator-hello-akka/src/main/g8/

You can manually copy each files over too.

step 4. License the template under CC0

We recommend licensing software templates under CC0 1.0, which waives all copyrights and related rights, similar to the “public domain.” If you followed step 1, CC0 should be mentioned in README.markdown.

For activator-hello-akka, it’s already licensed to CC0, so we just need to move LICENSE and COPYING file to the root directory.

$ cd activator-hello-akka
$ git mv src/main/g8/LICENSE ./
$ git mv src/main/g8/COPYING ./

step 5. Place tutorial on

Migrate any tutorial contents to

For activator-hello-akka, let’s just move the tutorial/ directory back to root:

$ git mv src/main/g8/tutorial ./

step 6. Port metadata

First move back to root:

$ git mv src/main/g8/ ./

Next copy name and description from the file to src/main/g8/

name = hello-akka
description = Akka is a toolkit and runtime for building highly concurrent, ....

step 7. Test the template

To test the template run:

$ sbt
> test

If Giter8 plugin is correctly configured, it should create your template on a temporary directory and run test inside it.

> test
[info] Updating {file:/templates/activator-hello-akka/}root...
[info] Resolving org.scala-sbt#sbt-launch;0.13.13 ...
[info] Done updating.
Falling back to file copy for /templates/activator-hello-akka/src/main/g8/src/main/scala/HelloAkkaScala.scala: File: /templates/activator-hello-akka/src/main/g8/src/main/scala/HelloAkkaScala.scala, 12:52: '"
    case Greet           => sender ! Greeting(greeting) // Send the current greeting back to the sender

object HelloAkkaScala extends App {

  // Create the 'helloakka' actor system
  val system = ActorSystem("' came as a complete surprise to me
Running activator-hello-akka / scripted
[success] Total time: 107 s, completed Mar 21, 2017 8:41:46 PM

step 9. Escape any use of $ in the source

Giter8 uses $ as for varible substitution.
If you have $ in your template content under src/main/g8, then you need to escape it by replacing it with \$.

Alernatively, you can tell it to skip the variable substitution for some files using verbatim property:

name = hello-akka
description = Akka is a toolkit and runtime for building highly concurrent, distributed, and fault tolerant event-driven apps.  This simple application will get you started building Actor based systems in Java and Scala.  This app uses Akka, Java, Scala, JUnit, and ScalaTest.
verbatim = *.scala *.java

step 10. Append “.g8” to the GitHub repository name

For example if your current repository is named akka/activator-hello-akka, rename to akka/hello-akka.g8.

$ git remote set-url origin

That’s it!

extra credit

You can migrate the tutorial to Paradox document, which is a GitHub friendly documentation tool.