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

Batfiles command-line surface

Commands, accepted options, output, and exit statuses. Every command and option below is implemented; unrecognized commands and options are usage errors, as exit statuses describes.

Command overview

batfiles [global-options] <command> [command-options]

Global options may appear before or after the command name.

CommandPurpose
initCreate a repository skeleton or add missing installer stubs
versionPrint the installed version
updateCheck for or install a binary release
cloneClone a leaf repository, adopt bootstrap choices, and sync
syncMaterialize remotes and execute selected actions
apply-action, apply-groupExecute a named part of the manifest
enable-action, disable-action, enable-group, disable-groupPersist machine-local selections
vars set, get, unsetManage machine-local variables
vars listInspect effective values and origins
vars refreshRefresh cached dynamic variables

Shared reference: execution options, output, selection, dry-run, partial plans, failures.

Global options

These options are accepted by every command, although a command only uses the locations relevant to its work. init, for example, operates on the current directory and does not use any selected roots.

OptionPurpose
-v, --verboseIncrease diagnostic detail. May be repeated, such as -vv.
-q, --quietSuppress informational output and leave errors or explicitly requested data. Mutually exclusive with --verbose.
--color <auto|always|never>Control colored output. Defaults to auto; see color selection.
--batfiles-dir <path>Select the leaf repository. See location selection for its fallbacks.
--home-dir <path>Select the destination home directory. Defaults to the current user’s home directory.
--config-dir <path>Select the directory containing vars.toml and disabled.toml. Defaults to the XDG config location.
--cache-dir <path>Select the directory containing dynamic-vars.toml and the run lock. Defaults to the XDG cache location.
--state-dir <path>Select the directory containing runs.toml. Defaults to the XDG state location.

-v prints the roots the command resolves, unchanged destinations, and action headings and exclusions. -vv also prints the effective variables. See location selection for which roots each command uses and their precedence, and output streams for quiet mode.

Shared action execution options

These options are accepted by every command that executes actions: sync, apply-action, apply-group, and clone, which forwards them to its follow-up synchronization.

OptionPurpose
--var <key=value>Set a one-shot variable. Repeatable; the last value for a key wins.
--refresh-varsCapture every dynamic variable again, even where its cached value is fresh.
--refresh-contentInstall copies and fetched seeds again over what is at their destinations.
--no-overwriteSkip anything in a destination’s way instead of backing it up and replacing it.
--interactiveAsk at each destination in the way: back up and replace, overwrite, or skip.

A --var key must be a variable name; an invalid key is a usage error before roots are resolved or files read. An empty value, such as --var profile=, overrides lower layers. See variable precedence.

--refresh-vars forces captures for the declarations this run evaluates; see cache evaluation.

Conflicts and backups defines destination handling and its output. --no-overwrite and --interactive are mutually exclusive, and --interactive cannot accompany --dry-run. --refresh-content affects only copy, copy-dir, fetch-file, and fetch-archive; see refreshing seeds.

Output streams

StreamContentEffect of --quiet
Standard outputRequested data: version, vars get, vars list, update --check; the standard output of run actions’ commandsNone for requested data; disconnects commands’ standard output
Standard errorChanges, progress, prompts, warnings, errorsSuppresses informational lines; keeps warnings and errors

Requested data has no labels or color. Errors and warnings raised by batfiles use error: and warning: labels, colored bold red and bold yellow when color is enabled. Verbose detail is unlabeled.

Dynamic commands inherit standard error unless --quiet disconnects it; their output is otherwise captured or discarded. See dynamic-command execution.

Sync and apply commands print no requested data, so a run action’s command inherits both streams directly and its output never mixes with batfiles’ own. Under --quiet its standard output is disconnected and its standard error kept.

Selecting what a run does

Selection preserves declaration order. sync considers all actions; apply commands consider the named action or group. Exclusions come from:

CLI and environment skips form a union, as do skips and persistent disables. Action and group namespaces are separate. An unnamed action can be selected by its group; an ungrouped action by its ID. Identified clone-list entries belong to the action namespace; groups reach entries only through the parent list. Excluding an inclusion leaves its whole manifest unread.

Malformed run-only addresses warn when inputs are read. Well-formed skips matching nothing warn after expansion and clone-list preparation, before any action executes. Both permit continuation. A name within an unread inclusion or list is neither matched nor unmatched, and does not warn. Persistent names matching nothing are always silent.

Selection by command

Exclusion sourcesyncapply-actionapply-group
An inclusion’s selection filtersHonorHonorHonor
Disabled action IDsHonorWaiveHonor
Disabled groupsHonorWaiveWaive the named group; honor others
--skip-action / BATFILES_SKIP_ACTIONSHonorOption rejected; environment ignoredHonor
--skip-group / BATFILES_SKIP_GROUPSHonorOption rejected; environment ignoredOption rejected; environment ignored
The action’s when / unlessEvaluate if otherwise selectedDo not evaluateEvaluate if otherwise selected
A run action’s triggerHonorWaiveHonor
A contributed run action’s missing allow-commandsHonorHonor; naming the action failsHonor

