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

Install batfiles

Batfiles runs on Linux, macOS, and Windows. Install Git if you will clone or update repositories. On Windows, use PowerShell 7 (pwsh). Symlink actions require Unix; directory, copy, download, and Git actions also work on Windows.

Install the binary

On Linux or macOS:

curl -fsSL https://batfiles.dev/install.sh | sh

On Windows, in PowerShell 7:

irm https://batfiles.dev/install.ps1 | iex

The installer verifies downloads against the release’s checksums. It installs to ~/.local/bin on Unix or %LOCALAPPDATA%\Programs\batfiles on Windows, unless it finds a usable batfiles already installed. It prints the location; ensure that directory is on your PATH. It leaves shell startup files alone.

Open a shell with the updated PATH and check:

batfiles version

To create your own dotfiles repository, continue with Your first repository.

Use an existing dotfiles repository

Review the repository before running it: actions choose installation paths, and dynamic variables can run programs with your permissions. See the trust model.

Replace the example URL with your own repository:

batfiles clone https://github.com/me/dotfiles

This clones into ~/dotfiles, adopts the repository’s bootstrap choices, and installs its selected actions. The directory must not already exist, even if it is empty. clone does not support --dry-run; to inspect an installation first, clone with Git and preview from the checkout:

git clone https://github.com/me/dotfiles dotfiles
cd dotfiles
batfiles sync --bootstrap --dry-run
batfiles sync --bootstrap

A dry run leaves installation content alone, but can execute dynamic-variable commands and write bookkeeping. Missing remotes can also make its plan partial. See dry-run behavior.

If the checkout includes the installers generated by batfiles init, running ./install.sh on Unix or .\install.ps1 in PowerShell gets batfiles if needed and bootstraps that checkout. See checkout stubs.

Install and clone in one step

On Linux or macOS:

curl -fsSL https://batfiles.dev/install.sh | sh -s -- clone https://github.com/me/dotfiles

On Windows, in PowerShell 7:

& ([scriptblock]::Create((irm https://batfiles.dev/install.ps1))) clone https://github.com/me/dotfiles

For a different checkout location, add --batfiles-dir and its path to the clone command. For a particular branch, tag, or commit, add --ref.

Update batfiles

batfiles update --check
batfiles update

The first command reports the running and available versions. The second installs the latest stable release. Updates happen only when requested; rerunning the installer can reuse an existing binary without upgrading it.

See the installer reference for version pins, alternate binary locations, and self-hosted releases, and the update reference for update behavior.