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

Configure a machine

Keep one dotfiles repository and select different content for each machine. Use groups for manual choices and variables with conditions for reusable rules.

Declare a default and a condition

Add this [vars] table at the top of batfiles.toml, before any [[actions]]:

[vars]
work = "false"

Add an action that should run only on a work machine:

[[actions]]
type = "create-dir"
id = "work-notes"
group = "work"
dest = "~/work-notes"
when = "work"

Variables are strings, including "true" and "false". They control conditions and templates.

Choose locally or for one run

batfiles vars set work true
batfiles sync --dry-run
batfiles sync

The value is saved on this machine, without editing the repository. To override it for one run:

batfiles sync --var work=false

To remove the machine override and return to the repository’s default:

batfiles vars unset work

The condition prevents future execution; it does not remove ~/work-notes after that directory has been created. Use sync --dry-run to check conditions; explicitly naming an action with apply-action bypasses its own condition.

Inspect values

batfiles vars list --no-refresh
batfiles vars list --machine-only
batfiles vars get work

The first lists effective leaf variables and their origins without running dynamic commands. The second lists only stored machine values. vars get reads a stored machine value, not the effective value, and fails if none is stored.

For ordinary leaf variables, command-line overrides win over environment values, which win over machine values, which win over manifest defaults. See the complete precedence, including inclusion-specific values.

Select by operating system

Conditions can inspect built-in facts:

[[actions]]
type = "create-dir"
id = "linux-cache"
dest = "~/.cache/my-tools"
when = "facts.os == 'linux'"

Other OS values include macos and windows. Use unless for the inverse condition; an action cannot declare both. For named profiles, compare strings: when = "profile == 'work'", with a declared profile variable. See conditions and host facts.

Write a value into a path

Destinations, download URLs, and Git refs can be templates, with ${...} around an expression:

[[actions]]
type = "create-dir"
id = "os-cache"
dest = "~/.cache/my-tools-${facts.os}"

On Linux this creates ~/.cache/my-tools-linux. A template that cannot be resolved fails its action. Write $${ for a literal ${. See templates.

Set bootstrap defaults

A repository can initially disable a group until a user opts into it:

[[default-disabled.groups]]
group = "work"

clone and sync --bootstrap offer these defaults when no disabled.toml exists. To bootstrap while opting into the work group:

batfiles sync --bootstrap --enable-group work

Enabling a group does not make a false action condition true; set work as well if using the earlier example. Defaults do not reset existing machine choices. See bootstrap defaults.

Discover values with commands

Dynamic variables capture a command’s output or success and cache it. Use them when a static machine choice is not enough. Their commands run with your permissions, including during dry-run. Included repositories need explicit permission to run them. To track a project’s latest GitHub release instead, see install from GitHub releases.

Use batfiles vars refresh to refresh the declarations in play, or batfiles sync --refresh-vars to refresh those evaluated by that run.