vcspull add¶

The vcspull add command adds a single repository to your vcspull configuration. Provide a repository name and URL, and vcspull will append it to your config file with the appropriate workspace root.

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] [-f FILE] [--path PATH] [-w DIR] [--dry-run] name url

Positional Arguments¶

name: Name for the repository in the config
url: Repository URL (e.g., https://github.com/user/repo.git)

Named Arguments¶

-f, --file

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

--path

Local directory path where repo will be cloned (determines workspace root if not specified with –workspace)

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

Workspace root directory in config (e.g., ‘~/projects/’). If not specified, will be inferred from –path or use current directory.

--dry-run, -n

Preview changes without writing to config file

Default: False

Basic usage¶

Add a repository by name and URL:

$ vcspull add flask https://github.com/pallets/flask.git
Successfully added 'flask' to ./.vcspull.yaml under './'

By default, the repository is added to the current directory’s workspace root (./).

Specifying workspace root¶

Use -w/--workspace or --workspace-root to control where the repository will be checked out:

$ vcspull add flask https://github.com/pallets/flask.git -w ~/code/
Successfully added 'flask' to ~/.vcspull.yaml under '~/code/'

All three flag names work identically:

$ vcspull add django https://github.com/django/django.git --workspace ~/code/
$ vcspull add requests https://github.com/psf/requests.git --workspace-root ~/code/

Custom repository path¶

Override the inferred path with --path when the repository already exists on disk:

$ vcspull add my-lib https://github.com/example/my-lib.git \
    --path ~/code/libraries/my-lib

The --path flag is useful when:

Migrating existing local repositories
Using non-standard directory layouts
The repository name doesn’t match the desired directory name

Choosing configuration files¶

By default, vcspull looks for the first YAML configuration file in:

Current directory (.vcspull.yaml)
Home directory (~/.vcspull.yaml)
XDG config directory (~/.config/vcspull/)

If no config exists, a new .vcspull.yaml is created in the current directory.

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

$ vcspull add vcspull https://github.com/vcs-python/vcspull.git \
    -f ~/projects/.vcspull.yaml

Dry run mode¶

Preview changes without modifying your configuration with --dry-run or -n:

$ vcspull add flask https://github.com/pallets/flask.git -w ~/code/ --dry-run
Would add 'flask' (https://github.com/pallets/flask.git) to ~/.vcspull.yaml under '~/code/'

This is useful for:

Verifying the workspace root is correct
Checking which config file will be modified
Testing path inference

URL formats¶

Repositories use pip VCS URL format with a scheme prefix:

Git: git+https://github.com/user/repo.git
Mercurial: hg+https://bitbucket.org/user/repo
Subversion: svn+http://svn.example.org/repo/trunk

The URL scheme determines the VCS type. For Git, the git+ prefix is required.

Examples¶

Add to default location:

$ vcspull add myproject https://github.com/myuser/myproject.git

Add to specific workspace:

$ vcspull add django-blog https://github.com/example/django-blog.git \
    -w ~/code/django/

Add with custom path:

$ vcspull add dotfiles https://github.com/myuser/dotfiles.git \
    --path ~/.dotfiles

Preview before adding:

$ vcspull add flask https://github.com/pallets/flask.git \
    -w ~/code/ --dry-run

Add to specific config file:

$ vcspull add tooling https://github.com/company/tooling.git \
    -f ~/company/.vcspull.yaml \
    -w ~/work/

Handling duplicates¶

If a repository with the same name already exists in the workspace, vcspull will warn you:

$ vcspull add flask https://github.com/pallets/flask.git -w ~/code/
WARNING: Repository 'flask' already exists in workspace '~/code/'.

The existing entry is preserved and not overwritten.

After adding repositories¶

After adding repositories, consider:

Running vcspull fmt --write to normalize and sort your configuration (see vcspull fmt)
Running vcspull list to verify the repository was added correctly (see vcspull list)
Running vcspull sync to clone the repository (see vcspull sync)

Migration from vcspull import¶

If you previously used vcspull import <name> <url>:

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

Changes:

Command name: import → add
Config flag: -c → -f
Same functionality otherwise