include-remote
Takes the actions another repository declares into this one, at this position in the list.
[[actions]]
type = "include-remote"
id = "corp"
remote = "corporate"
install-groups = ["shell"]
exclude-actions = ["p10k"]
| Field | Type | Required | Description |
|---|---|---|---|
remote | ID | yes | A git remote this same manifest declares. |
install-actions | ID or list of IDs | no | Take only the actions named. |
install-groups | ID or list of IDs | no | Take only the actions naming these groups. |
exclude-actions | ID or list of IDs | no | Leave out the actions named. |
exclude-groups | ID or list of IDs | no | Leave out the actions naming these groups. |
vars | map of name to string | no | Values for what it takes. |
remote must name a Git remote in the same manifest; undeclared, file, or
archive remotes are load errors. Multiple inclusions of one remote share its
materialization.
The inclusion reads remotes/<remote>/batfiles.toml and splices its actions
into this position, in their declaration order. Included repository paths, including clone-list
sources, resolve from that materialization. A present materialization with no
manifest fails. Expansion finishes before action execution; a malformed included
manifest therefore prevents installation. An absent materialization follows
plan completeness.
Inclusion is one level deep, subject to the restrictions below. A closed inclusion or remote condition contributes nothing, leaving the plan complete. Selection defines when an inclusion is opened and how its group or exclusion reaches its contents.
An inclusion’s id qualifies contributed addresses,
such as corp.zshrc; it need not match the remote ID. Without an ID, its
contents still run but cannot be addressed. Reports identify it by position
and remote, and attribute contributed records to it:
include-remote action 2 of remote `corporate`
symlink zshrc (group shell, from include-remote action 2 of remote `corporate`)
Named inclusions use include-remote `corp` in diagnostics. The same name
identifies filter warnings and variable blocks.
Selecting part of a remote
Filter values are unqualified IDs from the included manifest, as one string
or a list. With no filters, take all actions. An omitted allow-list differs
from an empty one: install-actions = [] takes nothing.
At most one of install-actions, install-groups, and exclude-groups may be
present. exclude-actions may stand alone or accompany either group filter,
but not install-actions. Other combinations are load errors.
Allow-lists omit records lacking the relevant ID or group; deny-lists retain them. Action and group filters use separate namespaces. A name matching nothing warns, naming the inclusion, filter, and remote, but does not fail the run.
Filtered-out actions retain their addresses for selection diagnostics. Filters are honored by every command; other exclusions can still apply to selected records. See selection.
Variables for one inclusion
[[actions]]
type = "include-remote"
id = "corp"
remote = "corporate"
vars = { profile = "work" }
vars maps variable names to strings, validated at load time.
Dynamic declarations are not accepted here. Omitted and empty maps both
provide no overrides. These values apply to contributed records, including
clone-list entries; see scope and precedence.
Variables an included remote declares
An included manifest may declare its own static or dynamic [vars], using the
same schema as the leaf. They are the lowest layer of
that inclusion’s scope, so the leaf and
this machine can override them without knowing they exist. They never decide the
inclusion’s own condition or the remote’s, which use the leaf scope.
Remote command declarations require allow-dynamic-vars;
without it they declare nothing. Remote
github-release declarations
need no permission: a lookup runs no code, so the remote supplies its value as
it could a static one. Dynamic declarations share one capture and cache entry per
remote variable across inclusions; see
cache evaluation.
Use -vv to inspect inclusion variable blocks.
Templates and the host environment
A template in a contributed record could send a
host secret to a URL of the remote author’s choosing, as in
source = "https://example.com/${env.TOKEN}". So it reads
env only if the leaf sets
allow-env-templates on the remote:
[remotes.corporate]
type = "git"
url = "git@git.example.com:it/dotfiles.git"
allow-env-templates = true
Without it, a lookup in env fails the record. A github-release declaration’s
github-url is a template too, under
the same permission: without it, reading env there fails the lookup, and the
variable reads as empty with a warning; a literal URL works either way.
Conditions and leaf templates need no permission. The permission applies only to a checkout of the repository
the remote’s url names; see
permissions follow the origin.
Commands
A contributed run action runs its command
only if the leaf sets allow-commands on the remote.
Without it, the action is excluded with a warning naming the remote and the
field, and apply-action naming it fails. A contributed run action whose
trigger keeps state needs this inclusion to have an id, which its address in
runs.toml begins with. An included run action cannot follow a remote.
What an included action may not write
Included repository paths must refer to the declaring repository’s own tree.
Remote references (@core/files/zshrc or the structured equivalent) are
refused even if that manifest declares the remote.
Nested include-remote records instead warn and are dropped; other actions
are contributed normally. The nested remote need not exist, since it will
never be resolved:
warning: not included: include-remote corp.shared; an included repository does not reach further repositories
An included manifest’s own [remotes]
The map is read for schema shape, then ignored. Unknown types and fields still fail. Value validation is skipped: invalid URLs, digests, templates, conditions, empty refs, and case-colliding remote keys do not fail a run that includes the manifest. Nothing materializes these remotes or allows an included action to source them.
A nonempty map warns once per inclusion, naming all ignored records; an empty one is silent.
See common action fields for id, group, and
conditions.