1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
# 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](https://golang.org/pkg/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`.
```toml
# 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](https://golang.org/pkg/text/template/).
See the [documentation](https://golang.org/pkg/text/template/) 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](registry/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](https://flaviocopes.com/go-date-time-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](https://gitea.com)
```
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](https://git.jojodev.com/jolheiser/tmpls/src/branch/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.
|