src.utils.git_utils

Module Contents

src.utils.git_utils.logger
src.utils.git_utils.DEFAULT_GIT_CLONE_TIMEOUT_SECONDS = 1800
exception src.utils.git_utils.GitHubApiError(message: str, status_code: int | None = None)

Bases: RuntimeError

Raised when a GitHub API request fails.

status_code = None
exception src.utils.git_utils.RepositoryAccessError(message: str, status_code: int | None = None)

Bases: RuntimeError

Raised when a repository or branch cannot be accessed for analysis.

status_code = None
src.utils.git_utils.extract_repo_path(repo_url: str, provider: str = 'github') → str

Extracts the repository path from a full URL. :param repo_url: Full repository URL (e.g., ‘https://github.com/user/repo’ or ‘user/repo’). :type repo_url: str :param provider: Git provider (“github” or “gitlab”). :type provider: str

Returns:

Repository path (e.g., ‘user/repo’).

Return type:

str

src.utils.git_utils.clone_repository(repo_url: str, token: str, branch: str = 'main', provider: str = 'github') → Generator[str, None, None]

Clone a repository to logs/.clones/ directory and yield the path.

Automatically cleans up the temporary directory when done.

Parameters:

  • repo_url (str) – Repository URL or path (e.g., ‘user/repo’ or ‘https://github.com/user/repo’).

  • token (str) – Authentication token (GitHub or GitLab).

  • branch (str) – Branch to clone. Defaults to ‘main’.

  • provider (str) – Git provider (‘github’ or ‘gitlab’). Defaults to ‘github’.

Yields:

str – Path to the cloned repository directory.

Raises:

RepositoryAccessError – If clone fails.

src.utils.git_utils.list_repository_files(repo_path: str, branch: str = 'main', provider: str = 'github') → List[Dict]

List all files in a local repository using filesystem traversal.

Parameters:

  • repo_path (str) – Path to the local cloned repository.

  • branch (str) – Branch name (unused for local repos, kept for compatibility).

  • provider (str) – Git provider (unused for local repos, kept for compatibility).

Returns:

List of file dicts with ‘name’, ‘path’, and ‘type’ keys.

Return type:

List[Dict]

src.utils.git_utils.get_gitignore_patterns(repo_path: str, access_token: str, branch: str = 'main', provider: str = 'github') → List[str]

DEPRECATED: Use _get_gitignore_patterns_from_local() instead.

This function is kept for backwards compatibility. Fetches .gitignore file from the repository and returns a list of patterns to ignore.

Parameters:

  • repo_path (str) – Repository path (e.g., ‘user/repo’) or local path.

  • access_token (str) – Authentication token (unused if repo_path is local).

  • branch (str, optional) – Branch name. Defaults to “main”.

  • provider (str, optional) – Git provider (“github” or “gitlab”). Defaults to “github”.

Returns:

List of ignore patterns from .gitignore.

Return type:

List[str]

src.utils.git_utils.should_ignore(name: str, patterns: List[str]) → bool

Checks if a file or directory name matches any ignore pattern. :param name: File or directory name. :type name: str :param patterns: List of ignore patterns. :type patterns: List[str]

Returns:

True if the name should be ignored, False otherwise.

Return type:

bool

src.utils.git_utils.read_file_content_from_local(repo_path: str, file_path: str) → str | None

Read file content from a local cloned repository.

Parameters:

  • repo_path (str) – Path to the local cloned repository.

  • file_path (str) – Relative path to the file within the repository.

Returns:

File content if successful, None otherwise.

Return type:

Optional[str]

src.utils.git_utils.read_file_bytes_from_local(repo_path: str, file_path: str) → bytes | None

Read file bytes from a local cloned repository.

Parameters:

  • repo_path (str) – Path to the local cloned repository.

  • file_path (str) – Relative path to the file within the repository.

Returns:

File bytes if successful, None otherwise.

Return type:

Optional[bytes]

src.utils.git_utils.fetch_content_from_github(repo_path: str, branch: str, file_path: str, access_token: str) → str | None

Fetches the raw content of a file from a GitHub repository. :param repo_path: Repository path (e.g., ‘user/repo’). :type repo_path: str :param branch: Branch name. :type branch: str :param file_path: Path to the file in the repository. :type file_path: str :param access_token: GitHub access token. :type access_token: str

Returns:

Raw file content if successful, None otherwise.

Return type:

Optional[str]

src.utils.git_utils.fetch_content_bytes_from_github(repo_path: str, branch: str, file_path: str, access_token: str) → bytes | None

Fetches the raw bytes of a file from a GitHub repository.

src.utils.git_utils.fetch_content_from_gitlab(repo_path: str, branch: str, file_path: str, private_token: str) → str | None

Fetches the raw content of a file from a GitLab repository. :param repo_path: Repository path. :type repo_path: str :param branch: Branch name. :type branch: str :param file_path: Path to the file in the repository. :type file_path: str :param private_token: GitLab private token. :type private_token: str

Returns:

Raw file content if successful, None otherwise.

Return type:

Optional[str]

src.utils.git_utils.fetch_repo_tree(repo_url: str, access_token: str, branch: str = 'main', provider: str = 'github', local_repo_path: str | None = None) → List[Dict]

Get the file tree from a repository.

If local_repo_path is provided, reads from that local directory (for already-cloned repos). Otherwise, clones the repository temporarily and reads the tree (caller must clean up).

Parameters:

  • repo_url (str) – Repository URL or path (e.g., ‘user/repo’ or full URL).

  • access_token (str) – Authentication token.

  • branch (str, optional) – Branch name. Defaults to “main”.

  • provider (str, optional) – Git provider (‘github’ or ‘gitlab’). Defaults to ‘github’.

  • local_repo_path (str, optional) – Path to a pre-cloned local repository. If provided, reads from this directory instead of cloning.

Returns:

List of files and directories in the repository.

Return type:

List[Dict]

Raises:

RepositoryAccessError – If clone or traversal fails.

src.utils.git_utils.validate_docstring(tech_stack: str, repo_path: str, branch: str, file_path: str, access_token: str, provider: str = 'github') → Tuple[bool, List[Dict[str, str]], List[Dict[str, str]]] | None

Validates the presence of docstring in a file based on its technology stack.

Parameters:

  • tech_stack (str) – Technology stack (e.g., “python”).

  • repo_path (str) – Repository path.

  • branch (str) – Branch name.

  • file_path (str) – Path to the file in the repository.

  • access_token (str) – Authentication token.

  • provider (str, optional) – Git provider (“github” or “gitlab”). Defaults to “github”.

Returns:

  • bool: True if docstring is present, False otherwise.

  • List[Dict[str, str]]: Items missing docstring.

  • List[Dict[str, str]]: Items with docstring.

Return type:

Optional[Tuple[bool, List[Dict[str, str]], List[Dict[str, str]]]]

src.utils.git_utils.create_directory_and_add_files(repo_url: str, dir_path: str, file_paths: list, branch: str, token: str, provider: str = 'github') → bool

Creates a new directory in the remote repository and adds multiple files to it in a single commit.

Parameters:

  • repo_url (str) – Repository path (e.g., ‘user/repo’).

  • dir_path (str) – Directory path to create (e.g., ‘autoapi_include’).

  • file_paths (list) – List of file paths in the repo to copy into the new directory.

  • branch (str) – Branch name.

  • token (str) – Access token.

  • provider (str) – ‘github’ or ‘gitlab’.

Returns:

True if operation succeeded, False otherwise.

Return type:

bool

src.utils.git_utils.create_a_file(repo_url, branch, file_path, content, token, provider)

Create or update a file in a specified repository on GitHub or GitLab.

Args:

repo_url (str): The repository URL. branch (str): The branch name. file_path (str): The path of the file to create/update. content (str or bytes): The content to write to the file. token (str): The access token for authentication. provider (str): The service provider (‘github’ or ‘gitlab’).

Returns:

bool: True if the operation was successful, False otherwise.

src.utils.git_utils.ensure_github_branch(repo_url: str, source_branch: str, new_branch: str, token: str) → bool

Ensures a GitHub branch exists by creating it from another branch when needed.

src.utils.git_utils.configure_github_pages(repo_url: str, pages_branch: str, token: str, path: str = '/') → bool

Configures GitHub Pages to publish from a branch without GitHub Actions.

src.utils.git_utils.request_github_pages_build(repo_url: str, token: str) → bool

Requests a GitHub Pages rebuild for a legacy branch-based site.

src.utils.git_utils.list_github_tree(repo_url: str, ref: str, token: str, recursive: bool = True) → List[Dict]

Lists files in a GitHub tree for the given ref.

src.utils.git_utils.download_github_branch_snapshot(repo_url: str, branch: str, token: str, destination_dir: str) → bool

Downloads a GitHub branch snapshot into a local directory.

src.utils.git_utils.create_github_blob(repo_url: str, token: str, content: bytes) → str | None

Creates a GitHub blob and returns its SHA.

src.utils.git_utils.publish_github_directory_to_branch(repo_url: str, source_branch: str, source_dir: str, target_branch: str, token: str, target_dir: str = '') → bool

Copies a built static directory from one branch to another in a single commit.

src.utils.git_utils.publish_local_directory_to_github_branch(repo_url: str, local_dir: str, target_branch: str, token: str, source_branch_for_seed: str, target_dir: str = '') → bool

Publishes a local directory to a GitHub branch in a single commit.

src.utils.git_utils.commit_files_to_github_branch(repo_url: str, branch: str, files: Dict[str, str], token: str, commit_message: str) → bool

Commits multiple text files to an existing GitHub branch.

src.utils.git_utils.create_github_pull_request(repo_url: str, head_branch: str, base_branch: str, title: str, body: str, token: str) → str | None

Opens a GitHub pull request and returns its URL.

src.utils.git_utils.list_open_github_pull_requests(repo_url: str, base_branch: str, token: str) → List[Dict]

Lists open GitHub pull requests targeting the provided base branch.

src.utils.git_utils.list_github_pull_request_files(repo_url: str, pull_number: int, token: str) → List[Dict]

Lists files changed in a GitHub pull request.