vcspull migrate¶

vcspull migrate rewrites configuration files to the current schema, moving the per-repository rev, shallow, and depth keys from the entry root into the options: block. By default it prints the proposed changes; apply them in place with --write.

These keys shipped at the entry root in vcspull v1.61.0. They are still read, but vcspull sync warns when it encounters them. Migrating clears the warning and keeps configs on the supported shape.

Command¶

Migrate configuration files to the options: form.

Relocates per-repository rev/shallow/depth keys from the entry root into the options: block. Without –write it previews changes; with –write it rewrites the file(s).

Usage¶

usage: vcspull migrate [-h] [-f FILE] [--write] [--all]

Examples¶

$ vcspull migrate

$ vcspull migrate -f ./myrepos.yaml

$ vcspull migrate --write

$ vcspull migrate --all --write

Options¶

-f, --file FILE¶

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

Default: None

--write, -w¶

Write migrated configuration back to file

Default: False

--all¶

Migrate all discovered config files (home, config dir, current dir)

Default: False

What gets migrated¶

For each repository entry, a top-level rev, shallow, or depth key is moved under options:. A value already present under options: wins, and depth takes precedence over shallow. Entries already on the options: form, string shorthands, and unrelated keys are left untouched.

Given:

~/code/:
  flask:
    repo: git+https://github.com/pallets/flask.git
    rev: v3.0.0
    shallow: true

vcspull migrate --write produces:

~/code/:
  flask:
    repo: git+https://github.com/pallets/flask.git
    options:
      rev: v3.0.0
      shallow: true

Writing changes¶

Preview the rewrite first:

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

Then add --write to persist it:

$ vcspull migrate \
    --file ~/.vcspull.yaml \
    --write

Use --all to iterate over the default search locations: the current working directory, ~/.vcspull.*, and the XDG configuration directory.

$ vcspull migrate --all --write

Migration is idempotent—running it again on an already-migrated file makes no changes.