clowder.git_project package

Submodules

clowder.git_project.git_repo module

Base Git utility class

class clowder.git_project.git_repo.GitRepo(repo_path: pathlib.Path, remote: str, default_ref: str, parallel: bool = False)

Bases: object

Class encapsulating base git utilities

Variables:
  • repo_path (str) – Absolute path to repo
  • default_ref (str) – Default ref
  • remote (str) – Default remote name
  • parallel (bool) – Whether command is being run in parallel, affects output
  • Optional[repo] (Repo) – Repo instance
add(files: str) → None

Add files to git index

Parameters:files (str) – Files to git add
Raises:ClowderError
checkout(truncated_ref: str, allow_failure: bool = False) → None

Checkout git ref

Parameters:
  • truncated_ref (str) – Ref to git checkout
  • allow_failure (bool) – Whether to allow failing to checkout branch
Raises:

ClowderError

clean(args: str = '') → None

Discard changes for repo

Parameters:args (str) – Git clean options - d Remove untracked directories in addition to untracked files - f Delete directories with .git sub directory or file - X Remove only files ignored by git - x Remove all untracked files
commit(message: str) → None

Commit current changes

Parameters:message (str) – Git commit message
Raises:ClowderError
current_branch() → str

Return currently checked out branch of project

Returns:Name of currently checked out branch
Return type:str
existing_local_branch(branch: str) → bool

Check if local branch exists

Parameters:branch (str) – Branch name
Returns:True, if local branch exists
Return type:bool
existing_remote_branch(branch: str, remote: str) → bool

Check if remote branch exists

Parameters:
  • branch (str) – Branch name
  • remote (str) – Remote name
Returns:

True, if remote branch exists

Return type:

bool

Raises:

ClowderError

fetch(remote: str, ref: Optional[str] = None, depth: int = 0, remove_dir: bool = False, allow_failure: bool = False) → None

Fetch from a specific remote ref

Parameters:
  • remote (str) – Remote name
  • ref (Optional[str]) – Ref to fetch
  • depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
  • remove_dir (bool) – Whether to remove the directory if commands fail
  • allow_failure (bool) – Whether to allow failure
Raises:

ClowderError

format_project_ref_string() → str

Return formatted project ref string

Returns:Formmatted repo ref
Return type:str
format_project_string(path: pathlib.Path) → str

Return formatted project name

Parameters:path (Path) – Relative project path
Returns:Formatted project name
Return type:str
get_current_timestamp() → str

Get current timestamp of HEAD commit

Returns:HEAD commit timestamp
Return type:str
Raises:ClowderError
git_config_add_local(variable: str, value: str) → None

Add local git config value for given variable key

Parameters:
  • variable (str) – Fully qualified git config variable
  • value (str) – Git config value
Raises:

ClowderError

git_config_unset_all_local(variable: str) → None

Unset all local git config values for given variable key

Parameters:variable (str) – Fully qualified git config variable
Raises:ClowderError
install_lfs_hooks() → None

Install git lfs hooks

Raises:ClowderError
is_detached(print_output: bool = False) → bool

Check if HEAD is detached

Parameters:print_output (bool) – Whether to print output
Returns:True, if HEAD is detached
Return type:bool
is_dirty() → bool

Check whether repo is dirty

Returns:True, if repo is dirty
Return type:bool
is_lfs_installed() → bool

Check whether git lfs hooks are installed

Returns:True, if lfs hooks are installed
Return type:bool
new_commits(upstream: bool = False) → int

Returns the number of new commits

Parameters:upstream (bool) – Whether to find number of new upstream or local commits
Returns:Int number of new commits
Return type:int
print_local_branches() → None

Print local git branches

print_remote_branches() → None

Print output if self._print_output is True

print_validation() → None

Print validation messages

pull() → None

Pull upstream changes

Raises:ClowderError
pull_lfs() → None

Pull lfs files

Raises:ClowderError
push() → None

Push changes

Raises:ClowderError
sha(short: bool = False) → str

Return sha for currently checked out commit

Parameters:short (bool) – Whether to return short or long commit sha
Returns:Commit sha
Return type:str
stash() → None

Stash current changes in repository

status() → None

Print git status

Equivalent to: git status

status_verbose() → None

Print git status

Equivalent to: git status -vv

Raises:ClowderError
validate_repo(allow_missing_repo: bool = True) → bool

Validate repo state

Parameters:allow_missing_repo (bool) – Whether to allow validation to succeed with missing repo
Returns:True, if repo not dirty or doesn’t exist on disk
Return type:bool

clowder.git_project.project_repo module

Project Git utility class

