Your first repository
Create a repository, declare one file to install, and preview the result. This example works on Linux, macOS, and Windows. It installs a demonstration file under your home directory without changing any application’s configuration.
You need batfiles on your PATH and Git installed.
Create the repository
In a directory where dotfiles-demo does not already exist:
mkdir dotfiles-demo
cd dotfiles-demo
batfiles init
These commands also work in PowerShell 7. Stay in this directory for the rest
of the tutorial. init creates a starter manifest, files/, bin/, an
appropriate .gitignore, and checkout installers, and initializes Git if needed.
The starter manifest installs nothing.
Declare a file
Create files/editor.toml in your editor with this content:
theme = "dark"
Replace the commented starter batfiles.toml with:
[[actions]]
type = "copy"
id = "editor"
group = "editor"
source = "files/editor.toml"
dest = "~/.config/batfiles-demo/editor.toml"
source is relative to this repository. ~ in dest names your destination
home. An action’s id lets you run it individually; group lets you select
several related actions together.
copy installs a starting file, called a seed. Later runs keep any existing
destination, so you can edit it locally. To keep a live connection to the file
in Git instead, Unix users can choose a symlink.
Preview and apply
batfiles sync --dry-run
batfiles sync
batfiles sync -v
If the destination is vacant, the preview reports would copy; the real run
reports copied and creates any missing parent directories. Open
~/.config/batfiles-demo/editor.toml to see the installed content. On Windows,
that path is inside your user profile directory.
The verbose run reports that the destination is kept. An ordinary repeat of
batfiles sync is silent when nothing changes. If the file was already there
before the tutorial, this copy action keeps it too.
Dry-run leaves installed content alone; see what it can still do.
Change the starting content
Change files/editor.toml to theme = "light". Running sync again keeps the
installed file. To deliberately replace it with the changed starting content:
batfiles apply-action --id editor --refresh-content
When content differs, the default policy backs up the existing destination
beside it before installing the replacement. --interactive asks how to handle
that conflict; --no-overwrite keeps it. See refreshing seeds.
Use a live link on Unix
For real configuration that should always use the repository’s copy, use
symlink instead of copy. For example, after adding your shell configuration
at files/zshrc:
[[actions]]
type = "symlink"
id = "zshrc"
group = "shell"
source = "files/zshrc"
dest = "~/.zshrc"
Preview before applying. An unmanaged file in the way is backed up by default;
use --no-overwrite to skip conflicts. Once linked, editing ~/.zshrc
edits files/zshrc in the repository. Symlink actions fail on Windows. See
replacement rules for other node types.
Keep the repository in Git
git add batfiles.toml .gitignore files bin install.sh install.ps1
git commit -m "Add my dotfiles"
Push it to your preferred Git host when ready. The checkout installers let you bootstrap another machine. Keep credentials and other secrets out of the repository.
Next: Everyday use explains selective runs, and Configure a machine introduces machine-specific choices.