Git-Garden¶
- class git_garden.GitGarden(logger, args, git=None)¶
A simple tool for automating a recursive scan of local git repos to display their status compared to their remote tracking branches with maintenance features such as fetching, pruning, deleting orphaned branches and fast-forwarding.
- Parameters:
logger (
Logger) – Logger to use for output.args (
Namespace) – Command line arguments.git (
Optional[str]) – Path to git executable (attempts to resolve system “git” if not passed).
- Raises:
RuntimeError – If Git installation not found.
- check_branch_remote_only(branch, local_branches, remote_branches)¶
Check whether branch only exists on the remote.
- Parameters:
branch (
str) – Branch to check.local_branches (
List[str]) – List of local branches.remote_branches (
List[str]) – List of remote branches.
- Return type:
bool- Returns:
Whether the branch only exists on the remote or not.
- check_git_status(dir='.')¶
Check status of git working directory.
- Parameters:
dir (
str) – Current directory being processed.- Return type:
bool- Returns:
Working directory is clean (False) or dirty (True).
- create_branch(branch_name, root_branch='main', dir='.')¶
Create a branch within a given git repo.
- Parameters:
branch_name (
str) – Name of the branch to create.root_branch (
str) – Root branch to create from.dir (
str) – Current directory being processed.
- Return type:
int- Returns:
Exit code from branch creation.
- create_commit(message, dir='.')¶
Create a commit on the local branch.
- Parameters:
message (
str) – Commit message.dir (
str) – Current directory being processed.
- Return type:
None
- delete_branch(branch_name, dir='.', branch_type='local')¶
Delete a branch within a given git repo.
- Parameters:
branch_name (
str) – Branch to delete.dir (
str) – Current directory being processed.branch_type (
Literal['local','remote','tracking','all']) – Specify the branch type for deletion.
- Return type:
int- Returns:
Exit code from branch deletion, 0 if branch not found.
- Raises:
ValueError – on unexpected branch_type.
- delete_commit(dir='.')¶
Delete the most recent commit on the local branch.
- Parameters:
dir (
str) – Current directory being processed.- Return type:
None
- fast_forward_branch(dir='.')¶
Attempt to fast-forward the current branch. Failure to fast-forward is not considered fatal.
- Parameters:
dir (
str) – Current directory being processed.- Return type:
int- Returns:
Return code from fast-forward.
- fetch(dir='.', prune=True)¶
Fetch (and optionally prune) remote tracking branches from a given git repo.
- Parameters:
dir (
str) – Current directory being processed.prune (
bool) – If set prune remote tracking branches, otherwise fetch only.
- Return type:
None
- find_current_branch(dir='.')¶
Find the current branch name. Coverage note: This function can’t be tested independently.
- Parameters:
dir (
str) – Current directory being processed.- Return type:
str- Returns:
Current branch name.
- find_root_branch(local_branches, remote_branches)¶
Attempt to find the root branch (main, master or –root) for a given git repo.
- Parameters:
local_branches (
List[str]) – List of local branches.remote_branches (
List[str]) – List of remote branches.
- Return type:
str- Returns:
Root branch name.
- get_dirs_with_depth(dir, depth=3)¶
Recursively search directories for git repos until a given depth.
- Parameters:
dir (
str) – Directory to search.depth (
int) – Depth to search.
- Return type:
List[str]- Returns:
Directories containing git repos.
- list_local_branches(dir='.', upstream=False)¶
List local branches (and optionally their upstream branch status).
- Parameters:
dir (
str) – Current directory being processed.upstream (
bool) – If set include upstream branch status.
- Return type:
List[str]- Returns:
List of local branches.
- list_remote_branches(dir='.', upstream=False)¶
List remote branches.
- Parameters:
dir (
str) – Current directory being processed.upstream (
bool) – If set include upstream branch status.
- Return type:
List[str]- Returns:
List of remote branches.
- main(dirs)¶
Execute the main logic of the script.
- Parameters:
dirs (
List[str]) – Directories containing git repos.- Return type:
None
- parse_branches(stdout, upstream=False)¶
Parse the output of a git branch command.
- Parameters:
stdout (
str) – Output of git branch command.upstream (
bool) – Branches include upstream status.
- Return type:
List[str]- Returns:
List of branches.
- pull_non_current_branch(branch, dir='.')¶
- Parameters:
branch (
str) – Branch to fetch.dir (
str) – Current directory being processed.
- Return type:
int- Returns:
Return code from fetch.
- purge_tracking_branches(dir='.')¶
Recursively purge all remote tracking branches from a given git repo.
- Parameters:
dir (
str) – Current directory being processed.- Return type:
None
- push_branch(branch, force=False, dir='.')¶
Push a branch to the remote.
- Parameters:
branch (
str) – Branch to push.force (
bool) – Switch for force push.dir (
str) – Current directory being processed.
- Return type:
None
- run_and_log(proc_args, check=True, capture=True)¶
Call subprocess.run() and passthrough args & check, returning either the output or the return code. Defaults to same behaviour as subprocess.check_output() (raise on non-zero, return stdout) In all cases log the result to debug.
- Parameters:
proc_args (
List[str]) – The process arguments for subprocess.run().check (
bool) – Whether to raise on non-zero return or not.capture (
bool) – Whether to return output or return code.
- Return type:
int|str- Returns:
Output (str) or return code (int)
- switch_branch(branch, dir='.')¶
Switch to a branch.
- Parameters:
branch (
str) – Branch to push.dir (
str) – Current directory being processed.
- Return type:
str|None- Returns:
Result from branch switch (stdout or None if skipped).