Giter8 Documentation

Giter8 0.7.0 introduces an experimental root layout. By default, Giter8 looks for templates in src/main/g8. With the root layout enabled, if Giter8 cannot find that directory, it will use the root directory of the specified Git repository as the template directory.

Constraints and Behavior:

• The default.properties file can be placed in either the root directory or the project directory.
• Limitation: You cannot include template fields in files located under the project directory when using this layout. This makes the root layout primarily suitable for simple templates.

Giter8 supports performing template expansion within file and directory names. This allows you to use placeholders (e.g., $MainClass$) directly in your file paths within the template structure.

src/main/g8/src/main/scala/$MainClass$.scala

To define scaffolds within a GitHub project, place them in the src/main/scaffolds directory.

• Each subdirectory inside src/main/scaffolds represents a unique scaffold and is accessible in the sbt shell by its directory name.
• You can include a default.properties file in a scaffold directory to define default field values.
• The name field: If a name property is defined in the scaffold, the generated output will be placed in a directory named after that value, preserving the subdirectory layout of the source scaffold.

When using the truthy property in conditional expressions, the following evaluation rules apply:

• True: `

Giter8 supports conditional expressions using the .truthy property of fields. A field is considered truthy if its value is "y", "yes", or "true". Any other value is false.

Conditional Logic in Files

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

Conditional Files and Directories

You can use conditionals in file paths to include or exclude files/directories. To skip a directory in the path while keeping its children, use . as the name:

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

To include comments for template maintainers that should not appear in the generated files, wrap them in $! and !$. These comments ignore any internal $substitutions$ or invalid tags.

$! 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$

!$

The recommended way to install Giter8 and other Scala command line tools is via Coursier.

1. Install Coursier and ensure the cs binary is in your system PATH following the official installation instructions.
2. Run the following command to install Giter8:

cs install giter8

To update your existing Giter8 installation, use:

cs update g8

You can authenticate with GitHub using the g8 --auth command. This implementation uses GitHub's client-side OAuth support. When using the login password method, your actual password is not stored locally; instead, an OAuth access token is generated and stored in ~/.g8/config for future use.

g8 --auth login password