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

clone

batfiles clone <url> [--ref <ref>] [--skip-action <id>]... [--skip-group <group>]...
    [--enable-action <id>]... [--disable-action <id>]...
    [--enable-group <group>]... [--disable-group <group>]...

Clone a leaf repository into the selected batfiles directory, adopt its bootstrap policy, and sync, in which a run action’s bootstrap trigger fires. Location selection excludes working-directory discovery for this command.

The destination must not exist, even as an empty directory or broken symlink. Batfiles rejects it before launching Git; missing parents are created.

OptionPurpose
--ref <ref>Check out a branch, tag, or commit before reading the manifest; never empty
--skip-action <id>Skip an action during this synchronization; repeatable
--skip-group <group>Skip a group during this synchronization; repeatable
--disable-action <id> / --enable-action <id>Persist a bootstrap action choice; repeatable
--disable-group <group> / --enable-group <group>Persist a bootstrap group choice; repeatable

The shared execution options also apply. clone accepts neither --dry-run nor --refresh-remotes.

--ref follows the manifest ref rules: a published branch becomes a local tracking branch; other resolved refs are detached. Without it, the origin’s HEAD selects the branch. Batfiles records no ref and never updates the leaf repository itself.

What the bootstrap decides

Bootstrap applies the leaf’s default-disabled candidates and explicit enable/disable inputs using adoption precedence, then persists the result under the state lifecycle rules. Included manifests’ bootstrap sections are ignored. Candidate conditions use the leaf’s effective variables; a condition failure warns and leaves the candidate unapplied. Ordinary condition exclusions are reported at -v.

Each decision is reported with its source and the same wording as an enable/disable command:

default-disabled: disabled action `p10k`
BATFILES_DISABLE_GROUPS: disabled group `gui`
--enable-group: enabled group `gui` (was disabled)

Malformed option addresses fail before cloning; malformed environment addresses warn and are dropped. Once cloned, the repository is kept on any later failure:

  • An unresolved --ref fails before manifest loading and leaves the default branch checked out. Correct it with Git, then run sync --bootstrap.
  • A missing batfiles.toml fails before bootstrap, identifying the clone as a Git repository that is not a batfiles repository.
  • A synchronization failure leaves both the clone and written bootstrap state in place. Fix the cause and retry with sync.

See global options and output conventions.