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: -
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:
-
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:
-
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:
-
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:
-
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: -
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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
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:
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: -
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:
-
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__