feat: derive template name
Signed-off-by: jolheiser <john.olheiser@gmail.com>pull/27/head
parent
4981a14e14
commit
181aa60d1b
GPG Key ID:
B853ADA5DA7BBF7A
128
FAQ.md
128
FAQ.md
|
|
@ -1,128 +0,0 @@
|
||||||
# tmpl templates
|
|
||||||
|
|
||||||
This documentation aims to cover FAQs and setup.
|
|
||||||
|
|
||||||
## Setting up a template
|
|
||||||
|
|
||||||
A "valid" tmpl template only requires two things
|
|
||||||
|
|
||||||
1. A `tmpl.yaml` file in the root directory.
|
|
||||||
2. A `template` directory that serves as the "root" of the template.
|
|
||||||
|
|
||||||
## tmpl.yaml
|
|
||||||
|
|
||||||
**NOTE:** The tmpl.yaml file will be expanded, though not with the full power of the template itself.
|
|
||||||
The tmpl.yaml 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`.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# tmpl.yaml
|
|
||||||
# Write any template args here to prompt the user for, giving any defaults/options as applicable
|
|
||||||
|
|
||||||
prompts:
|
|
||||||
- id: project # The unique ID for the prompt
|
|
||||||
label: Project Name # The prompt message/label
|
|
||||||
help: The name to use in the project # Optional help message for the prompt
|
|
||||||
default: tmpl # Prompt default
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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...
|
|
||||||
|
|
||||||
* An id defined in `tmpl.yaml` (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/) |
|
|
||||||
| trim_prefix | `{{trim_prefix "foobar" "foo"}}` | `bar` |
|
|
||||||
| trim_suffix | `{{trim_suffix "foobar" "bar"}}` | `foo` |
|
|
||||||
| replace | `{{replace "foobar" "bar" "baz"}}` | `foobaz` |
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
@ -2,6 +2,8 @@ package cmd
|
||||||
|
|
||||||
import (
|
import (
|
||||||
"fmt"
|
"fmt"
|
||||||
|
"os"
|
||||||
|
"path"
|
||||||
"strings"
|
"strings"
|
||||||
|
|
||||||
"go.jolheiser.com/tmpl/env"
|
"go.jolheiser.com/tmpl/env"
|
||||||
|
|
@ -15,7 +17,7 @@ var Download = &cli.Command{
|
||||||
Name: "download",
|
Name: "download",
|
||||||
Usage: "Download a template",
|
Usage: "Download a template",
|
||||||
Description: "Download a template and save it to the local registry",
|
Description: "Download a template and save it to the local registry",
|
||||||
ArgsUsage: "[repository URL] [name]",
|
ArgsUsage: "[repository URL] <name>",
|
||||||
Flags: []cli.Flag{
|
Flags: []cli.Flag{
|
||||||
&cli.StringFlag{
|
&cli.StringFlag{
|
||||||
Name: "branch",
|
Name: "branch",
|
||||||
|
|
@ -29,7 +31,7 @@ var Download = &cli.Command{
|
||||||
}
|
}
|
||||||
|
|
||||||
func runDownload(ctx *cli.Context) error {
|
func runDownload(ctx *cli.Context) error {
|
||||||
if ctx.NArg() < 2 {
|
if ctx.NArg() < 1 {
|
||||||
return cli.ShowCommandHelp(ctx, ctx.Command.Name)
|
return cli.ShowCommandHelp(ctx, ctx.Command.Name)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
@ -67,7 +69,7 @@ func runDownload(ctx *cli.Context) error {
|
||||||
cloneURL += ".git"
|
cloneURL += ".git"
|
||||||
}
|
}
|
||||||
|
|
||||||
t, err := reg.DownloadTemplate(ctx.Args().Get(1), cloneURL, ctx.String("branch"))
|
t, err := reg.DownloadTemplate(deriveName(ctx), cloneURL, ctx.String("branch"))
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return err
|
return err
|
||||||
}
|
}
|
||||||
|
|
@ -75,3 +77,19 @@ func runDownload(ctx *cli.Context) error {
|
||||||
log.Info().Msgf("Added new template %q", t.Name)
|
log.Info().Msgf("Added new template %q", t.Name)
|
||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
|
|
||||||
|
func deriveName(ctx *cli.Context) string {
|
||||||
|
if ctx.NArg() > 1 {
|
||||||
|
return ctx.Args().Get(1)
|
||||||
|
}
|
||||||
|
|
||||||
|
envBranch, envSet := os.LookupEnv("TMPL_BRANCH")
|
||||||
|
flagBranch, flagSet := ctx.String("branch"), ctx.IsSet("branch")
|
||||||
|
if flagSet {
|
||||||
|
if !envSet || envBranch != flagBranch {
|
||||||
|
return flagBranch
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return path.Base(ctx.Args().First())
|
||||||
|
}
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue