A simple CLI templating tool written in golang.
If you have go
installed:
$ go get github.com/noqcks/gucci
Or you can just download the binary and move it into your PATH
:
VERSION=1.5.5
wget -q https://github.com/noqcks/gucci/releases/download/${VERSION}/gucci-v${VERSION}-darwin-amd64
chmod +x gucci-v${VERSION}-darwin-amd64
mv gucci-v${VERSION}-darwin-amd64 /usr/local/bin/gucci
gucci
can locate a template in multiple ways.
Pass the template file path as the first argument:
$ gucci template.tpl > template.out
Supply the template through standard input:
$ gucci
Start typing stuff {{ print "here" }}
^d
Start typing stuff here
Via piping:
$ echo '{{ html "<escape-me/>" }}' | gucci
gucci
can receive variables for use in templates in the following ways (in order of lowest to highest precedence):
- A JSON or YAML file
- Environment variables
- Variable command options
Given an example variables file:
# vars.yaml
hosts:
- name: bastion
- name: app
Pass it into gucci
with -f
or --vars-file
:
$ gucci -f vars.yaml template.tpl
Here, MY_HOST
is available to the template:
$ export MY_HOST=localhost
$ gucci template.tpl
Pass variable options into gucci
with -s
or --set-var
, which can be repeated:
$ gucci -s foo.bar=baz template.tpl
Variable option keys are split on the .
character, and nested such that
the above example would equate to the following yaml variable input:
foo:
bar: baz
Existing golang templating options can be used for templating.
If no option is specified, the missingkey=error
option will be used (execution stops immediately with an error if a
key used in the template is not present in the supplied values).
One might want a different value for missingkey
when using conditionals and having keys that won't be
used at all.
For instance, given the following template, containing two docker-compose services service1
and service2
:
# template.tpl
version: "3.8"
services:
{{- if .service1 }}
service1:
image: {{ .service1.image }}
restart: "always"
ports: {{ toYaml .service1.ports | nindent 6}}
{{- end }}
{{- if .service2 }}
service2:
image: {{ .service2.image }}
restart: "unless-stopped"
ports: {{ toYaml .service2.ports | nindent 6}}
{{- end }}
And imagine a scenario where whe only need service2
. By using the following values file:
# values.yaml
service2:
image: "myservice:latest"
ports:
- "80"
- "443"
And using a different missingkey=error
, we can actually get the desired result without having to define the values
for service1
:
$ gucci -o missingkey=zero -f values.yaml template.tpl
version: "3.8"
services:
service2:
image: myservice:latest
restart: "unless-stopped"
ports:
- "80"
- "443"
All of the existing golang templating functions are available for use.
gucci ships with the sprig templating functions library offering a wide variety of template helpers. Sprig's env
and expandenv
functions are disabled in favor of gucci's own environment variable parsing (see below).
Furthermore, this tool also includes custom functions:
-
shell
: For arbitrary shell commands{{ shell "echo hello world" }}
and
# guest: world {{ shell "echo hello " .guest }}
Both produce:
hello world
-
toYaml
: Print items in YAML format{{ $myList := list "a" "b" "c" }} {{ toYaml $myList }}
Produces:
- a - b - c
NOTE: gucci reads and makes available all environment variables.
For example a var $LOCALHOST = 127.0.0.1
gucci template.tpl > template.conf
# template.tpl
{{ .LOCALHOST }}
gucci template.tpl > template.conf
-->
# template.conf
127.0.0.1
simple enough!
For an iteration example, you have $BACKENDS=server1.com,server2.com
# template.tpl
{{ range split .BACKENDS "," }}
server {{ . }}
{{ end }}
gucci template.tpl > template.conf
-->
# template.conf
server server1.com
server server2.com
Setup:
go get github.com/noqcks/gucci
go get github.com/onsi/ginkgo/ginkgo
go get github.com/onsi/gomega
Run tests:
ginkgo ./...