clone follows the sync column. Waivers affect only this invocation and never edit persistent state. apply-action does not evaluate the named record’s condition even if it would fail.

Naming a child does not waive its container’s exclusions. A qualified target opens its enclosing inclusion or clone list only if that container passes sync’s rules, including disables, accepted run-only skips, and its condition. An excluded container remains unread and fails the target naming the reason:

error: action `corp.zshrc` would come from include-remote `corp`, which is excluded: group `work` is disabled
error: entry `zsh-plugins.p10k` would come from git-clone-list `zsh-plugins`, which is excluded: action `zsh-plugins` is disabled

This includes a list excluded by inclusion filters: its entries cannot resolve. A contributed action whose own record is filtered out still resolves but applies nothing.

Conversely, naming a list waives none of its entries’ exclusions; each entry uses the table under its own address. Naming one entry with apply-action waives only that entry’s exclusions. An apply-group target reaching an inclusion reaches its contributed actions, but waives only the requested group: a contributed action whose own group is disabled is still left out, so apply-group --group work passes over the actions in a disabled corp.shell.

All three commands read the leaf manifest and disabled.toml, even when they waive lists. Missing state is empty; missing manifests and unreadable or malformed documents fail before action execution. Variable loading follows precedence.

Only sync materializes remotes; apply commands use existing trees. Every command evaluates remote conditions, and none waives them: sourcing an excluded remote fails. Only sync reports the remote’s exclusion as skipped materialization work.

Clone-list preparation

After the run’s list is expanded and selection and action conditions are settled, all selected, unskipped clone lists are read and validated before any action writes. This includes a list read only because the command names one of its entries, and the lists an inclusion contributed, each read from the materialization its record came from. Skipped lists are not opened. A missing or malformed executable list fails the run before installation begins, even if its action appears later in the list. A list produced by an earlier action in the same run is therefore unavailable for preparation.

Preparation decides each entry as selection decides a record — its disable, then the run-only skips, then its condition, evaluated only for an entry nothing else excludes — but the exclusions are reported when the parent action runs, in list order. It comes before run-only skips are checked for a match and before an apply command’s target is resolved, since an entry’s address is known only once its list has been read.

Addresses

An address is a nonempty sequence of IDs joined by ., with no segment-count limit. It is used wherever actions or groups are named, including skips, apply targets, persistent choices, and bootstrap defaults.

FormMeaning
<action-id>Leaf action
<group>Leaf group
<inclusion>.<action-id>Contributed action
<inclusion>.<group>Contributed group
<list>.<entry-id>Entry in a leaf clone list
<inclusion>.<list>.<entry-id>Entry in a contributed clone list

Unqualified names search only the leaf. <inclusion> is the inclusion record’s ID, which can differ from its remote’s ID. Without an inclusion ID, contributed content runs but cannot be addressed. An entry likewise needs both its own ID and an addressable list. Entries have no group addresses.

Unique action IDs disambiguate two-segment forms: zsh-plugins.p10k is an entry if zsh-plugins is a list, a contributed action if it is an inclusion. Reaching into either follows container selection.

Syntax and resolution are separate. Empty or invalid segments are malformed; a valid address matching no supported form, such as a.b.c.d.e, is simply not found. Commands storing addresses accept such names without resolving them.

Exclusion reporting

Expected exclusions appear only at -v, in the action heading:

create-dir zsh-cache (group shell) - skipped: group `shell` is disabled
symlink zshrc (group shell) - skipped: `zshrc` from --skip-action
symlink gitconfig-work (group git) - skipped: when "work" is false
symlink corp.p10k (group corp.prompt) - skipped: not selected by include-remote `corp`

Only the first applicable reason is reported, in this order: inclusion filters, persistent disables, run-only skips, then the condition. Among the disables, and among the skips, the action’s own address comes before its group. A skip names the option or environment variable responsible, and a condition is quoted as written. A record excluded for another reason never has its condition evaluated.

A contributed run action whose remote lacks allow-commands is excluded with a warning, at every verbosity, after the inclusion’s filters and before the other reasons:

warning: run corp.setup - skipped: remote `corporate` does not set `allow-commands = true`, so the `run` actions it contributes do not run

A run action that is selected but whose trigger does not fire is not excluded: -v prints not run: and the reason under its heading.

A condition that cannot be evaluated warns at every verbosity, without the - skipped: frame. The warning identifies the record, condition, failure, and remedy, without revealing the offending value.

Clone-list exclusions appear under their parent in entry order. Unrequested entries are silent; expected exclusions are verbose detail:

not cloning https://github.com/company/internal-zsh-tools.git (plugins.txt line 2): when "work" is false
not cloning https://github.com/romkatv/powerlevel10k.git (id=p10k, plugins.txt line 3): action `zsh-plugins.p10k` is disabled

Failed entry conditions warn in the same not cloning frame and leave other entries eligible. Remote exclusions appear before actions under remote <id>: ordinary condition exclusions at -v, evaluation failures as warnings. Neither stops the run, but an action sourcing that excluded remote fails naming it and repeating the reason.

