Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Batfiles repository format

Manifest syntax and action fields. Start with the README example.

Layout · Schema · Names · Remotes · Paths · Filters · Actions · Clone lists · Variables · Conditions · Templates · Bootstrap defaults

Repository layout

A repository is an ordinary file tree with batfiles.toml at its root. Other files matter only when an action references them. Batfiles owns generated remotes/; add it to .gitignore.

The leaf repository is selected by location precedence. A remote’s manifest is optional until an include-remote asks to read it.

Reading the manifest

Every document is read and validated in full before its contents are used, including before its dynamic commands run. An included manifest is read only when its inclusion opens, after the leaf’s variables have resolved.

  • Missing or unreadable manifests fail the command. Missing state files are instead empty documents.
  • Malformed TOML or invalid schema fails with the file and position; the file is left untouched.
  • Unknown record fields, invalid value shapes, and cross-record violations such as duplicate IDs are load errors. Action diagnostics use one-based positions in the manifest.
  • An empty manifest is valid. Commands that do not read the repository are unaffected by its manifest.

Top-level schema

All four sections are optional. There is no format-version field.

[remotes]                  # map<ID, Remote>

[[actions]]                # ordered list<Action>

[vars]                     # map<variable name, string | dynamic variable>

[default-disabled]         # leaf bootstrap policy
[[default-disabled.actions]]
[[default-disabled.groups]]

Records are closed: only documented fields and variants are accepted. Keys in [remotes] and [vars] are user-chosen names, validated by the rules below.

Names and IDs

KindSyntaxConstraints
Action ID, group, remote ID[A-Za-z0-9][A-Za-z0-9_-]*No whitespace, dots, or commas
Variable name[A-Za-z_][A-Za-z0-9_]*Cannot be facts, env, vars, true, or false

Action IDs must be unique within a repository; a duplicate error names both records. Remote IDs must also be distinct ignoring case on every platform, because they name materialization paths. Group, action, and remote names occupy separate namespaces.

Variable names are case-sensitive. _hidden is a variable name but not an ID; 9front and oh-my-zsh are IDs but not variable names. Dots join IDs into addresses.

Remotes

[remotes] is a map from a name to a record describing content this repository does not hold: another repository, a file, or an archive. The key is the remote’s ID:

[remotes.core]
type = "git"
url = "git@github.com:me/dotfiles-core.git"
ref = "main"

Every remote is a closed record selected by its required type:

FieldTypeRequiredDescription
typeremote-type stringyesSelects the record variant: git, file, or archive.
whenconditionnoSee conditions.
unlessconditionnoAt most one of the two.

A type the schema does not name is refused as the manifest is read, because there is no record behind it to check, and so is a field the selected variant does not have.

git

A repository for git to clone.

FieldTypeRequiredDescription
urltemplate stringyesA repository for git to clone. Never empty.
reftemplate stringnoA branch, tag, or commit to follow. Never empty.
allow-dynamic-varsbooleannoWhether an included manifest’s dynamic-variable commands run. Defaults to false.
allow-env-templatesbooleannoWhether an included manifest’s templates may read env; see templates and the host environment. Defaults to false.
allow-commandsbooleannoWhether an included manifest’s run actions run their commands. Defaults to false.

url follows git-clone source syntax, and ref follows its ref rules. branch is not a field.

allow-dynamic-vars permits dynamic-variable commands in an included manifest. Without it, command declarations there declare nothing, and -v names those skipped. Its github-release declarations still resolve: a lookup runs no code, so a remote with no permissions can supply a dynamic value, as it can already supply any static value. Leaf declarations need no permission. See dynamic-command execution.

Each permission applies only to a checkout of the repository url names; see permissions follow the origin.

A remote supplies content; an action decides where to install it. Only the leaf’s [remotes] is materialized. An included manifest’s map is ignored.

file

One file, fetched from a URL.

[remotes.pathogen]
type = "file"
url = "https://raw.githubusercontent.com/tpope/vim-pathogen/master/autoload/pathogen.vim"
FieldTypeRequiredDescription
urltemplate stringyesAn http://, https://, or file:// URL.
sha256template stringno64 hexadecimal digits: the digest the fetched bytes must have.
executablebooleannoWhether the file lands executable. Defaults to false.
decompressbooleannoWhether the download is a gzip or bzip2 stream holding the file. Defaults to false.

The materialization is the file itself, at remotes/<id>, so a repository path names it whole, as @pathogen or { remote = "pathogen" }:

[[actions]]
type = "symlink"
source = "@pathogen"
dest = "~/.vim/autoload/pathogen.vim"

A path under a file remote, or a source-dir naming one, is a load error. It is fetched by the shared transfer, with fetched-file permissions; executable and decompress mean what they do for fetch-file.

archive

A zip or tarball fetched from a URL and unpacked.

[remotes.fzf]
type = "archive"
url = "https://example.com/fzf-0.65.2.tar.gz"
archive-root = "*"
FieldTypeRequiredDescription
urltemplate stringyesAn http://, https://, or file:// URL.
sha256template stringno64 hexadecimal digits: the digest the fetched archive must have.
archive-rootstringnoA prefix every entry is written without, or * for the archive’s single top-level directory.
includeglob or listnoEntries to unpack, by their path once the root is stripped; absent, every entry. See entry filters.
excludeglob or listnoEntries not to unpack.
executableglob or listnoFiles to make executable, by their path once the root is stripped. See fetch-archive.

The archive is unpacked into remotes/<id>/ as fetch-archive unpacks into its dest, with the same formats, archive-root, filters, executable, and archive safety. Actions read paths within it as within a Git clone, such as @fzf/bin/fzf.

File and archive remotes have no manifest, so include-remote cannot name them.

Materialization

sync materializes (fetches or updates) every remote whose condition holds at remotes/<id> before any action, even if no action uses it. Two IDs naming one URL have separate materializations.

Git remotes clone or update under the Git policy, following ref when supplied. An unusable checkout at a tool-owned path is refused under every conflict policy; see clone validation.

File and archive remotes use a sibling stamp, remotes/<id>.batfiles-source, to record their fetching declaration and detect changes:

At remotes/<id>Stampsync
NothingAny, or noneFetch
Node of the stamp’s recorded kindMatches declarationKeep; report unchanged at -v
Node of the stamp’s recorded kindDiffers from declarationRefetch and replace
Anything elseMissing, unreadable, invalid, or wrong kindRefuse before fetching

The stamp covers the type, URL, digest, and type-specific options. It records resolved values, so a changed URL refetches. Digests compare case-insensitively; a single pattern and a one-element list compare equally, but pattern order matters. Replacement is staged and verified; a failed fetch leaves the old materialization and stamp in place and fails the run. sync --refresh-remotes forces refetching when a declaration is unchanged.

An unclaimed node, including a clone left under an ID now declared as a file or archive, must be moved aside or removed before retrying. A Git materialization removes any obsolete stamp beside it.

Materialization failure, including a failed template, stops the run before any action. Apply commands and dry runs fetch nothing and use existing trees, however stale. An action whose source remote is absent fails naming the remote; a missing inclusion is handled by plan completeness.

A remote’s condition

[remotes.corporate]
type = "git"
url = "git@git.example.com:it/dotfiles.git"
when = "work"

A remote’s condition decides whether it may be materialized or read. Every execution command evaluates it, including apply commands. An excluded remote is neither updated nor read, even if a previous materialization remains; that tree is not deleted.

An action sourcing an excluded remote fails naming the remote and reason. Usually it should carry the same condition. An inclusion of the excluded remote instead contributes nothing. See exclusion reporting.

Sources and destinations

A repository path identifies content within the declaring repository or a declared remote. symlink, copy, and git-clone-list use one as source; symlink-dir and copy-dir use one as source-dir. Fetching actions and git-clone have their own source syntax.

source = "files/zshrc"                             # declaring repository
source = "@core/files/zshrc"                       # declared remote
source = { remote = "core", path = "files/zshrc" } # same remote path

The structured form is closed and requires remote; omitting path means @<remote>. Both remote spellings resolve and appear in diagnostics identically.

  • A remote reference must name a remote in the same manifest. Undeclared references fail at load time; absent materializations fail at execution.
  • A file remote is named whole (@pathogen or { remote = "pathogen" }). A path within it or a source-dir naming it is invalid.
  • Tree paths must be nonempty, relative, and remain strictly inside the tree. . and .. are allowed only within that constraint. ., ./, shell/.., and a tree remote with no path are invalid.
  • Use / separators. Anchored paths and drive prefixes are rejected according to the host’s path syntax. Symlinks within a repository may point outside it.
  • An initial @ is reserved with no escape, including inside a structured path. Elsewhere it is ordinary text, as in files/@work/zshrc.

