Config - vcspull.config

Configuration functionality for vcspull.

vcspull.config.expand_dir(dir_, cwd=pathlib.Path.cwd)

Return path with environmental variables and tilde ~ expanded.

Return type:

Path

Parameters:

• dir (pathlib.Path) – Directory path to expand

• cwd (pathlib.Path, optional) – Current working dir (used to resolve relative paths). Defaults to pathlib.Path.cwd().

• dir_ (Path)

Returns:

Absolute directory path

Return type:

pathlib.Path

vcspull.config._validate_worktrees_config(worktrees_raw, repo_name)

Validate and normalize worktrees configuration.

Return type:

list[WorktreeConfigDict]

Parameters:

• worktrees_raw (Any) – Raw worktrees configuration from YAML/JSON.

• repo_name (str) – Name of the parent repository (for error messages).

Returns:

Validated list of worktree configurations.

Return type:

list[WorktreeConfigDict]

Raises:

VCSPullException – If the worktrees configuration is invalid.

Examples

Valid configuration with a tag:

>>> from vcspull.config import _validate_worktrees_config
>>> config = [{"dir": "../v1", "tag": "v1.0.0"}]
>>> result = _validate_worktrees_config(config, "myrepo")
>>> len(result)
1
>>> result[0]["dir"]
'../v1'
>>> result[0]["tag"]
'v1.0.0'

Valid configuration with a branch:

>>> config = [{"dir": "../dev", "branch": "develop"}]
>>> result = _validate_worktrees_config(config, "myrepo")
>>> result[0]["branch"]
'develop'

Valid configuration with a commit:

>>> config = [{"dir": "../fix", "commit": "abc123"}]
>>> result = _validate_worktrees_config(config, "myrepo")
>>> result[0]["commit"]
'abc123'

Error: worktrees must be a list:

>>> _validate_worktrees_config("not-a-list", "myrepo")
Traceback (most recent call last):
    ...
vcspull.exc.VCSPullException: ...worktrees must be a list, got str

Error: worktree entry must be a dict:

>>> _validate_worktrees_config(["not-a-dict"], "myrepo")
Traceback (most recent call last):
    ...
vcspull.exc.VCSPullException: ...must be a dict, got str

Error: missing required ‘dir’ field:

>>> _validate_worktrees_config([{"tag": "v1.0.0"}], "myrepo")
Traceback (most recent call last):
    ...
vcspull.exc.VCSPullException: ...missing required 'dir' field

Error: no ref type specified:

>>> _validate_worktrees_config([{"dir": "../wt"}], "myrepo")
Traceback (most recent call last):
    ...
vcspull.exc.VCSPullException: ...must specify one of: tag, branch, or commit

Error: empty ref value:

>>> _validate_worktrees_config([{"dir": "../wt", "tag": ""}], "myrepo")
Traceback (most recent call last):
    ...
vcspull.exc.VCSPullException: ...empty ref value...

Error: multiple refs specified:

>>> _validate_worktrees_config(
...     [{"dir": "../wt", "tag": "v1", "branch": "main"}], "myrepo"
... )
Traceback (most recent call last):
    ...
vcspull.exc.VCSPullException: ...cannot specify multiple refs...

vcspull.config.extract_repos(config, cwd=pathlib.Path.cwd)

Return expanded configuration.

end-user configuration permit inline configuration shortcuts, expand to identical format for parsing.

Return type:

list[ConfigDict]

Parameters:

• config (dict) – the repo config in dict format.

• cwd (pathlib.Path) – current working dir (for deciphering relative paths)

Returns:

list

Return type:

List of normalized repository information

vcspull.config.find_home_config_files(filetype=None)

Return configs of .vcspull.{yaml,json} in user’s home directory.

Return type:

list[Path]

Parameters:

filetype (list[str] | None)

vcspull.config.find_config_files(path=None, match=None, filetype=None, include_home=False)

Return repos from a directory and match. Not recursive.

Return type:

list[Path]

Parameters:

• path (list) – list of paths to search

• match (list) – list of globs to search against

• filetype (list) – of filetypes to search against

• include_home (bool) – Include home configuration files

Raises:

LoadConfigRepoConflict : – There are two configs that have same path and name with different repo urls.

Returns:

list of absolute paths to config files.

