tmpl/DOCS.md

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.

.tmplkeep

Perhaps you are familiar with .gitkeep and its unofficial status in git. Git does not like empty directories, so usually a .gitkeep (or just .keep) file is added to retain the directory while keeping it effectively empty.

tmpl instead uses .tmplkeep files for this purpose. The difference is, tmpl will not create the .tmplkeep file when the template is executed. This allows you to set up directory structures (for staging, examples, etc.) that will actually be empty after execution.