Diagnostics identify the source tree. Sources are checked when an action runs, including dry runs. A final broken symlink counts as present for linking; copies must read its target. source-dir must resolve to a directory. Clone-list sources are read during preparation.

dest and dest-dir are template strings whose resolved values use the selected home as their relative base:

FormResolution
~Selected home
~/path or pathRelative to selected home
Absolute pathUsed as written
Empty value or ~otherInvalid

Destinations may leave the selected home. Roots are anchored and paths normalized lexically. Location selection defines roots; installation safety defines filesystem resolution, source containment, conflicts, and staging.

Entry filters

include and exclude select tree entries for symlink-dir, copy, copy-dir, fetch-archive, and archive remotes. Each accepts one glob or a list; archive executable patterns use the same matching rules.

include = "*rc"
exclude = ["private", "**/*.bak"]

Paths are relative to the root specified by the action, with / separators on every platform. Patterns match the whole path, case-sensitively.

SyntaxMatches
*Any run of bytes within one segment, including a leading .
?One byte within a segment
[abc], [a-z], [!abc]One byte in, or outside, the class
{a,b}Either alternative within one segment
**Zero or more whole segments; must be a segment of its own

Only ** crosses separators: *.bak matches at the root, **/*.bak at any depth. Classes and alternatives cannot contain /. Backslash is literal; use [*] for a literal *. Byte matching means ?.txt and [é].txt both miss é.txt; use the literal character or *.

An entry is selected when it or an ancestor directory matches include, or include is absent, and neither it nor an ancestor matches exclude. Exclusion wins. include = [] selects nothing. Unselected, nonexcluded directories are created only when needed to hold selected descendants. For example, including bin and excluding bin/secret installs the rest of bin; including scripts/lib creates scripts holding only lib.

Empty patterns, leading /, empty/./.. segments (including a trailing /), and malformed globs are load errors. Patterns matching nothing are not errors; -v names the pattern and tree.

Actions

symlink · symlink-dir · create-dir · copy · copy-dir · fetch-file · fetch-archive · git-clone · git-clone-list · include-remote · run

[[actions]] is an ordered list. Each entry is a closed record selected by its required type field.

FieldTypeRequiredDescription
typeaction-type stringyesSelects the action variant. symlink, symlink-dir, create-dir, copy, copy-dir, fetch-file, fetch-archive, git-clone, git-clone-list, include-remote, and run are the ones that exist.
idIDnoMakes the action addressable.
groupIDnoPlaces the action in one group. See groups.
whenconditionnoRuns the action only where the condition is true. See conditions.
unlessconditionnoRuns it only where the condition is false. At most one of the two.

Each variant accepts only its documented fields. A field belonging to another variant is an error when the manifest is read: for example, symlink takes source, while symlink-dir takes source-dir. Only symlink-dir and copy-dir accept dot-prefix, which adds a leading . to each installed name.

symlink and copy install one file or directory at one destination. symlink-dir and copy-dir install each direct child into a destination directory. Choose the type explicitly; it is not inferred from the source’s filesystem type. To download and unpack an archive, use fetch-archive; fetch-file installs the downloaded bytes as one file.

include-remote and run install nothing of their own. An inclusion names a remote and takes what that repository’s manifest declares, at its position in this list; a run action runs a command, as often as its trigger says.

Groups

A group consists of the actions whose group field names it. Each action has at most one group; there is no [groups] declaration. Group values use the ID syntax, and may share names with actions. Membership does not change declaration order or require adjacency.

Use groups to apply, disable, or skip members together. See selection.

The transfer both fetching actions share

Both fetching actions use these rules:

  • HTTP, HTTPS, and file:// URLs; up to five redirects.
  • Status 200 OK is required. Partial, empty-status, and conditional responses such as 206, 204, and 304 fail.
  • An optional sha256 is checked against the downloaded bytes. A mismatch reports both digests and installs nothing. Archives are verified before extraction, and compressed files before decompression.
  • No Accept-Encoding request header. Proxy environment variables are honored.
  • TLS certificates use the operating system’s trust store, including corporate CAs trusted by that machine.
  • Thirty seconds to connect, thirty seconds to receive response headers, and ten minutes total for the body.

An incomplete or failed transfer is not published. See staging and publication.

File URLs

A file:// URL reads a whole local file and verifies sha256 if supplied. HTTP status, redirects, proxies, and timeouts do not apply.

Use an absolute path: file:///home/you/tool.tar.gz, file://localhost/home/you/tool.tar.gz, or file:///C:/tools/a.zip on Windows. Paths are percent-decoded; encode spaces as %20, ? as %3F, and # as %23. Queries, fragments, and hosts other than localhost are load errors. Missing or unreadable files fail when the action runs, naming the path.

An included manifest’s own [remotes]

See An included manifest’s own [remotes].

The clone list format

A git-clone-list source is a text file with one repository per line:

# vim plugins
https://github.com/tpope/vim-fugitive.git
https://github.com/romkatv/powerlevel10k.git dest-name=p10k id=p10k
https://github.com/company/internal-zsh-tools.git when="work" # work only
<repository> [<key>=<value> ...] [# <comment>]

The repository is the first whitespace-delimited field, passed unchanged to Git. Blank lines are ignored. The first # outside quoted values begins a comment; encode a repository URL’s literal # as %23.

KeyTypeDescription
idIDEntry address suffix and diagnostic name
refstringBranch, tag, or commit; follows ref rules
dest-namestringExplicit clone directory name
when / unlessconditionEntry gate; at most one

Unknown keys, repeated keys, empty key= values, and fields lacking = fail. Values may be quoted with ' or " to contain spaces or #. Inside quotes, only \\, \", and \' are escapes; other escapes and unclosed quotes fail.

Conditions use the enclosing action’s scope and the shared condition rules. See preparation for evaluation timing. An explicit id permits individual selection and appears in diagnostics as id=p10k, plugins.txt line 3; otherwise entries are named by file and line. IDs are never derived from directory names: ack.vim is a valid directory name but not an ID.

What a clone is called

Without dest-name, use everything after the repository’s last / or :, removing a trailing .git. This derivation is textual, independent of URL kind.

Derived or explicit names must be one directory component: nonempty, not ., .., or .git, and containing no /, \, or :. An invalid derived name asks for an explicit dest-name.

Destination names must be unique ignoring case on every platform; entry IDs must also be unique. Duplicate errors name both lines. One repository under two distinct destination names is valid, and destination spelling is preserved. The first error stops list loading, identifying the file, line, and fault.

Variables

[vars] maps variable names to strings or dynamic declarations:

[vars]
work = "false"
profile = "personal"
rank = "3"
email = { command = ["git", "config", "user.email"], cache = "1d" }
fzf_tag = { github-release = "junegunn/fzf" }

Variables feed when, unless, and templates. A [vars] value is not a template, so one variable cannot refer to another; the one exception, a github-release declaration’s github-url, reads only env and facts. Static values must be strings, including empty strings: work = true and rank = 3 are load errors. A table must match the dynamic-variable schema.

See variable precedence for machine values, environment and CLI overrides, and inclusion scopes. Dynamic declarations are captured even when no condition uses them; see evaluation.

Dynamic variables

A table under [vars] declares a variable whose value is captured rather than written: by running a command, or by looking up a GitHub release. A table is exactly one kind: github-release together with command, capture, or command-timeout is a load error, as is github-url or timeout beside command, and the error names the conflicting field. A table with neither command nor github-release is a load error too. Both kinds share cache:

FieldTypeRequiredDefaultDescription
cachedurationno"1d"How long a captured value is reused before it is captured again.

Cache rules define reuse, refresh, and failure fallback.

A declaration with no captured or cached value still declares the variable; it reads as the empty string and overrides lower layers. Consequently when on it closes but unless opens. Use when when installation requires a successful answer.

Command declarations

A command declaration’s value is what a command produces. Both TOML spellings are the same record:

[vars]
email = { command = ["git", "config", "user.email"], cache = "24h" }

[vars.has_op]
command = "command -v op >/dev/null"
capture = "status"
cache = "1h"
command-timeout = "5s"
FieldTypeRequiredDefaultDescription
commandstring or non-empty list of stringsyesA shell command line, or a program and its arguments run without a shell.
capture"stdout" or "status"no"stdout"The trimmed standard output, or "true"/"false" from the exit status.
command-timeoutdurationno"5s"How long the command may run before it is killed. Greater than zero.

Unknown fields, empty command lists, invalid capture modes or durations, and zero timeouts are load errors.

Execution defines shell selection, working directory, streams, limits, and capture semantics. Remote command declarations require allow-dynamic-vars.

GitHub release declarations

A github-release declaration’s value is the tag of a GitHub repository’s latest release, so a manifest can follow a project’s releases without a fixed URL. A template builds the download URL from it:

[vars.fzf_tag]
github-release = "junegunn/fzf"
cache = "1d"

[remotes.fzf]
type = "archive"
url = "https://github.com/junegunn/fzf/releases/download/${fzf_tag}/fzf-${fzf_tag.substring(1)}-linux_${{'x86_64': 'amd64', 'aarch64': 'arm64'}[facts.arch]}.tar.gz"
FieldTypeRequiredDefaultDescription
github-releasestringyesOWNER/REPO whose latest release’s tag is the value.
github-urlrestricted templateno"https://github.com"The GitHub host to ask, as an http:// or https:// URL.
timeoutdurationno"10s"How long the whole lookup may take. Greater than zero.

OWNER/REPO is checked as the manifest loads: an owner of ASCII letters, digits, and -; one /; and a repository of those, _, and ., but not . or ... A scheme, a host, or a .git suffix is a load error. It is not a template.

The value is the tag exactly as GitHub names it, such as v0.65.2, with nothing stripped; remove a prefix in the template, as ${fzf_tag.substring(1)} does above. “Latest” is GitHub’s: the most recent release that is neither a draft nor a prerelease. How a lookup is made defines the request and its failures. A lookup runs no code, so a remote’s declarations need no permission. Asset naming (amd64 or x86_64, darwin or macos, with or without a v) is the manifest’s to spell; batfiles does not guess it.

When an asset’s name holds no version, no variable is needed: https://github.com/OWNER/REPO/releases/latest/download/ASSET is a plain URL that always names the latest release’s asset.

What a download built from the tag does on a new release depends on what fetches it. A file or archive remote refetches when its resolved URL changes, so the next sync after a release downloads it. A seed, such as fetch-archive, keeps what it first installed until --refresh-content. A fixed sha256 matches one release, and a templated one can select a known digest for each tag; see what is not sandboxed.

The github-url field

github-url names the host a declaration asks: GitHub Enterprise Server, for example. Declarations may mix hosts. No environment variable changes the default.

[vars.internal_cli_tag]
github-release = "platform/cli"
github-url = "${env.GHE_URL}"

It is a template that reads only env and facts, which exist before any variable resolves. A reference to a variable, bare or through vars, is a load error: “github-url may read env and facts, not variables”. In an included manifest, reading env needs the remote’s allow-env-templates, as any template there does; a literal URL needs nothing.

The value must be an http:// or https:// URL naming a host, then optionally : and a decimal port from 1 to 65535, then optionally a path; one trailing / is removed. The host is a name of ASCII letters, digits, -, ., and _, which includes an IPv4 address, or an IPv6 address in brackets. The release path is appended to it, so a query or fragment is refused, as are credentials before an @: a lookup sends none, and the resolved URL is recorded in the cache. A literal is checked when the manifest loads; a templated value is checked each time the declaration resolves, including under vars list --no-refresh, because the resolved URL is part of what a cache entry records.

A github-url that fails to evaluate or resolves to an invalid URL fails the lookup rather than the run: the variable reads as empty, with a warning, and no cached value is used, since there is no URL to match an entry against. An unset environment variable is the empty string, so ${env.GHE_URL} on a machine without it warns rather than stopping a sync. Errors name the field and quote it as written, unless it holds an @ and so could hold credentials; they never quote the resolved value.

Duration values

cache, command-timeout, and timeout are strings holding a number and a unit, optionally repeated: 30s, 5m, 1h, 1d, 1w, 1h 30m. Units may be abbreviated or spelled out (2 hrs, 90 minutes), separated by whitespace or commas, and sub-second units are accepted (500ms). A clock-style HH:MM:SS form is accepted too (01:30:00). A fraction is allowed on the last unit written, and only for hours or smaller: 1.5h and 1m 30.5s are durations, 1.5d and 1.5h 30m are not. ISO 8601 durations such as PT1H are not.

A day is exactly 24 hours and a week exactly 7 days. Months and years have no fixed length, so they are not durations. A negative duration, written -1h or 1h ago, is invalid. Zero is a valid cache, where it means a value is never fresh, and an invalid command-timeout or timeout, which would stop every capture before it could answer.

Conditions

Actions, clone-list entries, remotes, and default-disabled candidates may carry one condition:

FieldThe record applies when
whenTrue
unlessFalse

Writing both is a load error.

[[actions]]
type = "symlink"
id = "gitconfig-work"
source = "git/gitconfig.work"
dest = "~/.gitconfig"
when = "work && facts.os == 'macos'"

The expression

Values use Simple Expressions. Every expression is parsed during document loading, even if never evaluated; a syntax error names the file, the record or clone-list line, and the position in the expression.

User variables are string-valued bare identifiers. Reserved namespaces facts, env, and vars also return strings. Use member syntax for identifier-compatible keys (facts.os) or index syntax for any key (env["XDG_CURRENT_DESKTOP"]).

Identifiers

LookupDeclared/setMissing
Bare user variableIts string value, including emptyEvaluation error
vars.<name>Same user valueEmpty string
facts.<key>, env.<key>Host valueEmpty string

Use a bare identifier to catch undeclared names, or vars for optional ones:

when = "work"                     # error if undeclared
when = "vars.work"                # false if undeclared
when = "vars.work || vars.school"

All variable names allow member syntax; index syntax is also accepted. Precedence chooses each user value.

Truthiness

The condition result and every &&, ||, and ! operand use this table:

ValueBoolean interpretation
BooleanItself
NumberFalse at zero, otherwise true
"true", "1", "yes", "on"True
"false", "0", "no", "off", ""False
Anything elseEvaluation error

Comparison and + retain the expression language’s rules. For example, profile = "personal" needs a comparison, not when = "profile".

When a condition cannot be evaluated

Undeclared bare identifiers, invalid truthiness, arithmetic overflow, and other evaluation failures close the gate for both when and unless. The record is skipped, with a warning that permits continuation. Diagnostics include the condition and remedy but never the offending value.

A failed dynamic declaration with no cached value is still declared and reads as the empty string; it does not cause an undeclared-name error. Selection determines when action conditions are evaluated or waived. Bootstrap conditions are evaluated only when their candidates are offered.

Templates

A template string is a field in which each ${...} is an expression whose value is written into the text:

[remotes.tool]
type = "file"
url = "https://downloads.example.com/tool/${facts.os}-${facts.arch}/tool.gz"
decompress = true

$${ writes a literal ${; any other $ is ordinary text.

Template fields

RecordTemplate fields
git remoteurl, ref
file and archive remotesurl, sha256
fetch-file, fetch-archivesource, dest, sha256
git-clonesource, dest, ref
symlink, copy, create-dirdest
symlink-dir, copy-dir, git-clone-listdest-dir
runcommand: the shell string, or each list element; cwd; each env value
github-release variablegithub-url, which reads only env and facts

No other field is a template.

When a template is evaluated

A template reads what a condition on the same record reads. Remotes and leaf actions use the leaf’s variables; an inclusion’s actions use the inclusion’s. A template in an included manifest reads env only with its remote’s permission. Each ${...} must give a string, number, or boolean.

Templates are parsed when the manifest loads, so a syntax error is a load error naming the record and field. Each is evaluated once, when needed, including in dry runs:

  • a github-url each time its declaration resolves, against env and facts alone; see the field;
  • a remote’s when sync or clone materializes it;
  • an action’s when the action is dispatched, including by apply-action; a run action’s only when its trigger fires.

Output shows resolved values, except a run action’s command, which is shown as written. A literal value is checked when the manifest loads; a templated one is checked by the same rule once it resolves.

When a template cannot be used

A template that fails to evaluate, or resolves to an invalid value, fails its record instead of skipping it as a condition does: an execution failure for an action, a materialization failure for a remote. A github-url is the exception: it fails its lookup, and the variable reads as empty.

error: create-dir action 2: dest "~/${nope}" cannot be evaluated at character 3: `nope` is not declared. ...

Errors never show a variable’s value or anything computed from it, including an invalid resolved value.

Default-disabled bootstrap entries

[default-disabled] proposes initial disables for a fresh machine:

[[default-disabled.actions]]
id = "p10k"

[[default-disabled.groups]]
group = "gui"
unless = "facts.os == 'macos'"

Action entry

FieldTypeRequiredDescription
idaddressyesAction or clone-list entry to disable
when / unlessconditionnoOffer the candidate only when its gate passes; at most one

Group entry

FieldTypeRequiredDescription
groupaddressyesGroup to disable
when / unlessconditionnoOffer the candidate only when its gate passes; at most one

Records are closed and address syntax is validated, but names are never resolved. Candidates may name included content or actions a later repository revision introduces.

Only the leaf’s candidates are considered, by clone or sync --bootstrap. Bootstrap adoption defines eligibility and persistence; precedence defines overrides. Conditions are always parsed at manifest load, and evaluated only when candidates are offered during bootstrap. Other commands ignore the section.