Dry-run behavior

A dry run inspects the real filesystem and reports intended work without creating, replacing, or removing installation content. Each action sees the original filesystem; earlier reported writes are not simulated.

Bookkeeping still runs, including the run lock and dynamic-variable evaluation. Templates are evaluated, and reports show their resolved values. Dynamic commands are arbitrary programs and can themselves change files or contact the network. A github-release declaration makes its lookup’s network request in a dry run too. Captures of both kinds are saved in the cache. A run action’s command is never launched, and runs.toml is left untouched.

Reports use would link, would copy, and similar wording, in the same order and granularity as a real run: one line per child for directory-wide actions, one for a whole installed tree. Exclusion reports are identical in both modes.

OperationDry-run inspection and limits
Local sourceValidate presence/readability before considering the destination, even if it would be kept
Occupied destinationApply the same inspection policy and report each proposed backup name; never prompt
SeedReport keeping an occupied destination, or the intended copy/download
--refresh-contentBuild and fetch nothing; report the refresh that differing content would require, without testing equality
Git clone/updateRun no Git, including read-only commands; report cloning at a vacant destination or updating a directory
File/archive remoteInspect node and stamp to decide whether to fetch, refetch, keep, or refuse
Source inside a remoteRead the existing materialization, however stale; fail if missing or excluded
Included manifestRead the existing materialization, first verifying a permitted checkout’s origin with a local Git query; if absent, warn and mark the plan partial

Clone-list entries are read during preparation and reported individually; refs are printed as declared without resolving them. No installation downloads or Git network requests occur. A directory cannot be classified as a usable checkout without Git, so a dry run may report an update where a real run would find a conflict. Other destination kinds are classified normally.

A dry run cannot predict write permissions, concurrent changes, download digests, or archive entries. Archives are reported as whole trees. Declared remotes are described but never materialized, and excluded remotes are not read.

Overlapping actions can produce different reports in a real run. For example, create-dir followed by copy at the same destination reports would create and would copy, but a real run reports created and kept. A broken symlink that a real run clears once can be reported repeatedly in dry-run mode, including once per child when it occupies a directory action’s container.

Plan completeness

An include-remote whose missing materialization prevents listing its actions warns with the remote, reason, and remedy:

warning: remote `corporate` is not materialized at /home/me/dotfiles/remotes/corporate,
         so what it includes cannot be listed; run `batfiles sync` to bring it down

That warning marks a partial plan. Otherwise the plan is complete, with no additional completion message. These do not make a plan partial:

  • An unreached inclusion, or one excluded by a condition, disable, or skip.
  • A remote whose condition closes.
  • Warnings from a manifest that was read: unmatched inclusion filters, ignored nested inclusions, or ignored remote declarations.

Partiality alone does not fail a command: available actions still run or are reported, and status is 0 absent another failure. A specifically targeted action or group that cannot be resolved still fails. sync materializes remotes before action execution; dry runs and apply commands use existing trees, where missing materializations can leave a partial plan. Materialize the remote and repeat the command to see the remaining work.

Execution failures

An action failure stops sync or an apply command with status 1. Earlier changes remain; nothing is rolled back, and runs.toml still records them for after triggers. A run action with allow-failure warns instead, and the run continues. A failed template is an action failure, in dry runs too. Directory-wide actions likewise stop at the first failed child, preserving work already completed for earlier children.

Clone-list entry failures

git-clone-list processes entries independently. Something in the way of an entry’s destination, including a directory that is not a clone, an indirect checkout, or an incomplete clone, is a conflict settled for that entry alone. The list warns and continues after:

  • a Git subprocess that ran but failed, including clone, fetch, or update;
  • a declared ref that cannot be resolved.

The warning names the repository source, list file, line number, and entry ID when present. If the entry’s destination was backed up and could not be put back, it also names the backup. Warnings remain visible under --quiet.

These stop the run instead: failure to launch Git, filesystem read or write failures, failure to create the destination container, and an unanswered --interactive question. The categories are conservative; they do not claim that every remaining entry would fail the same way.

Recoverable entry failures do not fail the command, so status 0 can include entries that did not clone or update, even when every entry failed. Consult the warnings and the Git recovery policy before retrying. Standalone git-clone failures propagate normally.

Condition evaluation failures also warn and skip the affected action or entry without making the command fail. The condition rules define this fail-closed behavior; exclusion reporting defines the action warning format.

Exit statuses

StatusMeaning
0Successful command, --help, or --version; may include warnings
1Runtime or semantic failure; earlier work may remain
2Usage error before execution; no files read or written

Status 1 includes invalid addresses or machine-variable keys, missing or invalid documents, unresolved apply targets, missing vars get values, refresh failures, lock refusal, and installation/update failures. Explicit usage errors, such as invalid --var keys or vars refresh key syntax, are called out above.

Failures before action execution leave installation destinations untouched, although cloning, remote materialization, bootstrap state, and dynamic captures may already have occurred. See execution failures for stopping behavior and warnings that permit status 0.