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¶

Synchronize VCS repositories.

Usage¶

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 ...]

Examples¶

$ vcspull sync "*"

$ vcspull sync "django-"

$ vcspull sync --dry-run ""

$ vcspull sync -f ./myrepos.yaml "*"

$ vcspull sync -w ~/code myproject

Positional Arguments¶

repo_patterns pattern

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

Default: None

Options¶

-f, --file FILE

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

Default: None

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

filter by workspace root directory

Default: None

--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

when to use colors (default: auto)

Default: auto | Choices: auto, always, never

--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:

Current directory (.vcspull.yaml)
Home directory (~/.vcspull.yaml)
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. Using --workspace:

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

Or using --workspace-root:

$ 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