jeremybower/tmpl

🚀 Command line tool that generates text from Go templates and YAML configuration files.

Tmpl

Tmpl is a command line tool that generates text from Go templates and YAML configuration files.

It is a standalone tool that can be used with Go, Node.js, Python, Ruby, PHP, Rust, C++, or any other language or framework you are using. This is especially helpful if you are writing multiple services in different languages and want a consistent approach when generating text files.

Table of Contents

• Features
• Installation
• Usage
• Template Functions
• Examples
  • Generating a Dockerfile
• Contributing

Features

• Supports any text-based format (Dockerfile, etc.)
• Available for Linux and macOS
• Lightweight and efficient
• Customizable with one or more config files
• Include multiple template files with glob filepaths

Installation

macOS

Install the binary directly on macOS for amd64:

$ sudo curl -fsSL -o /usr/local/bin/tmpl https://github.com/jeremybower/tmpl/releases/latest/download/tmpl-darwin-amd64
$ sudo chmod +x /usr/local/bin/tmpl

or arm64:

$ sudo curl -fsSL -o /usr/local/bin/tmpl https://github.com/jeremybower/tmpl/releases/latest/download/tmpl-darwin-arm64
$ sudo chmod +x /usr/local/bin/tmpl

Linux

Install the binary directly on Linux for amd64:

$ sudo curl -fsSL -o /usr/local/bin/tmpl https://github.com/jeremybower/tmpl/releases/latest/download/tmpl-linux-amd64
$ sudo chmod +x /usr/local/bin/tmpl

or arm64:

$ sudo curl -fsSL -o /usr/local/bin/tmpl https://github.com/jeremybower/tmpl/releases/latest/download/tmpl-linux-arm64
$ sudo chmod +x /usr/local/bin/tmpl

Docker

Docker images are published to GitHub Container Registry (ghcr.io/jeremybower/tmpl).

$ docker run --rm -it ghcr.io/jeremybower/tmpl --help

If you wish to generate files, you will need to use Docker's bind mount feature to make your local working directory (pwd) available inside the tmpl container:

$ docker run --rm -it --volume "$(pwd)/workspace:/workspace" --workdir "/workspace" ghcr.io/jeremybower/tmpl generate --config config.yml --config Dockerfile.yml --mount Dockerfile.tmpl:/Dockerfile.tmpl --mount includes:/includes --out Dockerfile /Dockerfile.tmpl

Usage

$ tmpl generate --help
NAME:
   tmpl generate - Generate text from template and configuration files

USAGE:
   tmpl generate [command options]

OPTIONS:
   --config value, -c value [ --config value, -c value ]  Apply configuration data to the templates
   --missingkey value                                     Controls the behavior during execution if a map is indexed with a key that is not present in the map (default: error)
   --mount value, -m value [ --mount value, -m value ]    Attach a filesystem mount to the template engine
   --out value, -o value                                  Write the generated text to file
   --help, -h                                             show help

Tmpl accepts multiple config files, a single destination file and mounts to access the file system at known paths. For example, generating a Dockerfile might require general configuration and specific configuration files, plus other templates:

tmpl generate -c config.yml -c Dockerfile.yml -m Dockerfile.tmpl:/Dockerfile -m includes:/includes -o Dockerfile /Dockerfile.tmpl

See Generating a Dockerfile for the complete example.

Template Functions

Tmpl includes all the functions provided by sprig and additional functions that support working with multiple templates and config files:

Function	Description
dirs	Lists all the directories that were mounted. The only parameter is a glob pattern to match against the directory names.
filename	Returns the filename of the current template.
files	Lists all the files that were mounted. The only parameter is a glob pattern to match against the file names.
include	Similar to the standard template function, but the first parameter accepts a pipeline to select templates dynamically. The second parameter is the data to pass to the named template.
includeText	Similar to include function, but passes the file's text through unchanged. The only parameter is a pipeline to select the files dynamically.

Examples

Generating a Dockerfile

The full example is available in examples/dockerfile:

.
├── Dockerfile <--- generate this file
├── Dockerfile.tmpl
├── Dockerfile.yml
├── Makefile
├── config.yml
└── includes
    ├── en.tmpl
    └── fr.tmpl

The Dockerfile can be generated with:

cd examples/dockerfile
make Dockerfile
make build
make clean

There are three parts to this example: config files, template files and the command to generate.

Step 1: Config Files

Setup a general configuration file to use the same defaults for all Dockerfiles in a project:

config.yml:

Config:
  LanguageCode: "en"
  BaseImage: "ubuntu:24.04"

Use a specific configuration file to change the generated output:

Dockerfile.yml:

Config:
  LanguageCode: "fr"

Tmpl will combine the configuration files in order where successive configuration files can overwrite earlier ones. Internally, templ will use this configuration:

Config:
  LanguageCode: "fr"
  BaseImage: "ubuntu:24.04"

Notice that LanguageCode was overwritten by the second configuration file.

Step 2: Templates

Create a main template for the Dockerfile:

Dockerfile.tmpl:

FROM {{ .BaseImage }}

{{ include (printf "includes/%s.tmpl" .LanguageCode) . }}

Create template files to include for each language:

includes/en.tmpl:

CMD ["echo", "Hello!"]

includes/fr.tmpl:

CMD ["echo", "Bonjour!"]

Step 3: Generate

To generate the Dockerfile, run:

$ make Dockerfile
Generated 1 file(s) in 6.961916ms
/tmpl/examples/dockerfile/Dockerfile

The resulting Dockerfile contains:

FROM ubuntu:24.04

CMD ["echo", "Bonjour!"]

Contributing

Tmpl is written in Go. Pull requests are welcome.