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.

When duplicate workspace roots are encountered, the formatter merges them into a single section so repositories are never dropped. Prefer to review duplicates without rewriting them? Pass --no-merge to leave the original sections in place while still showing a warning.

Command

Format vcspull configuration files for consistency.

Normalizes repository entries, sorts sections, and can write changes back to disk or format all discovered configuration files.

Usage

usage: vcspull fmt [-h] [-f FILE] [--write] [--all] [--no-merge]

Examples

$ vcspull fmt

$ vcspull fmt -f ./myrepos.yaml

$ vcspull fmt --write

$ vcspull fmt --all

Options

-f, --file FILE

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

Default

None

--write, -w

Write formatted configuration back to file

Default

False

--all

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

Default

False

--no-merge

Do not merge duplicate workspace roots when formatting

Default

True

What gets formatted

The formatter performs four 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.

• Consolidates duplicate workspace roots into a single merged section while logging any conflicts.

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:

$ vcspull fmt --file ~/.vcspull.yaml

Then add --write (or -w) to persist them back to disk:

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

Short form for preview:

$ vcspull fmt -f ~/.vcspull.yaml

Short form to apply:

$ vcspull fmt -f ~/.vcspull.yaml -w

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 discover after scanning the file system to keep newly added repositories ordered and normalized.