tmpl/DOCS.md

4.5 KiB

tmpl templates

This documentation aims to cover FAQs and setup.

Setting up a template

A "valid" tmpl template only requires two things

  1. A template.toml file in the root directory.
  2. A template directory that serves as the "root" of the template.

template.toml

NOTE: The template.toml file will be expanded, though not with the full power of the template itself.
The template.toml file will only expand environment variables with syntax $USER or ${USER}.
For full documentation on the syntax, see os.ExpandEnv.

When using the --defaults flag, no prompts will be shown and only default values will be used.
As another alternative, any environment variable that matches a key will bypass the prompt.
For example, author would have the corresponding environment variable TMPL_VAR_AUTHOR.

# Key-value pairs can be simple
# The user will receive a basic prompt asking them to fill out the variable
project = "my-project"

# Extended properties MUST be added after any simple key-value pairs (due to how TOML works)

# The "key" is enclosed in braces
[author]
# prompt is what will be shown to prompt the user
prompt = "The name of the author of this project"
# help would be extra information (generally seen by giving '?' to a prompt)
help = "Who will be primarily writing this project"
# default is the "value" part of the simple pair. This could be a suggested value
default = "$USER"

template directory

This directory contains any and all files that are part of the template.

Everything in this directory (including paths and file names!) will be executed as a Go template.

See the documentation for every available possibility, but some basic examples are...

  • A variable defined in template.toml (tmpl allows for keys to be called as a func or variable, whichever you prefer!)
    • {{project}} or {{.project}}
    • {{author}} or {{.author}}
  • Conditionally including something
    • {{if eq project ""}} something... {{end}}

template helpers

For a full list, see helper.go

Helper Example Output
upper {{upper project}} MY-PROJECT
lower {{lower project}} my-project
title {{title project}} My-Project
snake {{snake project}} my_project
kebab {{kebab project}} my-project
pascal {{pascal project}} MyProject
camel {{camel project}} myProject
env {{env "USER"}} The current user
sep {{sep}} Filepath separator for current OS
time} {{time "01/02/2006"}} 11/21/2020 - The time according to the given format

Sources

tmpl was designed to work with any local or git-based template. Unfortunately, in contrast to boilr, this means it cannot be used with user/repo notation out of the box.

However, you can set up a source (and subsequent env variable) to make it easier to use your preferred source while still allowing for others.

Setting up a source

Let's set up a source for Gitea

tmpl source add https://gitea.com gitea

To use it, either pass it in with the --source flag

tmpl --source gitea download jolheiser/tmpls tmpls

Or set it as the env variable TMPL_SOURCE

Using a different branch

By default, tmpl will want to use a branch called main in your repository.

If you are using another branch as your default, you can set it as the env variable TMPL_BRANCH

Alternatively, you can specify on the command-line with the --branch flag of the download command

tmpl --source gitea download --branch license jolheiser/tmpls license

The above command would download the license template from jolheiser/tmpls

Putting it all together

I realize that many users will be using GitHub, and most will likely still be using the master branch.

  1. Set up a source for GitHub
    1. tmpl source add https://github.com github
    2. Set the env variable TMPL_SOURCE to github
  2. Set the env variable TMPL_BRANCH to master
  3. Happy templating! tmpl download user/repo repo

Backup and Restore

  1. The simplest solution is to make a copy of your registry.toml (default: ~/.tmpl/registry.toml).

    • Once in the new location, you will need to use tmpl restore.
  2. Alternatively, you can copy/paste the entire registry (default: ~/.tmpl) and skip the restore step.