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 manual import functionality from vcspull import. For bulk scanning of existing repositories, see vcspull discover.

Command

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

Positional Arguments

repo_path

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

Named Arguments

--name

Override detected repository name when importing from a path

--url

Repository URL to record (overrides detected remotes)

-f, --file

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

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

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

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

  1. ./.vcspull.yaml

  2. ~/.vcspull.yaml

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

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

$ vcspull add ~/study/python/pytest-docker -f ~/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.

After adding repositories

  1. Run vcspull fmt --write to normalize your configuration (see vcspull fmt).

  2. Run vcspull list to verify the new entry (see vcspull list).

  3. Run vcspull sync to clone or update the working tree (see vcspull sync).

Migration from vcspull import

If you previously used vcspull import <name> <url>, switch to the path-first workflow:

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

Key differences:

  • vcspull add now 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.