Return type:

list

vcspull.config.load_configs(files, cwd=pathlib.Path.cwd, *, merge_duplicates=True)

Return repos from a list of files.

Return type:

list[ConfigDict]

Parameters:

• files (list) – paths to config file

• cwd (pathlib.Path) – current path (pass down for extract_repos()

• merge_duplicates (bool)

Returns:

expanded config dict item

Return type:

list of dict

vcspull.config.detect_duplicate_repos(config1, config2)

Return duplicate repos dict if repo_dir same and vcs different.

Return type:

list[tuple[ConfigDict, ConfigDict]]

Parameters:

• config1 (list[ConfigDict])

• config2 (list[ConfigDict])

Returns:

List of duplicate tuples

Return type:

list[tuple[ConfigDict, ConfigDict]]

vcspull.config.in_dir(config_dir=None, extensions=None)

Return a list of configs in config_dir.

Return type:

list[str]

Parameters:

• config_dir (str) – directory to search

• extensions (list) – filetypes to check (e.g. ['.yaml', '.json']).

Return type:

list

vcspull.config.filter_repos(config, path=None, vcs_url=None, name=None)

Return a list list of repos from (expanded) config file.

path, vcs_url and name all support fnmatch.

Return type:

list[ConfigDict]

Parameters:

• config (dict) – the expanded repo config in dict format.

• path (str, Optional) – directory of checkout location, fnmatch pattern supported

• vcs_url (str, Optional) – url of vcs remote, fn match pattern supported

• name (str, Optional) – project name, fnmatch pattern supported

Returns:

Repos

Return type:

list

vcspull.config.is_config_file(filename, extensions=None)

Return True if file has a valid config file type.

Return type:

bool

Parameters:

• filename (str) – filename to check (e.g. mysession.json).

• extensions (list or str) – filetypes to check (e.g. ['.yaml', '.json']).

Returns:

bool

Return type:

True if is a valid config file type

vcspull.config._atomic_write(target, content)

Write content to a file atomically via temp-file-then-rename.

Return type:

None

Parameters:

• target (pathlib.Path) – Destination file path

• content (str) – Content to write

vcspull.config.save_config_yaml(config_file_path, data)

Save configuration data to a YAML file.

Return type:

None

Parameters:

• config_file_path (pathlib.Path) – Path to the configuration file to write

• data (dict) – Configuration data to save

vcspull.config.save_config_json(config_file_path, data)

Save configuration data to a JSON file.

Return type:

None

Parameters:

• config_file_path (pathlib.Path) – Path to the configuration file to write

• data (dict) – Configuration data to save

vcspull.config.save_config_yaml_with_items(config_file_path, items)

Persist configuration data while preserving duplicate top-level sections.

Return type:

None

Parameters:

• config_file_path (Path)

• items (list[tuple[str, Any]])

vcspull.config.merge_duplicate_workspace_root_entries(label, occurrences)

Merge duplicate entries for a single workspace root.

Return type:

tuple[Any, list[str], int]

Parameters:

• label (str)

• occurrences (list[Any])

vcspull.config.merge_duplicate_workspace_roots(config_data, duplicate_roots)

Merge duplicate workspace root sections captured during load.

Return type:

tuple[dict[str, Any], list[str], int, list[tuple[str, int]]]

Parameters:

• config_data (dict[str, Any])

• duplicate_roots (dict[str, list[Any]])

vcspull.config.canonicalize_workspace_path(label, *, cwd=None)

Convert a workspace root label to an absolute canonical path.

Return type:

Path

Parameters:

• label (str)

• cwd (Path | None)

vcspull.config.workspace_root_label(workspace_path, *, cwd=None, home=None, preserve_cwd_label=True)

Create a normalized label for a workspace root path.

Return type:

str

Parameters:

• workspace_path (Path)

• cwd (Path | None)

• home (Path | None)

• preserve_cwd_label (bool)

vcspull.config.normalize_workspace_roots(config_data, *, cwd=None, home=None, preserve_cwd_label=True)

Normalize workspace root labels and merge duplicate sections.

Return type:

tuple[dict[str, Any], dict[Path, str], list[str], int]

Parameters:

• config_data (dict[str, Any])

• cwd (Path | None)

• home (Path | None)

• preserve_cwd_label (bool)