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

Share configuration between repositories

Keep reusable configuration in one repository and choose how each machine uses it from your own dotfiles repository. Your own checkout is called the leaf; a declared remote supplies additional content.

Use a remote’s files

Add a Git remote near the top of batfiles.toml, before [[actions]]:

[remotes.shared]
type = "git"
url = "https://git.example.com/team/dotfiles.git"
ref = "main"

Replace the URL with your shared repository. Its ordinary files can be used without a manifest:

[[actions]]
type = "copy"
id = "shared-editor"
source = "@shared/files/editor.toml"
dest = "~/.config/my-editor/settings.toml"

sync fetches the remote into remotes/shared/ before applying actions. That generated directory belongs in .gitignore. Your leaf still chooses what to install and where. As a copy, this example keeps an existing destination; refresh it deliberately when you want updated starting content.

Include the remote’s actions

If the shared repository has its own batfiles.toml, you can include its actions instead of declaring copies yourself:

[[actions]]
type = "include-remote"
id = "team"
remote = "shared"
install-groups = ["editor"]

This includes actions in the shared manifest’s editor group, at this position in your manifest. Omit install-groups to include all its actions. Review the included repository: it can choose destinations and affect your files.

Use sync to fetch the remote and run the selected actions. Until sync has fetched it, a dry run cannot list the included actions and reports a partial plan, and apply commands cannot run them.

Inclusion is one level deep. Nested inclusions are warned about and dropped; the included manifest’s own remotes are ignored. See the inclusion reference.

Address included actions

If the shared manifest has an action with id = "settings", the inclusion above exposes it as team.settings:

batfiles apply-action --id team.settings
batfiles disable-action team.settings
batfiles apply-group --group team.editor

The prefix is the inclusion’s id, not the remote’s name. Naming an included action does not bypass the inclusion: if team is disabled or its condition is false the command fails, and an action outside install-groups applies nothing. See addresses.

Keep a work remote off personal machines

Gate both the remote and its inclusion:

[vars]
work = "false"

[remotes.shared]
type = "git"
url = "https://git.example.com/team/dotfiles.git"
when = "work"

[[actions]]
type = "include-remote"
id = "team"
remote = "shared"
when = "work"

Set batfiles vars set work true on a work machine. Disabling only the inclusion does not prevent sync from contacting an otherwise eligible remote; the remote’s own condition controls that.

An inclusion can pass static values through vars = { profile = "work" }. Included dynamic commands are disabled unless the leaf explicitly sets allow-dynamic-vars = true on the Git remote; included github-release lookups run no code and need no permission. See inclusion variables.