templative 1.0.1

A tiny CLI for managing project templates
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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

# 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

| Command | Description |
|---|---|
| `templative init TEMPLATE [PATH]` | Copy a template into PATH (default: current directory), then run `git init` and an initial commit. |
| `templative add [PATH] [--name NAME]` | Register an existing directory as a template (default PATH: current directory; default name: directory name). |
| `templative change TEMPLATE [FLAGS]` | Change and set custom features for individual templates. |
| `templative remove TEMPLATE...` | Remove one or more templates from the registry. Does not delete the actual files. |
| `templative update [TEMPLATE] [--check]` | Update cached git templates. Omit name to update all. `--check` reports what's out of date without applying changes. |
| `templative list` | Show registered templates and their paths. |

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

## Install

**Homebrew:**

```sh
brew tap serenacula/tap
brew install templative
```

**Cargo:**

```sh
cargo install templative
```

Or download a pre-built binary from the [releases page](https://github.com/serenacula/templative/releases).

### Completions

**zsh:**

```sh
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):

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

Then: `source ~/.zshrc`

**bash:**

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

**fish:**

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

**PowerShell:**

```sh
templative completions powershell >> $PROFILE
. $PROFILE
```

---

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

```sh
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:

```json
{
    // 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`

```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"
        }
    ]
}
```