vcspull import¶

The vcspull import command registers existing repositories with your vcspull configuration. You can either provide a single repository name and URL or scan directories for Git repositories that already live on disk.

Command¶

usage: vcspull import [-h] [-c file] [--path PATH] [--workspace-root DIR]
                      [--scan DIR] [--recursive] [--yes]
                      [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¶

-c, --config

path to custom 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-root)

--workspace-root

Workspace root directory in config (e.g., ‘~/projects/’). If not specified, will be inferred from –path or use current directory. When used with –scan, applies the workspace root to all discovered repos.

--scan

Scan directory for git repositories and import them

--recursive, -r

Scan directories recursively (use with –scan)

Default: False

--yes, -y

Skip confirmation prompt (use with –scan)

Default: False

Manual import¶

Provide a repository name and remote URL to append an entry to your configuration. Use --path when you already have a working tree on disk so the inferred workspace root matches its location. Override the detected workspace root with --workspace-root when you need to target a specific directory.

$ vcspull import my-lib https://github.com/example/my-lib.git --path ~/code/my-lib
$ vcspull import another-lib https://github.com/example/another-lib.git \
    --workspace-root ~/code

With no -c/--config flag vcspull looks for the first YAML configuration file under ~/.config/vcspull/ or the current working directory. When none exist a new .vcspull.yaml is created next to where you run the command.

Filesystem scanning¶

vcspull import --scan discovers Git repositories that already exist on disk and writes them to your configuration. The command prompts before adding each repository, showing the inferred name, workspace root, and origin URL (when available).

$ vcspull import --scan ~/code --recursive
? Add ~/code/vcspull (workspace root: ~/code/)? [y/N]: y
? Add ~/code/libvcs (workspace root: ~/code/)? [y/N]: y

--recursive/-r searches nested directories.
--workspace-root forces all discovered repositories to use the same workspace root, overriding the directory inferred from their location.
--yes/-y accepts every suggestion, which is useful for unattended migrations.

When vcspull detects a Git remote named origin it records the remote URL in the configuration. Repositories without a remote are still added, allowing you to fill the repo key later.

Choosing configuration files¶

Pass -c/--config to import into a specific YAML file:

$ vcspull import --scan ~/company --recursive --config ~/company/.vcspull.yaml

Use --all with the vcspull fmt command after a large scan to keep configuration entries sorted and normalized.