gitws.gitws module

Multi Repository Management.

The GitWS class provides a simple facade to all Git Workspace functionality.

class gitws.gitws.GitWS(workspace: Workspace, manifest_path: Path, group_filters: Tuple[str, ...], secho=None, manifest_format_manager: Optional[ManifestFormatManager] = None)[source]

Bases: object

Multi Repository Management.

Parameters:

workspace – The Workspace Representation.
manifest_path – Manifest File Path. Resolved Path.
group_filters – Group Filters.

Keyword Arguments:

secho – click.secho like print method for verbose output.

There are static methods to create a GitWS instances in the different scenarios:

GitWS.from_path(): Create GitWS for EXISTING workspace at path.
GitWS.create(): Create NEW workspace at path and return corresponding GitWS.
GitWS.init(): Initialize NEW Workspace and return corresponding GitWS.
GitWS.clone(): Clone git url, initialize NEW Workspace and return corresponding GitWS.

add(paths: Tuple[Path, ...], force: bool = False, all_: bool = False)[source]

Add paths to index - aka git add.

The given paths are automatically mapped to the corresponding git clones.

Parameters:

paths – Paths to be added.

Keyword Arguments:

force – allow adding otherwise ignored files.
all – add changes from all tracked and untracked files.

property base_path: Path: GitWS Workspace Main Directory (if the workspace has a main project) or GitWS Workspace Directory.

static check_manifest(manifest_path: Path)[source]

Check Manifest at manifest_path.

Read in and evaluate.

Raises:

ManifestNotFoundError – If manifest does not exists.
ManifestError – If manifest is broken.

checkout(paths: Optional[Tuple[Path, ...]] = None, branch: Optional[str] = None, force: bool = False)[source]

Enriched Git Checkout - aka git checkout.

The given paths are automatically mapped to the corresponding git clones.

Keyword Arguments:

paths – Limit Checkout to paths only. Otherwise run checkout on all git clones.
branch – Branch to be checked out.
force – force checkout (throw away local modifications)

static clone(url: str, path: Optional[Path] = None, main_path: Optional[Path] = None, manifest_path: Optional[Path] = None, group_filters: Optional[Tuple[str, ...]] = None, depth: Optional[int] = None, revision: Optional[str] = None, force: bool = False, secho=None) → GitWS[source]

Clone git url, initialize NEW Workspace and return corresponding GitWS.

Parameters:

url – Main Project URL.

Keyword Arguments:

path – Workspace Path. Parent directory of Git Clone Root Directory by default.
main_path – Main Project Path. Twice the URL stem in the current working directory by default.
manifest_path – Manifest File Path. Relative to main_path. Default is git-ws.toml. This value is written to the configuration.
group_filters – Default Group Filters. This value is written to the configuration.
depth – Shallow Clone Depth.
revision – Revision instead of default one.
force – Ignore that the workspace is not empty.
secho – click.secho like print method for verbose output.

clones(skip_main: bool = False, resolve_url: bool = True, reverse: bool = False) → Generator[Clone, None, None][source]

Iterate over Clones.

Keyword Arguments:

skip_main – Skip Main Repository.
resolve_url – Resolve URLs to absolute ones.
reverse – Operate in reverse order.

Yields:

Clone

commit(msg: str, paths: Tuple[Path, ...], all_: bool = False)[source]

Commit - aka git commit.

The given paths are automatically mapped to the corresponding git clones.

Parameters:

msg – Commit Message

Keyword Arguments:

paths – Paths.
all – commit all changed files

static create(path: Path, main_path: Optional[Path] = None, manifest_path: Optional[Path] = None, group_filters: Optional[Tuple[str, ...]] = None, depth: Optional[int] = None, force: bool = False, secho=None) → GitWS[source]

Create NEW workspace at path and return corresponding GitWS.

Parameters:

path – Workspace Path.

Keyword Arguments:

main_path – Main Project Path.
manifest_path – Manifest File Path. Relative to main_path if given, otherwise relative to path. Default is git-ws.toml. This value is written to the configuration.
group_filters – Default Group Filters. This value is written to the configuration.
depth – Shallow Clone Depth.
force – Ignore that the workspace exists.
secho – click.secho like print method for verbose output.

static create_manifest(manifest_path: Path = PosixPath('git-ws.toml')) → Path[source]: Create Manifest File at manifest_path.

deinit(prune: bool = False, force: bool = False)[source]

De-Initialize GitWS.

The workspace is not working anymore after that. The corresponding GitWS instance should be deleted.

Keyword Arguments:

prune – Remove dependencies, including non-project data!
force – Enforce to prune repositories with changes.

diff(paths: Optional[Tuple[Path, ...]] = None)[source]

Enriched Git Diff - aka git diff.

Keyword Arguments:: paths – Limit Git Diff to paths only.

diffstat(paths: Optional[Tuple[Path, ...]] = None) → Generator[DiffStat, None, None][source]

Enriched Git Diff Status - aka git diff --stat.

Keyword Arguments:: paths – Limit Git Diff to paths only.
Yields:: DiffStat

foreach(project_paths: Optional[Tuple[str, ...]] = None, reverse: bool = False, filter_=None) → Generator[Clone, None, None][source]

