vcspull fmt¶

vcspull fmt normalizes configuration files so directory keys and repository entries stay consistent. By default the formatter prints the proposed changes to stdout. Apply the updates in place with --write.

Command¶

usage: vcspull fmt [-h] [-c file] [--write] [--all]

Named Arguments¶

-c, --config

path to custom config file (default: .vcspull.yaml or ~/.vcspull.yaml)

--write, -w

Write formatted configuration back to file

Default: False

--all

Format all discovered config files (home, config dir, and current dir)

Default: False

What gets formatted¶

The formatter performs three main tasks:

Expands string-only entries into verbose dictionaries using the repo key.
Converts legacy url keys to repo for consistency with the rest of the tooling.
Sorts directory keys and repository names alphabetically to minimize diffs.

For example:

~/code/:
  libvcs: git+https://github.com/vcspull/libvcs.git
  vcspull:
    url: git+https://github.com/vcspull/vcspull.git

becomes:

~/code/:
  libvcs:
    repo: git+https://github.com/vcspull/libvcs.git
  vcspull:
    repo: git+https://github.com/vcspull/vcspull.git

Writing changes¶

Run the formatter in dry-run mode first to preview the adjustments, then add --write (or -w) to persist them back to disk:

$ vcspull fmt --config ~/.vcspull.yaml
$ vcspull fmt --config ~/.vcspull.yaml --write

Use --all to iterate over the default search locations: the current working directory, ~/.vcspull.*, and the XDG configuration directory. Each formatted file is reported individually.

$ vcspull fmt --all --write

Pair the formatter with vcspull import after scanning the file system to keep newly added repositories ordered and normalized.