Repository navigation
Expand file tree
/
Copy pathspec.task
More file actions
209 lines (198 loc) · 11 KB
/
Copy pathspec.task
File metadata and controls
209 lines (198 loc) · 11 KB
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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
# Taskpod task file reference. Every statement fits on one line; end a line
# with \ to continue it on the next. Comments start with #.
#
# taskpod spec.task run every task that isn't manual
# taskpod spec.task -D compare with the system: only what would change, with file diffs
# taskpod spec.task -d dry run: every task and step, change nothing
# taskpod spec.task --pull bring changed files back from the system into
# the task files, -D or -d only show what would change
# taskpod spec.task -H host run on another machine over SSH, nothing to install there
# taskpod spec.task -r hello run one task, and the tasks it needs
# taskpod spec.task -u undo every task (see Undo below), -D or -d only show it
# taskpod spec.task -l list tasks
# taskpod spec.task -g the task graph: each task with what runs before it
# (-g dot for Graphviz, -g mermaid)
# taskpod spec.task --sources
# every file it reads and the secrets each task uses
# taskpod spec.task --check check the file for errors
# taskpod spec.task -D --json --no-secrets
# the diff as JSON for editors, without decrypting secrets
# Variables. Use them anywhere with {{ name }}. Strings in "double quotes"
# understand \n, \t, \" and \; 'single quotes' are taken as written.
let greeting = "Hello"
let today = $(date +%A) # shell output, run once when first used
# Questions, asked once when first used (pausing the live display):
# let games = confirm "Install games?" true or false, so `if {{ games }}` works
# let desktop = choose "Desktop?" kde gnome one of the options
# let host = input "Hostname" "archbox" text, with an optional default
# Without a terminal: confirm is false, choose takes the first option, input the default.
# Built in: {{ home }}, {{ user }}, {{ pwd }} and {{ dir }} (this file's
# directory). Unknown names fall back to environment variables: {{ HOME }}.
# Load KEY=value lines as variables, also exported to every command:
# env ".env"
# Secrets from a sops-encrypted file (YAML, JSON, .env or INI), used as
# {{ secrets.name }}; nested keys join with dots: {{ secrets.wifi.password }}.
# Decrypted with `sops` the first time a secret is used, so runs that don't
# use one need no key. Values are hidden from output (shown as ••••), and
# `taskpod FILE --secrets other.yaml` adds files from the command line:
# secrets "secrets.yaml"
# Each file is unlocked on its own, so with a security key, several files
# mean several PINs and touches. An age identity encrypted to the key, that
# the files are also encrypted to, is decrypted once and unlocks them all
# (or `taskpod FILE --age-key taskpod.key.age`):
# age-key "taskpod.key.age"
# Merge another file, paths are relative to this one; `if`/`unless` optional:
# include "desktop.task" if pacman -Q plasma-workspace
# Commands run with `sh -ec` by default, change it with:
# shell "bash -eo pipefail -c"
task main {
desc "{{ greeting }} on a {{ today }}" # shown when the task runs
# Each `run` is a shell command, passed to the shell as written.
run echo "Hello main!"
# A block runs as one script, so `cd` and shell variables carry over.
run {
cd /tmp
name=$(whoami)
echo "Hello $name from $(pwd)"
}
}
task hello {
# Run after these tasks. They run either way (unless skipped by a guard),
# but if one fails, this task doesn't run.
needs main
# Guards, all must pass for the task to run:
# if <command> run only if the command succeeds
# unless <command> skip if the command succeeds
# ask "Question?" ask first (a dry run assumes yes)
if test -d /tmp
unless test -e /tmp/taskpod-never-exists
run echo "Hello"
# End a guard with { to only guard the steps inside, not the whole task.
unless test -e /tmp/taskpod-hello {
run touch /tmp/taskpod-hello
}
# `changed {` only runs if an earlier step in this task changed something,
# like restarting a service after its config file. In undo, its `undo`
# runs where it stands either way. In a template, a `changed` line makes
# the whole call wait for a change before it in the calling task.
file "/tmp/taskpod-hello.conf" "greeting=hello\n"
changed {
run echo "the config changed"
}
# `notice "text"` is a message for whoever runs taskpod: shown under the
# task, and again above the final summary so it isn't lost (a command's
# output only shows while it runs). It changes nothing, so a task with
# only notices is still up to date; --undo and --pull skip them.
unless test -d /tmp/taskpod-example {
notice "/tmp/taskpod-example doesn't exist yet, run -r setup"
}
}
# Subtasks run after their parent, and only if the parent changed something:
# not when it was skipped or everything in it was already up to date. Unlike
# a `changed` block, a subtask is its own task, so it can be run with -r.
subtask world of hello {
run echo "world"
}
# Templates are reusable steps. Call one with words after its name: inside
# the template, {{ args }} is all of them and {{ 1 }}, {{ 2 }}, ... each one.
# A template's guards only apply to that call, so a task can mix calls that
# are already done with ones that still need to run. A template's own
# `let $( )` or question that uses {{ }} is worked out again for each call.
template note {
unless test -e /tmp/taskpod-{{ 1 }}
run echo "{{ args }}"
}
task notes {
note first one
note second
}
task setup {
manual # only runs with -r, or when another task needs it
workdir "/tmp" # where commands run, default: this file's directory
let where = "{{ home }}" # variables can be per task
# Files are written only when their content, mode or owner differs (through
# symlinks); diffs say when only the encoding, line endings or final newline do.
# mode 600 permission bits, default 644, or 755 for content starting with #!
# owner user:group checked and set, writes with sudo
# encoding utf-16le utf-8 (default), utf-8-bom, utf-16le, utf-16be, latin1 or ascii
# sudo write as root, renaming a new file over the old one, so
# programs watching the directory never see it go missing
# new taskpod created it: --undo deletes it (see Undo below)
# keep --undo leaves it as it is
# Content is a string, a """ block, or `from "path"` (relative to this file,
# copied byte for byte unless an encoding is given).
file "/tmp/taskpod-example/hello.sh" """
#!/bin/sh
echo "hello from {{ where }}"
"""
file "/tmp/taskpod-example/copy.task" mode 600 from "spec.task"
file "/tmp/taskpod-example/windows.txt" encoding utf-16le "for notepad\n"
# `directory` copies every file in a `from` directory (subdirectories
# included), each like its own file step with the same options. Files
# there that the directory doesn't have are left alone, and --pull
# copies them into it: only from directories the source has too (not an
# app's data/ next to its config), and not ones other steps of the task
# write (like a secrets file written inline).
directory "/tmp/taskpod-example/editors" from "editors/vscode/syntaxes"
# Without `from`, only the directory: made if it's missing (with its
# parents), with `mode` (default 755) and `owner`. Undo deletes one
# taskpod made only once it's empty, and puts back a mode or owner it
# changed; `keep` leaves it (a data directory).
directory "/tmp/taskpod-example/data" mode 750 keep
# `line` makes sure a file that's otherwise left alone (a package's, or
# yours) has one line, compared ignoring spacing (`before`, `after` and
# `match` too: a tab or a run of spaces is one space). Missing, it goes before
# the first other line starting with `before`, after the last starting
# with `after`, or at the end; on the wrong side of it, it's moved. With
# `match "start"`, a line starting with that is this step's line, and is
# replaced rather than added again. The file must exist, or with `base
# "path"` (on the machine being configured) it starts as a copy of that,
# for overrides of vendor files. `sudo` reads and writes as root, keeping
# the owner and mode. The journal records what taskpod added or replaced,
# so --undo takes out only that (asking if it changed since), and deletes
# a file taskpod created once it's the base again. A line with no record
# is left; `new` says taskpod added it. `keep`: undo leaves it.
# line "~/.bashrc" ". ~/.scripts/functions.sh"
# line "/etc/pam.d/kde" sudo base "/usr/lib/pam.d/kde" match "auth sufficient pam_u2f.so" \
# before "auth" "auth sufficient pam_u2f.so cue"
run /tmp/taskpod-example/hello.sh
}
# Undo. `taskpod FILE --undo` (or -u) undoes every task, `-u -r name` one task
# and its subtasks, not what it needs; a task others still need isn't undone
# unless they're in -r too. Dependents go first, subtasks before
# their parent, and in a task the steps run last first:
# - Files go back to what they were before taskpod first wrote them, from a
# journal on the machine (~/.local/state/taskpod, /var/lib/taskpod for root
# files). A file without a record is deleted if it says `new`, otherwise
# reported. One changed since taskpod wrote it is asked about (--yes: undone).
# - Commands can't be undone by themselves: `undo` gives the command that
# does, like `run`, and runs where it stands. A block with commands but no
# `undo` is reported, unless it says `keep`: leave it as it is.
# - In undo, `unless` says when there's something to undo (its check passes
# when the task is done) and `if` still says where the task applies.
template service {
unless systemctl is-enabled -q {{ args }}
run sudo systemctl enable --now {{ args }}
undo sudo systemctl disable --now {{ args }}
}
task undo-example {
manual
file "/tmp/taskpod-example/app.conf" new "port=8080\n"
unless test -d /tmp/taskpod-example/data {
keep # data stays
run mkdir -p /tmp/taskpod-example/data
}
# At the end, so it runs first in an undo, before the file goes:
undo echo "stopping the app"
}
# More directives:
# lock name tasks holding the same lock never run at the same time,
# e.g. `lock pacman` for package installs
# sudo ask for sudo before running; commands mentioning sudo do this
# automatically, so parallel tasks never prompt at once
# interactive this task gets the terminal: nothing else runs alongside it,
# the live display pauses, and its commands can ask questions
#
# While running, each task gets a live spinner with its latest output, above
# an overall progress bar. Failed tasks show their last output; -v streams
# everything, and --plain (or no terminal) prints output prefixed by task.