vcspull add¶

The vcspull add command registers a repository in your configuration by pointing vcspull at a checkout on disk. The command inspects the directory, merges duplicate workspace roots by default, and prompts before writing unless you pass --yes.

Note

This command replaces the old vcspull import <name> <url> from v1.36–v1.39. For bulk scanning of local repositories, see vcspull discover. For bulk import from remote services (GitHub, GitLab, etc.), see vcspull import.

Command¶

Add a single repository to the configuration.

Usage¶

usage: vcspull add [-h] [--name OVERRIDE_NAME] [--url URL] [--pin REF]
                   [--shallow] [--depth N] [-f FILE] [-w DIR] [--dry-run]
                   [--no-merge] [-y]
                   [repo_path]

Examples¶

$ vcspull add ~/code/mylib

$ vcspull add ~/src/mylib --workspace ~/code

$ vcspull add ~/code/mylib --url https://github.com/example/mylib.git --dry-run

Positional Arguments¶

repo_path¶

Filesystem path to an existing project. The parent directory becomes the workspace unless overridden with --workspace.

Default: None

Options¶

--name¶

Override detected repository name when importing from a path

Default: None

--url¶

Repository URL to record (overrides detected remotes)

Default: None

--pin REF¶

Record a fixed commit, tag, or branch as the repository 'rev'

Default: None

--shallow¶

Record 'options.shallow: true' (clone --depth 1 on sync). A shallow checkout is detected automatically; this forces it on.

Default: False

--depth N¶

Record 'options.depth: N' (clone --depth N on sync). Overrides --shallow. An existing shallow checkout's depth is detected automatically.

Default: None
Type: int

-f, --file FILE¶

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

Default: None

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

Workspace root directory in config (e.g., '~/projects/'). Defaults to the parent directory of the repository path.

Default: None

--dry-run, -n¶

Preview changes without writing to config file

Default: False

--no-merge¶

Skip merging duplicate workspace roots before writing

Default: True

-y, --yes¶

Automatically confirm interactive prompts

Default: False

Basic usage¶

Point to an existing checkout to add it under its parent workspace:

$ vcspull add ~/study/python/pytest-docker
Found new repository to import:
  + pytest-docker (https://github.com/avast/pytest-docker)
  • workspace: ~/study/python/
  ↳ path: ~/study/python/pytest-docker
? Import this repository? [y/N]: y
Successfully added 'pytest-docker' (git+https://github.com/avast/pytest-docker) to ~/.vcspull.yaml under '~/study/python/'.

The parent directory (~/study/python/ in this example) becomes the workspace root. vcspull shortens paths under $HOME to ~/... in its log output so the preview stays readable.

Overriding detected information¶

Choose a different name¶

Override the derived repository name with --name when the directory name isn’t the label you want stored in the configuration:

$ vcspull add ~/study/python/pytest-docker --name docker-pytest

Override the remote URL¶

vcspull reads the Git origin remote automatically. Supply --url when you need to register a different remote or when the checkout does not have one yet:

$ vcspull add ~/study/python/example --url https://github.com/org/example

URLs follow pip’s VCS format; vcspull inserts the git+ prefix for HTTPS URLs so the resulting configuration matches vcspull fmt output.

Select a workspace explicitly¶

The workspace defaults to the checkout’s parent directory. Pass --workspace/--workspace-root to store the repository under a different section:

$ vcspull add ~/scratch/tmp-project --workspace ~/projects/python/

Confirmation and dry runs¶

vcspull add asks for confirmation before writing. Use --yes to skip the prompt in automation, or --dry-run/-n to preview the changes without modifying any files:

$ vcspull add ~/study/python/pytest-docker --dry-run

Dry runs still show duplicate merge diagnostics so you can see what would change.

Choosing configuration files¶

vcspull searches for configuration files in this order:

./.vcspull.yaml
~/.vcspull.yaml
~/.config/vcspull/*.yaml

Specify a file explicitly with -f/--file:

$ vcspull add ~/study/python/pytest-docker \
    --file ~/configs/python.yaml

Handling duplicates¶

vcspull merges duplicate workspace sections before writing so existing repositories stay intact. When it collapses multiple sections, the command logs a summary of the merge. Prefer to inspect duplicates yourself? Add --no-merge to keep every section untouched.

Pinned entries¶

Repositories whose configuration includes a pin on the add operation are skipped with a warning. For example, given this configuration:

~/code/:
  internal-fork:
    repo: "[email protected]:myorg/internal-fork.git"
    options:
      pin: true
      pin_reason: "pinned to company fork — update manually"

Attempting to add a repo that matches an existing pinned entry produces a warning and leaves the entry untouched:

$ vcspull add ~/code/internal-fork
⚠ Repository 'internal-fork' is pinned (pinned to company fork — update manually) — skipping

Both options.pin: true (global) and options.pin.add: true (per-operation) block the add command. The pin_reason (if set) is included in the warning. See Repository pinning for full pin configuration.

After adding repositories¶

Run vcspull fmt with --write to normalize your configuration.
Run vcspull list to verify the new entry.
Run vcspull sync to clone or update the working tree.

Migration from the old vcspull import¶

The vcspull import <name> <url> command from v1.36–v1.39 has been replaced by vcspull add:

- $ vcspull import flask https://github.com/pallets/flask.git -c ~/.vcspull.yaml
+ $ vcspull add ~/code/flask --url https://github.com/pallets/flask.git --file ~/.vcspull.yaml

Key differences:

vcspull add derives the name from the filesystem unless you pass --name.
The parent directory becomes the workspace automatically; use --workspace to override.
Use --url to record a remote when the checkout does not have one.

Note

Starting with v1.55, vcspull import is a different command that bulk-imports repositories from remote services (GitHub, GitLab, etc.). See vcspull import for details.