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

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"]
FieldTypeRequiredDescription
remoteIDyesA git remote this same manifest declares.
install-actionsID or list of IDsnoTake only the actions named.
install-groupsID or list of IDsnoTake only the actions naming these groups.
exclude-actionsID or list of IDsnoLeave out the actions named.
exclude-groupsID or list of IDsnoLeave out the actions naming these groups.
varsmap of name to stringnoValues 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.