Installation reference
Hosted installer
Invocation
curl -fsSL <base>/latest/download/install.sh | sh
curl -fsSL <base>/latest/download/install.sh | sh -s -- clone https://github.com/me/dotfiles
The official installers are also served from https://batfiles.dev/; see
GitHub Pages.
With no arguments it ensures a binary and exits. With arguments it ensures a
binary and then execs it with those arguments, which makes the second form
the one-command bootstrap of a new machine: clone does
the rest. When its standard input is not a terminal, as when it is piped into
sh, and the process has a controlling terminal, batfiles gets /dev/tty as
standard input, so a command such as clone --interactive can still ask.
Inputs, all optional:
| Variable | Meaning |
|---|---|
BATFILES_BASE | The release base. Defaults to the stamped base. |
BATFILES_VERSION | A release to fetch, a version with or without a leading v. Empty or latest means the latest release. |
BATFILES_BIN | The path of the one batfiles to use, or to install. A relative path is taken from the working directory. Unset, the installer searches as resolving a binary describes. |
Because the script is piped, a variable reaches it as curl … | BATFILES_BASE=… sh. latest never names a pre-release, so installing one takes
BATFILES_VERSION.
Resolving a binary
With BATFILES_BIN set, it is the only candidate, and where a download goes.
Otherwise the candidates, in order, are the batfiles found on PATH and
$HOME/.local/bin/batfiles, and a download goes to the second. Either way, the
last candidate is the install location.
- No version requested: the first candidate that runs is used, and nothing
is downloaded. Upgrading an existing binary is what
updateis for; an installer run with no arguments reports which binary it found and suggestsbatfiles update. BATFILES_VERSIONset: it names exactly what is downloaded, and is a floor for what is accepted. The first candidate whose version is at least the requested one is used. If none is, the requested release is installed at the install location, replacing an older batfiles there, and used by its absolute path. A candidate onPATHthat was passed over is named in a warning and never modified.
Because the pin is a floor, a repository that needs 1.4 accepts 1.5 without downgrading it, while a machine holding 1.2 gets 1.4.
A candidate’s version is read from batfiles version, whose output (batfiles <version>) is a frozen contract, and
versions compare as versions order. A candidate that fails to run,
prints something else, or reports a version outside the grammar is passed over,
and the installer says so.
Installing
The installer only ever writes in the directory holding the install location, creating it if needed. It never replaces something there that is not batfiles: a file at the install location that does not report a batfiles version, or a directory, stops the installer before it downloads anything, naming the path. Otherwise:
- Map
uname -sanduname -mto a target:Linuxto musl,Darwinto Apple;x86_64/amd64andaarch64/arm64. An x86_64 shell on Apple silicon (Rosetta, reported bysysctl hw.optional.arm64) gets the aarch64 binary. An unmapped platform fails, naming what was detected. - Choose the release: the requested version, or else the one
<base>/latest/download/VERSIONnames, read once so that a release published meanwhile cannot mix two. When that cannot be read, the installer suggests requesting a pre-release, since the base may have no stable release yet. Everything else comes from<base>/download/v<version>/. - Download the binary to a temporary file beside the install location, and
SHA256SUMSbeside it, withcurl, falling back towget. - Verify the digest with
sha256sum, falling back toshasum -a 256. With neither available, or on a mismatch, stop without installing anything. - Make it executable and run its
version, which catches a binary the machine cannot execute. It must report the chosen release. - Rename it to the install location, and report the version and the path.
Any failure removes the temporary files and leaves the directory as it was, apart from creating it.
The installer never edits a shell startup file, since the first sync usually
installs the user’s own. When the install directory is not on PATH, it says so
and continues; it runs batfiles by absolute path, so the bootstrap does not
depend on PATH.
Script conventions
- POSIX
sh, checked byshellcheckintask lintand run underdashin the pristine-machine container. - The whole body is a function called on the last line, so a truncated download runs nothing.
- The installer’s own messages go to standard error, so a command it
execs owns standard output. They are ASCII, like everything else batfiles prints. - Its own failures exit 1. Once it
execs batfiles, the exit status is batfiles’.
On Windows
install.ps1 is the same installer for PowerShell 7 or later:
irm <base>/latest/download/install.ps1 | iex
& ([scriptblock]::Create((irm <base>/latest/download/install.ps1))) clone https://github.com/me/dotfiles
The first form ensures a binary; the second ensures one and then runs it with
the arguments after the scriptblock. It takes the same three
variables, set beforehand as $env:BATFILES_VERSION = '1.2.3',
and differs from install.sh only where Windows does:
- Candidates: the
batfilesthatGet-Commandfinds onPATH, then$env:LOCALAPPDATA\Programs\batfiles\batfiles.exe, the install location.BATFILES_BINreplaces both, as it does on Unix, and the same floor applies toBATFILES_VERSION. - Target:
PROCESSOR_ARCHITECTURE, orPROCESSOR_ARCHITEW6432in a 32-bit PowerShell on a 64-bit Windows, chooses it.AMD64andARM64both getx86_64-pc-windows-msvc, which Windows on ARM runs under emulation; any other architecture fails, naming it. On Linux or macOS it refuses, naminginstall.sh. - Downloads use
Invoke-WebRequest, andGet-FileHashverifies the digest. The staged file’s name ends in.exe, so that Windows will run itsversion. PATHis never changed. When the install directory is not on it, the installer prints the[Environment]::SetEnvironmentVariablecommand that would add it for the current user.- Failures are terminating errors rather than
exit, which insideirm | iexwould close the session it ran in; underpwsh -Commandor-Filethe status is 1. Batfiles’ own status is left in$LASTEXITCODE. - Windows PowerShell 5.1, which every Windows has, is refused with the
winget install Microsoft.PowerShellthat provides PowerShell 7. The script stays parseable by 5.1 so that it can say so.
It is ASCII, its body a function called on the last line, and its messages go
to standard error with an install.ps1: prefix. task lint runs
PSScriptAnalyzer over it where pwsh is installed.
Leaf stub
init writes install.sh, executable, and its Windows
counterpart install.ps1, as the last entries of its
skeleton; init --stubs adds either to a repository that
lacks it. They are for a machine that already has a checkout:
git clone https://github.com/me/dotfiles ~/dotfiles && ~/dotfiles/install.sh
A new machine with no checkout uses the hosted installer’s clone one-liner
instead.
The stub’s first line is #!/bin/sh, its second the marker # batfiles-stub 1,
and then two settings; the rest is fixed text, its body a function called on
the last line like the installer’s:
BATFILES_BASE=${BATFILES_BASE:-'<base>'}
BATFILES_VERSION=${BATFILES_VERSION:-}
init fills in <base> from the release base, so a
self-hoster runs BATFILES_BASE=https://mysite/batfiles batfiles init, or edits
the line afterwards. Setting BATFILES_VERSION pins the repository to a release
at least that new. BATFILES_BIN chooses the batfiles to use or install, as it
does for the installer.
Run, the stub:
- Finds its own directory from
$0, and refuses — printing thecloneone-liner — when$0is not a file or there is nobatfiles.tomlbeside it. That is what happens when the stub is piped intoshinstead of run from a checkout. - Looks for a binary among the installer’s
candidates, taking the first that reports
batfiles <version>in the version grammar.- No pin, and one found: it is used, and nothing touches the network.
- Otherwise — nothing found, or a pin, whose comparison the stub leaves
to the installer — it fetches the hosted installer, from
<base>/download/v<version>/when pinned so the installer matches the binary and fromlatestotherwise, pipes it intoshwith its settings exported and thesynccommand below as its arguments, and exits with its status. The installer resolves, installs if it must, andexecs. - The installer cannot be fetched: a pinned stub that found a binary uses it, warning that the pin went unchecked; otherwise it fails.
execsbatfiles sync --bootstrap --batfiles-dir <its directory>with its own arguments appended, so./install.sh --dry-runworks, a checkout outside the default location is still the one synchronized, and./install.sh --disable-group guistarts the machine asclonewould. Seesync --bootstrap.
An installed binary makes an unpinned stub work offline. The stub carries no
version comparison, so nothing about version ordering is frozen into
repositories; it stays in the hosted installer, which changes with each
release. The parts the stub does share with the installer — the version
grammar, reading a candidate’s version, and the candidates themselves — are the
same text in both, which tests/dist checks.
The Windows stub
install.ps1 does the same for PowerShell 7 or later, from a checkout:
git clone https://github.com/me/dotfiles $HOME\dotfiles; & $HOME\dotfiles\install.ps1
Its first line is #Requires -Version 7.0, its second the same marker, and
then its two settings:
$BatfilesBase = if ($env:BATFILES_BASE) { $env:BATFILES_BASE } else { '<base>' }
$BatfilesVersion = if ($env:BATFILES_VERSION) { $env:BATFILES_VERSION } else { '' }
A pin is written in the second line’s ''. Run, it follows the steps above with
the Windows installer’s candidates: it finds its directory from
$PSScriptRoot, refusing with the clone one-liner when it is not run from a
file beside a batfiles.toml; fetches install.ps1 and runs it as a
scriptblock with the sync command as its arguments; and exits with batfiles’
status. The text it shares with the Windows installer is checked the same way.
A machine whose execution policy refuses local scripts runs it as pwsh -ExecutionPolicy Bypass -File .\install.ps1.
Stability
The stub depends on five contracts, and each is frozen:
- the release tree layout;
- the installer’s input variables, and its running its arguments as a batfiles command;
- the
batfiles <version>form ofbatfiles version, in the version grammar; - the binary candidates and their order, on each platform; and
sync --bootstrap --batfiles-dir, with the enable and disable options.
Nothing rewrites a stub in a repository: sync writes nothing in the leaf but
remotes/. init, with or without --stubs,
writes only a missing stub, and warns about an existing one that lacks the
marker line. The marker lets a future stub format be recognized.