class clowder.git_project.project_repo.ProjectRepo(repo_path: pathlib.Path, remote: str, default_ref: str, parallel: bool = False)

Bases: clowder.git_project.project_repo_impl.ProjectRepoImpl

Class encapsulating git utilities for projects

Variables:
  • repo_path (str) – Absolute path to repo
  • default_ref (str) – Default ref
  • remote (str) – Default remote name
  • parallel (bool) – Whether command is being run in parallel, affects output
  • Optional[repo] (Repo) – Repo instance
configure_remotes(upstream_remote_name: str, upstream_remote_url: str, fork_remote_name: str, fork_remote_url: str) → None

Configure remotes names for fork and upstream

Parameters:
  • upstream_remote_name (str) – Upstream remote name
  • upstream_remote_url (str) – Upstream remote url
  • fork_remote_name (str) – Fork remote name
  • fork_remote_url (str) – Fork remote url
Raises:

ClowderError

create_clowder_repo(url: str, branch: str, depth: int = 0) → None

Clone clowder git repo from url at path

Parameters:
  • url (str) – URL of repo
  • branch (str) – Branch name
  • depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
Raises:

ClowderError

herd(url: str, depth: int = 0, fetch: bool = True, rebase: bool = False, config: Optional[Dict[str, str]] = None) → None

Herd ref

Parameters:
  • url (str) – URL of repo
  • depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
  • fetch (bool) – Whether to fetch
  • rebase (bool) – Whether to use rebase instead of pulling latest changes
  • config (Optional[GitConfig]) – Custom git config
herd_branch(url: str, branch: str, depth: int = 0, rebase: bool = False, fork_remote: Optional[str] = None, config: Optional[Dict[str, str]] = None) → None

Herd branch

Parameters:
  • url (str) – URL of repo
  • branch (str) – Branch name
  • depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
  • rebase (bool) – Whether to use rebase instead of pulling latest changes
  • fork_remote (Optional[str]) – Fork remote name
  • config (Optional[GitConfig]) – Custom git config
herd_remote(url: str, remote: str, branch: Optional[str] = None) → None

Herd remote repo

Parameters:
  • url (str) – URL of repo
  • remote (str) – Remote name
  • branch (Optional[str]) – Branch name
herd_tag(url: str, tag: str, depth: int = 0, rebase: bool = False, config: Optional[Dict[str, str]] = None) → None

Herd tag

Parameters:
  • url (str) – URL of repo
  • tag (str) – Tag name
  • depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
  • rebase (bool) – Whether to use rebase instead of pulling latest changes
  • config (Optional[GitConfig]) – Custom git config
install_project_git_herd_alias() → None

Install ‘git herd’ alias for project

prune_branch_local(branch: str, force: bool) → None

Prune local branch

Parameters:
  • branch (str) – Branch name to delete
  • force (bool) – Force delete branch
Raises:

ClowderError

prune_branch_remote(branch: str, remote: str) → None

Prune remote branch in repository

Parameters:
  • branch (str) – Branch name to delete
  • remote (str) – Remote name
Raises:

ClowderError

reset(depth: int = 0) → None

Reset branch to upstream or checkout tag/sha as detached HEAD

Parameters:depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
Raises:ClowderError
reset_timestamp(timestamp: str, author: str, ref: str) → None

Reset branch to upstream or checkout tag/sha as detached HEAD

Parameters:
  • timestamp (str) – Commit ref timestamp
  • author (str) – Commit author
  • ref (str) – Reference ref
Raises:

ClowderError

start(remote: str, branch: str, depth: int, tracking: bool) → None

Start new branch in repository and checkout

Parameters:
  • remote (str) – Remote name
  • branch (str) – Local branch name to create
  • depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
  • tracking (bool) – Whether to create a remote branch with tracking relationship
Raises:

ClowderError

clowder.git_project.project_repo_impl module

Project Git abstract utility class

class clowder.git_project.project_repo_impl.ProjectRepoImpl(repo_path: pathlib.Path, remote: str, default_ref: str, parallel: bool = False)

Bases: clowder.git_project.git_repo.GitRepo

Abstract class encapsulating private git utilities for projects

Variables:
  • repo_path (str) – Absolute path to repo
  • default_ref (str) – Default ref
  • remote (str) – Default remote name
  • parallel (bool) – Whether command is being run in parallel, affects output
  • Optional[repo] (Repo) – Repo instance

clowder.git_project.project_repo_recursive module

Project Git utility class with submodules

class clowder.git_project.project_repo_recursive.ProjectRepoRecursive(repo_path: pathlib.Path, remote: str, default_ref: str, parallel: bool = False)

