From 181aa60d1be3591adf40847430e26d67d4e419bf Mon Sep 17 00:00:00 2001 From: jolheiser Date: Wed, 16 Aug 2023 22:58:21 -0500 Subject: [PATCH 1/3] feat: derive template name Signed-off-by: jolheiser --- FAQ.md | 128 ------------------------------------------------ cmd/download.go | 24 +++++++-- 2 files changed, 21 insertions(+), 131 deletions(-) delete mode 100644 FAQ.md diff --git a/FAQ.md b/FAQ.md deleted file mode 100644 index 6ec6f61..0000000 --- a/FAQ.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/cmd/download.go b/cmd/download.go index f5ce256..9338733 100644 --- a/cmd/download.go +++ b/cmd/download.go @@ -2,6 +2,8 @@ package cmd import ( "fmt" + "os" + "path" "strings" "go.jolheiser.com/tmpl/env" @@ -15,7 +17,7 @@ var Download = &cli.Command{ Name: "download", Usage: "Download a template", Description: "Download a template and save it to the local registry", - ArgsUsage: "[repository URL] [name]", + ArgsUsage: "[repository URL] ", Flags: []cli.Flag{ &cli.StringFlag{ Name: "branch", @@ -29,7 +31,7 @@ var Download = &cli.Command{ } func runDownload(ctx *cli.Context) error { - if ctx.NArg() < 2 { + if ctx.NArg() < 1 { return cli.ShowCommandHelp(ctx, ctx.Command.Name) } @@ -67,7 +69,7 @@ func runDownload(ctx *cli.Context) error { 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 { return err } @@ -75,3 +77,19 @@ func runDownload(ctx *cli.Context) error { log.Info().Msgf("Added new template %q", t.Name) 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()) +} -- 2.41.0 From 4b7aa8a03e3d2b9a15ba4efce4df57362f468416 Mon Sep 17 00:00:00 2001 From: jolheiser Date: Wed, 16 Aug 2023 22:58:58 -0500 Subject: [PATCH 2/3] docs: update FAQ Signed-off-by: jolheiser --- FAQ.md | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 FAQ.md diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..3b6bcfa --- /dev/null +++ b/FAQ.md @@ -0,0 +1,128 @@ +# 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.yaml` (default: `~/.tmpl/registry.yaml`). + * 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. \ No newline at end of file -- 2.41.0 From b687e6348e0b080a0e11f26a4f5349c1371b2859 Mon Sep 17 00:00:00 2001 From: jolheiser Date: Sun, 20 Aug 2023 12:28:04 -0500 Subject: [PATCH 3/3] feat: nushell completions Signed-off-by: jolheiser --- cmd/list.go | 15 ++++- cmd/source.go | 15 ++++- contrib/tmpl-completions.nu | 113 ++++++++++++++++++++++++++++++++++++ 3 files changed, 139 insertions(+), 4 deletions(-) create mode 100644 contrib/tmpl-completions.nu diff --git a/cmd/list.go b/cmd/list.go index 32002be..7c1be1a 100644 --- a/cmd/list.go +++ b/cmd/list.go @@ -1,6 +1,7 @@ package cmd import ( + "encoding/json" "fmt" "os" "text/tabwriter" @@ -14,15 +15,25 @@ var List = &cli.Command{ Name: "list", Usage: "List templates in the registry", Description: "List all usable templates currently downloaded in the registry", - Action: runList, + Flags: []cli.Flag{ + &cli.BoolFlag{ + Name: "json", + Usage: "JSON format", + }, + }, + Action: runList, } -func runList(_ *cli.Context) error { +func runList(ctx *cli.Context) error { reg, err := registry.Open(registryFlag) if err != nil { return err } + if ctx.Bool("json") { + return json.NewEncoder(os.Stdout).Encode(reg.Templates) + } + wr := tabwriter.NewWriter(os.Stdout, 0, 8, 1, '\t', 0) if _, err := fmt.Fprintf(wr, "NAME\tURL\tLOCAL\tLAST UPDATED\n"); err != nil { return err diff --git a/cmd/source.go b/cmd/source.go index 1a5f820..70f2adb 100644 --- a/cmd/source.go +++ b/cmd/source.go @@ -1,6 +1,7 @@ package cmd import ( + "encoding/json" "fmt" "os" "text/tabwriter" @@ -28,7 +29,13 @@ var ( Name: "list", Usage: "List available sources", Description: "List all available sources in the registry", - Action: runSourceList, + Flags: []cli.Flag{ + &cli.BoolFlag{ + Name: "json", + Usage: "JSON format", + }, + }, + Action: runSourceList, } SourceAdd = &cli.Command{ @@ -48,12 +55,16 @@ var ( } ) -func runSourceList(_ *cli.Context) error { +func runSourceList(ctx *cli.Context) error { reg, err := registry.Open(registryFlag) if err != nil { return err } + if ctx.Bool("json") { + return json.NewEncoder(os.Stdout).Encode(reg.Sources) + } + wr := tabwriter.NewWriter(os.Stdout, 0, 8, 1, '\t', 0) if _, err := fmt.Fprintf(wr, "NAME\tURL\n"); err != nil { return err diff --git a/contrib/tmpl-completions.nu b/contrib/tmpl-completions.nu new file mode 100644 index 0000000..ca99993 --- /dev/null +++ b/contrib/tmpl-completions.nu @@ -0,0 +1,113 @@ +def _tmpl_env_keys [] { + ["TMPL_SOURCE", "TMPL_REGISTRY", "TMPL_BRANCH"] +} + +def _tmpl_source_list [] { + ^tmpl source list --json | from json | each { |it| { value: $it.Name, description: $it.URL } } +} + +def _tmpl_template_list [] { + ^tmpl list --json | from json | each { |it| { value: $it.Name, description: (if $it.Path != "" { $it.Path } else { $"($it.Repository)@($it.Branch)" }) } } +} + + +# Template automation +export extern "tmpl" [ + --registry(-r): string # Registry directory of tmpl (default: ~/.tmpl) [$TMPL_REGISTRY] + --source(-s): string # Short-name source to use [$TMPL_SOURCE] + --help(-h): bool # Show help + --version(-v): bool # Show version +] + +# Download a template +export extern "tmpl download" [ + repo_url: string # Repository URL + name: string # Local name for template + --branch(-b): string # Branch to clone (default: "main") [$TMPL_BRANCH] + --help(-h): bool # Show help +] + +# Manage tmpl environment variables +export extern "tmpl env" [ + --help(-h): bool # Show help +] + +# Set a tmpl environment variable +export extern "tmpl env set" [ + key: string@"_tmpl_env_keys" # Env key + value: string # Env value + --help(-h): bool # Show help +] + +# Unset a tmpl environment variable +export extern "tmpl env unset" [ + key: string@"_tmpl_env_keys" # Env key +] + +# Initialize a blank tmpl template +export extern "tmpl init" [ + --help(-h): bool # Show help +] + +# List all templates in registry +export extern "tmpl list" [ + --json: bool # Output in JSON + --help(-h): bool # Show help +] + +# Remove a template +export extern "tmpl remove" [ + name: string # Name of the template to remove + --help(-h): bool #Show help +] + +# Restore templates present in the registry, but missing archives +export extern "tmpl restore" [ + --help(-h): # Show help +] + +# Save a local template +export extern "tmpl save" [ + path: string # Path to the local template + name: string # Name of the template + --help(-h): bool # Show help +] + +# Work with tmpl sources +export extern "tmpl source" [ + --help(-h): # Show help +] + +# Add a tmpl source +export extern "tmpl source add" [ + base_url: string # Base URL + name: string # Name + --help(-h): bool # Show help +] + +# Remove a tmpl source +export extern "tmpl source remove" [ + name: string@"_tmpl_source_list" # Source to remove + --help(-h): bool # Show help +] + +# Test whether a directory is a valid tmpl template +export extern "tmpl test" [ + path?: string # Path to test (default: ".") + --help(-h): bool # Show help +] + +# Update a template +export extern "tmpl update" [ + name: string@"_tmpl_template_list" # Template to update + --help(-h): # Show help +] + +# Use a template +export extern "tmpl use" [ + name: string@"_tmpl_template_list" # The template to execute + dest?: path # Destination for the template (default: ".") + --defaults: bool # Use template defaults + --force: bool # Overwrite existing files + --help(-h): bool # Show help +] -- 2.41.0