vcspull list¶

The vcspull list command displays configured repositories from your vcspull configuration files. Use this introspection command to verify your configuration, filter repositories by patterns, and export structured data for automation.

Command¶

List configured repositories.

Usage¶

usage: vcspull list [-h] [-f FILE] [-w DIR] [--tree] [--json] [--ndjson]
                    [--color {auto,always,never}]
                    [pattern ...]

Examples¶

$ vcspull list

$ vcspull list "django-*"

$ vcspull list --tree

$ vcspull list --json

Positional Arguments¶

repo_patterns pattern¶

filter repositories by name pattern (supports fnmatch)

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

--tree¶

display repositories grouped by workspace root

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

Basic usage¶

List all configured repositories:

$ vcspull list
• tiktoken → ~/study/ai/tiktoken
• GeographicLib → ~/study/c++/GeographicLib
• flask → ~/code/flask

Filtering repositories¶

Filter repositories using fnmatch-style patterns:

$ vcspull list 'flask*'
• flask → ~/code/flask
• flask-sqlalchemy → ~/code/flask-sqlalchemy

Multiple patterns are supported:

$ vcspull list django flask

Tree view¶

Group repositories by workspace root with --tree:

$ vcspull list --tree

~/study/ai/
  • tiktoken → ~/study/ai/tiktoken

~/study/c++/
  • GeographicLib → ~/study/c++/GeographicLib
  • anax → ~/study/c++/anax

~/code/
  • flask → ~/code/flask

JSON output¶

Export repository information as JSON for automation and tooling:

$ vcspull list --json

Output format:

[
  {
    "name": "tiktoken",
    "url": "git+https://github.com/openai/tiktoken.git",
    "path": "~/study/ai/tiktoken",
    "workspace_root": "~/study/ai/"
  },
  {
    "name": "flask",
    "url": "git+https://github.com/pallets/flask.git",
    "path": "~/code/flask",
    "workspace_root": "~/code/"
  }
]

The workspace_root field shows which configuration section the repository belongs to, matching the keys in your .vcspull.yaml file.

Filter JSON output with tools like jq:

$ vcspull list --json | jq '.[] | select(.workspace_root | contains("study"))'

NDJSON output¶

For streaming and line-oriented processing, use --ndjson:

$ vcspull list --ndjson
{"name":"tiktoken","url":"git+https://github.com/openai/tiktoken.git","path":"~/study/ai/tiktoken","workspace_root":"~/study/ai/"}
{"name":"flask","url":"git+https://github.com/pallets/flask.git","path":"~/code/flask","workspace_root":"~/code/"}

Each line is a complete JSON object, making it ideal for:

Processing large configurations line-by-line
Streaming data to other tools
Parsing with simple line-based tools

$ vcspull list --ndjson | grep 'study' | jq -r '.name'

Choosing configuration files¶

By default, vcspull searches for config files in standard locations (~/.vcspull.yaml, ./.vcspull.yaml, and XDG config directories).

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

$ vcspull list -f ~/projects/.vcspull.yaml

Workspace filtering¶

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

$ vcspull list -w ~/code/
• flask → ~/code/flask
• requests → ~/code/requests

Globbing is supported, so you can target multiple related workspaces:

$ vcspull list --workspace '*/work/*'

The workspace filter combines with pattern filters and structured output flags, allowing you to export subsets of your configuration quickly.

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.