vcspull sync

The vcspull sync command clones and updates repositories defined in your vcspull configuration. It’s the primary command for keeping your local workspace synchronized with remote repositories.

Command

usage: vcspull sync [-h] [-f FILE] [-w DIR] [--dry-run] [--json] [--ndjson]
                    [--color {auto,always,never}] [--exit-on-error]
                    [--show-unchanged] [--summary-only] [--long]
                    [--relative-paths] [--fetch] [--offline] [-v]
                    [pattern ...]

Positional Arguments

pattern

patterns / terms of repos, accepts globs / fnmatch(3)

Named Arguments

-f, --file

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

-w, --workspace, --workspace-root

filter by workspace root directory

--dry-run, -n

preview what would be synced without making changes

Default: False

--json

output as JSON

Default: False

--ndjson

output as NDJSON (one JSON per line)

Default: False

--color

Possible choices: auto, always, never

when to use colors (default: auto)

Default: 'auto'

--exit-on-error, -x

exit immediately encountering error (when syncing multiple repos)

Default: False

--show-unchanged

include repositories that are already up to date

Default: False

--summary-only

print only the plan summary line

Default: False

--long

show extended details for each repository

Default: False

--relative-paths

display repository paths relative to the workspace root

Default: False

--fetch

refresh remote tracking information before planning

Default: False

--offline

skip network access while planning (overrides –fetch)

Default: False

-v, --verbose

increase plan verbosity (-vv for maximum detail)

Default: 0

Dry run mode

Preview what would be synchronized without making changes:

$ vcspull sync --dry-run '*'
Would sync flask at ~/code/flask
Would sync django at ~/code/django
Would sync requests at ~/code/requests

Use --dry-run or -n to:

  • Verify your configuration before syncing

  • Check which repositories would be updated

  • Test pattern filters

  • Preview operations in CI/CD

JSON output

Export sync operations as JSON for automation:

$ vcspull sync --dry-run --json '*'
[
  {
    "reason": "sync",
    "name": "flask",
    "path": "~/code/flask",
    "workspace_root": "~/code/",
    "status": "preview"
  },
  {
    "reason": "summary",
    "total": 3,
    "synced": 0,
    "previewed": 3,
    "failed": 0
  }
]

Each event emitted during the run includes:

  • reason: "sync" for repository events, "summary" for the final summary

  • name, path, workspace_root: Repository metadata from your config

  • status: "synced", "preview", or "error" (with an error field)

Use --json without --dry-run to capture actual sync executions—successful and failed repositories are emitted with their final state.

NDJSON output

Stream sync events line-by-line with --ndjson:

$ vcspull sync --dry-run --ndjson '*'
{"reason":"sync","name":"flask","path":"~/code/flask","workspace_root":"~/code/","status":"preview"}
{"reason":"summary","total":3,"synced":0,"previewed":3,"failed":0}

Each line is a JSON object representing a sync event, ideal for:

  • Real-time processing

  • Progress monitoring

  • Log aggregation

Configuration file selection

Specify a custom config file with -f/--file:

$ vcspull sync -f ~/projects/.vcspull.yaml '*'

By default, vcspull searches for config files in:

  1. Current directory (.vcspull.yaml)

  2. Home directory (~/.vcspull.yaml)

  3. XDG config directory (~/.config/vcspull/)

Workspace filtering

Filter repositories by workspace root with -w/--workspace or --workspace-root:

$ vcspull sync -w ~/code/ '*'

This syncs only repositories in the specified workspace root, useful for:

  • Selective workspace updates

  • Multi-workspace setups

  • Targeted sync operations

All three flag names work identically:

$ vcspull sync --workspace ~/code/ '*'
$ vcspull sync --workspace-root ~/code/ '*'

Color output

Control colored output with --color:

  • --color auto (default): Use colors if outputting to a terminal

  • --color always: Always use colors

  • --color never: Never use colors

The NO_COLOR environment variable is also respected.

Filtering repos

As of 1.13.x, $ vcspull sync with no args passed will show a help dialog:

$ vcspull sync
Usage: vcspull sync [OPTIONS] [REPO_TERMS]...

Sync all repos

Depending on how your terminal works with shell escapes for expands such as the wild card / asterisk, you may not need to quote *.

$ vcspull sync '*'

Filtering

Filter all repos start with “django-“:

$ vcspull sync 'django-*'

Multiple terms

Filter all repos start with “django-“:

$ vcspull sync 'django-anymail' 'django-guardian'

Error handling

Repos not found in config

As of 1.13.x, if you enter a repo term (or terms) that aren’t found throughout your configurations, it will show a warning:

$ vcspull sync non_existent_repo
No repo found in config(s) for "non_existent_repo"

$ vcspull sync non_existent_repo existing_repo
No repo found in config(s) for "non_existent_repo"

$ vcspull sync non_existent_repo existing_repo another_repo_not_in_config
No repo found in config(s) for "non_existent_repo"
No repo found in config(s) for "another_repo_not_in_config"

Since syncing terms are treated as a filter rather than a lookup, the message is considered a warning, so will not exit even if --exit-on-error flag is used.

Syncing

As of 1.13.x, vcspull will continue to the next repo if an error is encountered when syncing multiple repos.

To imitate the old behavior, the --exit-on-error / -x flag:

$ vcspull sync --exit-on-error grako django

Print traceback for errored repos:

$ vcspull --log-level DEBUG sync --exit-on-error grako django