templative

A tiny CLI for instantiating project templates from local directories. Templates are tracked by absolute path; there is no templating engine.

Git is initialized by default (with an initial commit) when you create a project from a template.

Commands

Optional flags are available to view with --help. This also applies to subcommands, e.g. templative change --help.

Install

Homebrew:

brew tap serenacula/tap
brew install templative

Cargo:

cargo install templative

Or download a pre-built binary from the releases page.

Completions

zsh:

mkdir -p ~/.zsh/completions
templative completions zsh > ~/.zsh/completions/_templative

Then add these two lines to your ~/.zshrc before any existing compinit call (or at the end if you don't have one):

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Then: source ~/.zshrc

bash:

mkdir -p ~/.local/share/bash-completion/completions
templative completions bash > ~/.local/share/bash-completion/completions/templative

fish:

templative completions fish > ~/.config/fish/completions/templative.fish

PowerShell:

templative completions powershell >> $PROFILE
. $PROFILE

To check whether an installed script is up to date after upgrading templative:

templative completions zsh --check ~/.zsh/completions/_templative

Config

The config can be used to set values that apply across all templates, or which affect tool functionality. Values here can be overridden by settings in templates.json or with flags.

• Config location:
  • Linux / macOS: ~/.config/templative/config.json
  • Windows: %APPDATA%\templative\templative\config.json

A default config is created automatically if there isn't one. This is the default config created, with comments added:

{
    // config.json version
    "version": 1,

    // whether to display colors in `templative list`
    "color": true,

    // git init behaviour
    // fresh: copy the template files and start a new git history
    // preserve: clone the template repo, keeping its full git history
    //   note: preserve ignores exclude patterns and write-mode — it clones the repo as-is
    // no-git: copy files only, no git setup
    "git": "fresh",

    // files excluded when creating a new template - glob patterns are accepted
    "exclude": ["node_modules", ".DS_Store"],

    // overwrite behaviour during init
    // strict: fail if target directory isn't empty
    // no-overwrite: fail if a file would be overwritten
    // skip-overwrite: skip overwriting files
    // overwrite: overwriting existing files
    // ask: ask the user when collision detected
    "write_mode": "strict"
}

Template Registry

The registry of available templates is the backbone of templative. You can customise individual templates with specific behaviours using templative change.

By default optional fields are not set. In this case they fallback to the config setting.

• Registry location:
  • Linux / macOS: ~/.config/templative/templates.json
  • Windows: %APPDATA%\templative\templative\templates.json

{
    // templates.json version
    "version": 2,
    "templates": [
        {
            "name": "example-template",
            "location": "/templates/example-template",

            // below are optional features specific to templates
            // these are not defaults, they're just examples

            // a description for `template list`
            "description": "an example template",
            // pin a git template to a specific commit/branch/tag
            "git-ref": "v2.0.0",
            // hook that runs before init
            "pre-init": "pwd",
            // hook that runs after init
            "post-init": "ls -l",

            // below are optional features that override the config behaviours

            "git": "fresh",
            "exclude": ["target"],
            "write-mode": "ask"
        }
    ]
}