vcspull search¶

The vcspull search command looks up repositories across your vcspull configuration with an rg-like query syntax. Queries are regex by default, can scope to specific fields, and can emit structured JSON for automation.

Command¶

Search configured repositories.

Query terms use regex by default, with optional field prefixes like name:, path:, url:, or workspace:.

Usage¶

usage: vcspull search [-h] [-f FILE] [-w DIR] [--field NAME] [-i] [-S] [-F]
                      [--word-regexp] [-v] [--any] [--json] [--ndjson]
                      [--color {auto,always,never}]
                      query [query ...]

Examples¶

$ vcspull search django

$ vcspull search name:django url:github

$ vcspull search --fixed-strings 'git+https://github.com/org/repo.git'

$ vcspull search --ignore-case --any django flask

Positional Arguments¶

query_terms query¶

search query terms (regex by default). Use field prefixes like name:, path:, url:, workspace:.

Default: None
Required

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

--field NAME¶

limit unscoped queries to specific fields (name, path, url, workspace). Repeatable or comma-separated.

Default: None

-i, --ignore-case¶

case-insensitive matching

Default: False

-S, --smart-case¶

smart case matching (ignore case unless pattern has capitals)

Default: False

-F, --fixed-strings¶

treat search terms as literal strings

Default: False

--word-regexp¶

match only whole words

Default: False

-v, --invert-match¶

show non-matching repositories

Default: False

--any¶

match if any term matches (default: all terms)

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¶

Search all fields (name, path, url, workspace) with regex:

$ vcspull search django
• django → ~/code/django

Field-scoped queries¶

Target specific fields with prefixes:

$ vcspull search name:django url:github
• django → ~/code/django
  url: git+https://github.com/django/django.git

Available field prefixes:

name:
path:
url:
workspace: (alias: root: or ws:)

Literal matches¶

Use -F/--fixed-strings to match literal text instead of regex:

$ vcspull search --fixed-strings 'git+https://github.com/org/repo.git'

Case handling¶

-i/--ignore-case forces case-insensitive matching. -S/--smart-case matches case-insensitively unless your query includes uppercase characters.

$ vcspull search -S Django

Boolean matching¶

By default all terms must match. Use --any to match if any term matches:

$ vcspull search --any django flask

Invert matches with -v/--invert-match:

$ vcspull search -v --fixed-strings github

JSON output¶

Emit matches as JSON for automation:

$ vcspull search --json django

Output format:

[
  {
    "name": "django",
    "url": "git+https://github.com/django/django.git",
    "path": "~/code/django",
    "workspace_root": "~/code/",
    "matched_fields": ["name", "url"]
  }
]

Use NDJSON for streaming:

$ vcspull search --ndjson django