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

Manage files and downloads

Choose an action based on how the installed content should behave after the first run. All actions run in declaration order. Give actions an id when you want to select them individually.

Choose an action

NeedActionOn later runs
Use the repository’s live file or directorysymlinkKeep or correct the link; Unix only
Link each direct child into an existing directorysymlink-dirManage child links; Unix only
Ensure a directory existscreate-dirKeep an existing directory
Install an editable starting file or treecopyKeep an occupied destination
Seed each direct child into a directorycopy-dirKeep occupied child destinations
Download one filefetch-fileKeep an occupied destination
Download and unpack a treefetch-archiveKeep an occupied destination
Maintain a Git checkoutgit-cloneUpdate conservatively
Maintain a list of Git checkoutsgit-clone-listProcess each entry
Run another repository’s actionsinclude-remoteSee composition
Run a commandrunAs its trigger says

Copies and downloads are seeds: after installation, the local content is allowed to diverge. A seed’s ordinary run does not compare or overwrite it.

Seed an editable configuration

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

Add the source file to your repository, then preview and apply:

batfiles apply-action --id editor --dry-run
batfiles apply-action --id editor

For a whole directory tree, copy uses that directory as source. For separate children merged into a destination directory, use copy-dir with source-dir. The entry filters select children or archive entries.

Download content

Replace this illustrative URL with a source you trust:

[[actions]]
type = "fetch-file"
id = "theme"
source = "https://downloads.example.com/editor/theme.toml"
dest = "~/.config/my-editor/theme.toml"

A template can fetch each machine’s build:

[[actions]]
type = "fetch-file"
id = "tool"
source = "https://downloads.example.com/tool/tool-${facts.os}-${facts.arch}.gz"
dest = "~/.local/bin/tool"
decompress = true
executable = true

To follow a project’s GitHub releases instead of a fixed URL, see install from GitHub releases.

Add sha256 with the expected 64-digit digest to verify the downloaded bytes. Without a digest, identity depends on the chosen source and transport. Use fetch-archive to unpack an archive, and decompress = true on fetch-file to expand a gzip or bzip2 stream into a single file. The action references list supported formats and options; archive safety defines permitted entries.

Refresh deliberately

batfiles apply-action --id editor --refresh-content

This rebuilds the seed and compares it with the installed content. If different, the normal conflict policy applies: back up and replace by default, ask with --interactive, or leave it with --no-overwrite. A dry-run refresh does not build or download the content, so it cannot tell whether the result would differ.

The three refresh options affect different things:

OptionRefreshes
--refresh-contentInstalled copy and download seeds
sync --refresh-remotesFile and archive sources under remotes/
--refresh-varsDynamic variables evaluated for that run

See seed refresh, remotes, and dynamic captures.

Maintain a Git checkout

[[actions]]
type = "git-clone"
id = "tools"
source = "https://git.example.com/me/tools.git"
dest = "~/src/tools"
ref = "main"

Batfiles uses your Git executable, credentials, and SSH configuration. Existing checkouts with a suitable branch update by fast-forward; local modifications and divergence are preserved rather than reset. A warning can therefore mean the checkout was kept. See Git updates.

For several repositories, use a clone list. Some per-entry failures warn and continue, so inspect warnings even when a clone-list command exits successfully.

Run a command after an install

A program often needs a command run once it is installed, and again whenever it is upgraded. A run action following the install does that:

[[actions]]
type = "fetch-file"
id = "mise"
source = "https://downloads.example.com/mise/mise-${facts.os}-${facts.arch}"
dest = "~/.local/bin/mise"
executable = true

[[actions]]
type = "run"
id = "mise-install"
command = ["~/.local/bin/mise", "install"]
trigger = { after = "mise" }

The command runs on the first sync, and after that only when the download is installed or replaced, including by --refresh-content. A leading ~/ in the program reaches it even before ~/.local/bin is on PATH. Other triggers run a command every time, only at bootstrap, once, or on an interval. Batfiles records each success in runs.toml; use batfiles apply-action --id mise-install to run it again regardless.