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

Troubleshooting

Start with verbose output from the command you were running. For a preview:

batfiles sync --dry-run -v

This reports selected roots, actions, and exclusions. Dynamic-variable commands can still run during dry-run; use batfiles vars list --no-refresh to inspect cached values without running them.

The command printed nothing

An ordinary sync is quiet when it changes nothing. Add -v to distinguish correct destinations from skipped actions. Copies and downloads keep existing destinations; use refresh-content when you want to replace an editable seed from its source.

An action did not run

Check the reason printed at -v: a condition, persistent disable, run-only skip, or inclusion filter may exclude it. Use vars list --no-refresh to inspect leaf values and sync --dry-run -vv to inspect values used by opened inclusions. A condition that cannot be evaluated prints a warning and skips its action, whether it is written as when or unless.

Enabling a group does not override its members’ conditions. Conversely, apply-action deliberately bypasses the named action’s own condition and persistent disable. See selection.

A command did not run

A selected run action whose trigger did not fire prints not run: and the reason at -v: not a bootstrap run, already ran, ran 3h ago, or nothing it follows changed. Run it regardless with batfiles apply-action --id <id>. An after target counts only what changed in the run, so a change made outside batfiles does not fire it. A contributed command that warns about allow-commands needs that permission on its remote.

Batfiles selected the wrong repository

Run from the directory containing batfiles.toml, or provide --batfiles-dir /path/to/dotfiles. Discovery does not walk up from subdirectories. BATFILES_DIR, if set, takes priority over discovery. -v shows the roots used. See locations.

There is something at the destination

The default conflict policy backs up unmanaged content beside its destination. Use --no-overwrite to skip conflicts or --interactive to decide individually. Copy and download seeds normally keep an occupied destination without replacing it. See destination safety.

Backups have names such as settings.toml.batfiles-backup-20261006T142233Z. To restore one, inspect both versions, move the current destination aside, and move the chosen backup back to its original name. Disable or change the action first if the next synchronization would otherwise replace it again. Batfiles never automatically deletes backups.

The preview says its plan is partial

An included remote has not been materialized, so its actions cannot be read. Review that repository, then use sync to fetch it and apply the configuration. Repeat your preview to see the full set. A partial plan can exit successfully; it does not mean every potential action was inspected. See plan completeness.

A Git checkout did not update

Read the warning, then inspect that checkout with git status and Git’s branch and remote tools. Batfiles preserves local modifications and diverged branches rather than resetting them. Resolve the Git situation and retry. A normal sync also does not pull the leaf repository itself. See Git update policy.

A dynamic value is stale

batfiles vars list --no-refresh
batfiles vars refresh

The first shows cached values and freshness; the second runs the declarations in play again. Failed refreshes can retain an older value, and explicit refresh reports failure. For a remote variable, the refresh name is remote-id.name, not an inclusion’s address. See refreshing variables.

Another run holds the lock

Wait for the other run using the same cache directory to finish. The presence of run.lock alone does not mean a process holds it; the operating-system lock is released when the process exits. Do not delete or replace the file while a run is active. See run lock.

A run failed partway through

Earlier completed work remains. Fix the reported cause and retry; the whole run is not rolled back. Exit status 0 can still include warnings, including failed clone-list entries. Read failure behavior and exit statuses when scripting batfiles.

Symlink actions require Unix. Use copies for Windows where appropriate, or condition Unix-only actions on host facts. See machine configuration.