Bases: clowder.git_project.project_repo.ProjectRepo

Class encapsulating git utilities for projects with submodules

Variables:
  • repo_path (strt) – Absolute path to repo
  • default_ref (strt) – Default ref
  • remote (strt) – Default remote name
  • parallel (bool) – Whether command is being run in parallel, affects output
  • Optional[repo] (Repo) – Repo instance
clean(args: str = '') → None

Discard changes for repo and submodules

Parameters:args (str) – Git clean options - d Remove untracked directories in addition to untracked files - f Delete directories with .git sub directory or file - X Remove only files ignored by git - x Remove all untracked files
has_submodules() → bool

Repo has submodules

Returns:True, if repo has submodules
Return type:bool
herd(url: str, depth: int = 0, fetch: bool = True, rebase: bool = False, config: Optional[Dict[str, str]] = None) → None

Herd ref

Parameters:
  • url (str) – URL of repo
  • depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
  • fetch (bool) – Whether to fetch
  • rebase (bool) – Whether to use rebase instead of pulling latest changes
  • config (Optional[GitConfig]) – Custom git config
herd_branch(url: str, branch: str, depth: int = 0, rebase: bool = False, fork_remote: Optional[str] = None, config: Optional[Dict[str, str]] = None) → None

Herd branch

Parameters:
  • url (str) – URL of repo
  • branch (str) – Branch name
  • depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
  • rebase (bool) – Whether to use rebase instead of pulling latest changes
  • fork_remote (Optional[str]) – Fork remote name
  • config (Optional[GitConfig]) – Custom git config
herd_tag(url: str, tag: str, depth: int = 0, rebase: bool = False, config: Optional[Dict[str, str]] = None) → None

Herd tag

Parameters:
  • url (str) – URL of repo
  • tag (str) – Tag name
  • depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
  • rebase (bool) – Whether to use rebase instead of pulling latest changes
  • config (Optional[GitConfig]) – Custom git config
is_dirty_submodule(path: str) → bool

Check whether submodule repo is dirty

Parameters:path (str) – Submodule path
Returns:True, if submodule at path is dirty
Return type:bool
submodule_update_recursive(depth: int = 0) → None

Update submodules recursively and initialize if not present

Parameters:depth (int) – Git clone depth. 0 indicates full clone, otherwise must be a positive integer
validate_repo(allow_missing_repo: bool = True) → bool

Validate repo state

Parameters:allow_missing_repo (bool) – Whether to allow validation to succeed with missing repo
Returns:True, if repo and submodules not dirty or repo doesn’t exist on disk
Return type:bool

clowder.git_project.util module

Clowder git utilities

clowder.git_project.util.check_ref_format(ref: str) → bool

Check if git ref is correctly formatted

Parameters:ref (str) – Git ref
Returns:True, if git ref is a valid format
Return type:bool
clowder.git_project.util.existing_git_repository(path: pathlib.Path) → bool

Check if a git repository exists

Parameters:path (Path) – Repo path
Returns:True, if .git directory exists inside path
Return type:bool
clowder.git_project.util.existing_git_submodule(path: pathlib.Path) → bool

Check if a git submodule exists

Parameters:path (Path) – Submodule path
Returns:True, if .git file exists inside path
Return type:bool
clowder.git_project.util.format_git_branch(branch: str) → str

Returns properly formatted git branch

Parameters:branch (str) – Git branch name
Returns:Branch prefixed with ‘refs/heads/’
Return type:str
clowder.git_project.util.format_git_tag(tag: str) → str

Returns properly formatted git tag

Parameters:tag (str) – Git tag name
Returns:Tag prefixed with ‘refs/heads/’
Return type:str
clowder.git_project.util.git_url(protocol: str, url: str, name: str) → str

Return git url

Parameters:
  • protocol (str) – Git protocol (‘ssh’ or ‘https’)
  • url (str) – Repo url
  • name (str) – Repo name
Returns:

Full git repo url for specified protocol

Return type:

str

Raises:

ClowderError

clowder.git_project.util.not_detached(func)

If HEAD is detached, print error message and exit

clowder.git_project.util.ref_type(ref: str) → str

Return branch, tag, sha, or unknown ref type

Parameters:ref (str) – Full pathspec
Returns:‘branch’, ‘tag’, ‘sha’, or ‘unknown’
Return type:str
clowder.git_project.util.truncate_ref(ref: str) → str

Return bare branch, tag, or sha

Parameters:ref (str) – Full pathspec or short ref
Returns:Ref with ‘refs/heads/’ and ‘refs/tags/’ prefix removed
Return type:str

Module contents

clowder.git_project module __init__