User Level Clone Iteration.

We are printing the a banner for each clone.

Keyword Arguments:

project_paths – Limit to projects only.
reverse – Operate in reverse order.
filter – Filter Function

Yields:

Clone

static from_path(path: Optional[Path] = None, manifest_path: Optional[Path] = None, group_filters: Optional[Tuple[str, ...]] = None, secho=None) → GitWS[source]

Create GitWS for EXISTING workspace at path.

Keyword Arguments:

path – Path within the workspace (Default is the current working directory).
manifest_path – Manifest File Path. Relative to base_path. Default is taken from Configuration.
group_filters – Group Filters. Default is taken from Configuration.
secho – click.secho like print method for verbose output.

get_deptree(primary=False) → DepNode[source]: Get Dependency Tree.

get_manifest(freeze: bool = False, resolve: bool = False) → Manifest[source]

Get Manifest.

Read the manifest file with the manifest specification and translate to manifest.

Keyword Arguments:

freeze – Determine current SHA of each project and use it as revision.
resolve – Add project specification of all transient dependencies.

get_manifest_spec(freeze: bool = False, resolve: bool = False) → ManifestSpec[source]

Get Manifest Specification.

Read the manifest file with the manifest specification.

Keyword Arguments:

freeze – Determine current SHA of each project and use it as revision.
resolve – Add project specification of all transient dependencies.

static init(path: Optional[Path] = None, main_path: Optional[Path] = None, manifest_path: Optional[Path] = None, group_filters: Optional[Tuple[str, ...]] = None, depth: Optional[int] = None, force: bool = False, secho=None) → GitWS[source]

Initialize NEW Workspace and return corresponding GitWS.

Keyword Arguments:

path – Workspace Path. Parent directory of the main git clone directory or current working directory by default.
main_path – Main Project Path.
manifest_path – Manifest File Path. Relative to main_path. Default is git-ws.toml. This value is written to the configuration.
group_filters – Default Group Filters. This value is written to the configuration.
depth – Shallow Clone Depth.
force – Ignore that the workspace exists.
secho – click.secho like print method for verbose output.

This method has different modes depending on main_path and the current working directory:

if main_path refers to a git clone, it is taken as main project.
if main_path is None but the current working directory contains a git clone, it is taken as main project
if main_path is None and the current working directory does not contain a git clone, the workspace is initialized without main project.

property main_path: Optional[Path]: GitWS Workspace Main Directory.

manifests() → Generator[Manifest, None, None][source]: Iterate Over Manifests In Current Workspace.

property path: Path: GitWS Workspace Root Directory.

projects(skip_main: bool = False, resolve_url: bool = False) → Generator[Project, None, None][source]

Iterate Over Projects In Current Workspace.

Keyword Arguments:

skip_main – Skip Main Repository.
resolve_url – Resolve URLs to absolute ones.

Yields:

Project

reset(paths: Tuple[Path, ...])[source]

Reset paths - aka git reset.

The given paths are automatically mapped to the corresponding git clones.

rm(paths: Tuple[Path, ...], cached: bool = False, force: bool = False, recursive: bool = False)[source]

Remove paths - aka git rm.

The given paths are automatically mapped to the corresponding git clones.

Parameters:

paths – Files and/or Directories.

Keyword Arguments:

cached – only remove from the index
force – override the up-to-date check
recursive – allow recursive removal

run_foreach(command, project_paths: Optional[Tuple[str, ...]] = None, reverse: bool = False, filter_=None)[source]

Run command on each clone.

Parameters:

command – Command to run

Keyword Arguments:

project_paths – Limit to projects only.
reverse – Operate in reverse order.
filter – Filter Function

status(paths: Optional[Tuple[Path, ...]] = None, banner: bool = False, branch: bool = False) → Generator[Status, None, None][source]

Enriched Git Status - aka git status.

The given paths are automatically mapped to the corresponding git clones.

Keyword Arguments:

paths – Limit Git Status to paths only.
banner – Display Banner For Every Dependency.
branch – Dump branch information.

Yields:

Status

tag(name: str, msg: Optional[str] = None, force: bool = False)[source]

Create Git Tag name with msg.

The following steps are done to create a valid tag:

store a frozen manifest to main_path/.git-ws/manifests/<name>.toml
commit frozen manifest from main_path/.git-ws/manifests/<name>.toml
create git tag.

update(project_paths: Optional[Tuple[str, ...]] = None, skip_main: bool = False, prune: bool = False, rebase: bool = False, force: bool = False)[source]

Create/Update all dependent projects.

Missing dependencies are cloned.
Existing dependencies are fetched.
Checkout revision from manifest
Merge latest upstream changes.

Keyword Arguments:

project_paths – Limit operation to these projects.
skip_main – Exclude main project.
prune – Remove obsolete files from workspace, including non-project data!
rebase – Rebase instead of merge.
force – Enforce to prune repositories with changes.

update_manifest(recursive: bool = False, revision: bool = False, url: bool = False)[source]

Update Manifest.

Keyword Arguments:

recursive – Update dependencies too.
revision – Update Revisions.
url – Update URL.