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.
| Option | Purpose |
|---|---|
--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
--reffails before manifest loading and leaves the default branch checked out. Correct it with Git, then runsync --bootstrap. - A missing
batfiles.tomlfails 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.