CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-pygithub

Comprehensive Python client library providing full access to the GitHub REST API v3 for programmatic management of repositories, users, organizations, issues, pull requests, and other GitHub entities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

git-operations.mddocs/

Git Operations

Low-level Git operations including commit creation, tree manipulation, blob handling, references, and tags. Provides direct access to Git objects and operations for advanced repository management.

Capabilities

Git Commit Operations

Create and manage Git commits with full control over commit metadata and tree structure.

class Repository:
    def get_commits(
        self,
        sha: str = None,
        path: str = None,
        author: str = None,
        since: datetime = None,
        until: datetime = None
    ):
        """
        Get repository commits.
        
        Args:
            sha (str, optional): SHA or branch to start listing from
            path (str, optional): Filter commits touching this path
            author (str, optional): Filter by author
            since (datetime, optional): Only commits after this date
            until (datetime, optional): Only commits before this date
            
        Returns:
            PaginatedList[Commit]: List of commits
        """
    
    def get_commit(self, sha: str):
        """
        Get a specific commit.
        
        Args:
            sha (str): Commit SHA
            
        Returns:
            Commit: Commit object
        """
    
    def create_git_commit(
        self,
        message: str,
        tree: Union[GitTree, str],
        parents: list,
        author: InputGitAuthor = None,
        committer: InputGitAuthor = None
    ):
        """
        Create a Git commit object.
        
        Args:
            message (str): Commit message
            tree (Union[GitTree, str]): Tree object or SHA
            parents (list): List of parent commit SHAs
            author (InputGitAuthor, optional): Commit author
            committer (InputGitAuthor, optional): Commit committer
            
        Returns:
            GitCommit: Created commit object
        """
    
    def compare(self, base: str, head: str):
        """
        Compare two commits, branches, or tags.
        
        Args:
            base (str): Base commit, branch, or tag
            head (str): Head commit, branch, or tag
            
        Returns:
            Comparison: Comparison object with diff information
        """

class Commit:
    @property
    def sha(self) -> str: ...
    @property
    def commit(self) -> GitCommit: ...
    @property
    def author(self) -> NamedUser: ...
    @property
    def committer(self) -> NamedUser: ...
    @property
    def parents(self) -> list: ...
    @property
    def files(self) -> list: ...
    @property
    def stats(self) -> CommitStats: ...
    @property
    def html_url(self) -> str: ...
    
    def get_comments(self):
        """
        Get commit comments.
        
        Returns:
            PaginatedList[CommitComment]: List of comments
        """
    
    def create_comment(self, body: str, line: int = None, path: str = None):
        """
        Create a commit comment.
        
        Args:
            body (str): Comment body
            line (int, optional): Line number to comment on
            path (str, optional): File path to comment on
            
        Returns:
            CommitComment: Created comment
        """
    
    def get_statuses(self):
        """
        Get commit statuses.
        
        Returns:
            PaginatedList[CommitStatus]: List of statuses
        """
    
    def create_status(
        self,
        state: str,
        target_url: str = None,
        description: str = None,
        context: str = None
    ):
        """
        Create a commit status.
        
        Args:
            state (str): Status state ("pending", "success", "error", "failure")
            target_url (str, optional): URL for status details
            description (str, optional): Status description
            context (str, optional): Status context identifier
            
        Returns:
            CommitStatus: Created status
        """

class GitCommit:
    @property
    def sha(self) -> str: ...
    @property
    def message(self) -> str: ...
    @property
    def author(self) -> GitAuthor: ...
    @property
    def committer(self) -> GitAuthor: ...
    @property
    def tree(self) -> GitTree: ...
    @property
    def parents(self) -> list: ...
    @property
    def verification(self) -> GitCommitVerification: ...

Git Tree Operations

Manipulate Git tree objects for advanced file system operations.

class Repository:
    def get_git_tree(self, sha: str, recursive: bool = False):
        """
        Get a Git tree object.
        
        Args:
            sha (str): Tree SHA
            recursive (bool, optional): Recursively fetch sub-trees
            
        Returns:
            GitTree: Tree object
        """
    
    def create_git_tree(self, tree: list, base_tree: str = None):
        """
        Create a Git tree object.  
        
        Args:
            tree (list): List of InputGitTreeElement objects
            base_tree (str, optional): Base tree SHA to build upon
            
        Returns:
            GitTree: Created tree object
        """

class GitTree:
    @property
    def sha(self) -> str: ...
    @property
    def tree(self) -> list: ...  # List of GitTreeElement objects
    @property
    def truncated(self) -> bool: ...

class GitTreeElement:
    @property
    def path(self) -> str: ...
    @property
    def mode(self) -> str: ...
    @property
    def type(self) -> str: ...  # "blob", "tree", "commit"
    @property
    def size(self) -> int: ...
    @property
    def sha(self) -> str: ...
    @property
    def url(self) -> str: ...

class InputGitTreeElement:
    def __init__(
        self,
        path: str,
        mode: str,
        type: str,
        content: str = None,
        sha: str = None
    ):
        """
        Input element for creating Git trees.
        
        Args:
            path (str): File path
            mode (str): File mode ("100644", "100755", "040000", "160000", "120000")
            type (str): Object type ("blob", "tree", "commit")
            content (str, optional): File content (for new files)
            sha (str, optional): Object SHA (for existing objects)
        """

Input Helper Classes

Helper classes for providing structured input to Git and file operations.

class InputFileContent:
    def __init__(self, content: str, new_name: str | None = None):
        """
        Input class for file content operations in gists and other file operations.
        
        Args:
            content (str): File content
            new_name (str, optional): New filename for the content
        """

class InputGitAuthor:
    def __init__(self, name: str, email: str, date: str = None):
        """
        Git author information for commits and tags.
        
        Args:
            name (str): Author name
            email (str): Author email  
            date (str, optional): Date in ISO 8601 format (defaults to current time)
        """

Git Blob Operations

Handle Git blob objects for raw file content storage.

class Repository:
    def get_git_blob(self, sha: str):
        """
        Get a Git blob object.
        
        Args:
            sha (str): Blob SHA
            
        Returns:
            GitBlob: Blob object
        """
    
    def create_git_blob(self, content: str, encoding: str):
        """
        Create a Git blob object.
        
        Args:
            content (str): Blob content
            encoding (str): Content encoding ("utf-8", "base64")
            
        Returns:
            GitBlob: Created blob object
        """

class GitBlob:
    @property
    def sha(self) -> str: ...
    @property
    def content(self) -> str: ...
    @property
    def encoding(self) -> str: ...
    @property
    def size(self) -> int: ...
    @property
    def url(self) -> str: ...

Git Reference Management

Manage Git references including branches, tags, and other refs.

class Repository:
    def get_git_refs(self, subspace: str = None):
        """
        Get Git references.
        
        Args:
            subspace (str, optional): Reference namespace ("heads", "tags", "remotes")
            
        Returns:
            PaginatedList[GitRef]: List of references
        """
    
    def get_git_ref(self, ref: str):
        """
        Get a specific Git reference.
        
        Args:
            ref (str): Reference name (e.g., "heads/main", "tags/v1.0.0")
            
        Returns:
            GitRef: Reference object
        """
    
    def create_git_ref(self, ref: str, sha: str):
        """
        Create a Git reference.
        
        Args:
            ref (str): Reference name
            sha (str): SHA to point to
            
        Returns:
            GitRef: Created reference
        """

class GitRef:
    @property
    def ref(self) -> str: ...
    @property
    def object(self) -> GitObject: ...
    @property
    def url(self) -> str: ...
    
    def edit(self, sha: str, force: bool = False):
        """
        Update the reference.
        
        Args:
            sha (str): New SHA to point to
            force (bool, optional): Force update even if not fast-forward
        """
    
    def delete(self):
        """Delete the reference."""

class GitObject:
    @property
    def sha(self) -> str: ...
    @property
    def type(self) -> str: ...  # "commit", "tree", "blob", "tag"
    @property
    def url(self) -> str: ...

Git Tag Operations

Create and manage Git tag objects for version marking and releases.

class Repository:
    def get_git_tags(self):
        """
        Get Git tag objects.
        
        Returns:
            PaginatedList[GitTag]: List of tag objects
        """
    
    def get_git_tag(self, sha: str):
        """
        Get a specific Git tag object.
        
        Args:
            sha (str): Tag SHA
            
        Returns:
            GitTag: Tag object
        """
    
    def create_git_tag(
        self,
        tag: str,
        message: str,
        object: str,
        type: str,
        tagger: InputGitAuthor = None
    ):
        """
        Create a Git tag object.
        
        Args:
            tag (str): Tag name
            message (str): Tag message
            object (str): SHA of object to tag
            type (str): Type of object ("commit", "tree", "blob")
            tagger (InputGitAuthor, optional): Tag creator
            
        Returns:
            GitTag: Created tag object
        """

class GitTag:
    @property
    def sha(self) -> str: ...
    @property
    def tag(self) -> str: ...
    @property
    def message(self) -> str: ...
    @property
    def tagger(self) -> GitAuthor: ...
    @property
    def object(self) -> GitObject: ...
    @property
    def url(self) -> str: ...

Git Author Information

Handle Git author and committer information for commits and tags.

class GitAuthor:
    @property
    def name(self) -> str: ...
    @property
    def email(self) -> str: ...
    @property
    def date(self) -> datetime: ...

class InputGitAuthor:
    def __init__(self, name: str, email: str, date: str = None):
        """
        Git author information for commits and tags.
        
        Args:
            name (str): Author name
            email (str): Author email
            date (str, optional): Date in ISO 8601 format (defaults to current time)
        """

Comparison and Diff Operations

Compare commits, branches, and view detailed diff information.

class Comparison:
    @property
    def status(self) -> str: ...  # "behind", "ahead", "identical", "diverged"
    @property
    def ahead_by(self) -> int: ...
    @property
    def behind_by(self) -> int: ...
    @property
    def total_commits(self) -> int: ...
    @property
    def commits(self) -> list: ...
    @property
    def files(self) -> list: ...
    @property
    def merge_base_commit(self) -> Commit: ...
    @property
    def diff_url(self) -> str: ...
    @property
    def patch_url(self) -> str: ...
    @property
    def permalink_url(self) -> str: ...

class File:
    @property
    def filename(self) -> str: ...
    @property
    def status(self) -> str: ...  # "added", "removed", "modified", "renamed"
    @property
    def additions(self) -> int: ...
    @property
    def deletions(self) -> int: ...
    @property
    def changes(self) -> int: ...
    @property
    def sha(self) -> str: ...
    @property
    def blob_url(self) -> str: ...
    @property
    def raw_url(self) -> str: ...
    @property
    def contents_url(self) -> str: ...
    @property
    def patch(self) -> str: ...
    @property
    def previous_filename(self) -> str: ...  # For renamed files

Commit Status and Checks

Manage commit statuses for continuous integration and status checks.

class Repository:
    def get_commit_statuses(self, sha: str):
        """
        Get statuses for a commit.
        
        Args:
            sha (str): Commit SHA
            
        Returns:
            PaginatedList[CommitStatus]: List of statuses
        """
    
    def create_commit_status(
        self,
        sha: str,
        state: str,
        target_url: str = None,
        description: str = None,
        context: str = None
    ):
        """
        Create a commit status.
        
        Args:
            sha (str): Commit SHA
            state (str): Status state ("pending", "success", "error", "failure")
            target_url (str, optional): URL with status details
            description (str, optional): Short status description
            context (str, optional): Unique context identifier
            
        Returns:
            CommitStatus: Created status
        """
    
    def get_combined_status(self, ref: str):
        """
        Get combined status for a reference.
        
        Args:
            ref (str): Commit SHA, branch name, or tag name
            
        Returns:
            CommitCombinedStatus: Combined status information
        """

class CommitStatus:
    @property
    def state(self) -> str: ...
    @property
    def target_url(self) -> str: ...
    @property
    def description(self) -> str: ...
    @property
    def context(self) -> str: ...
    @property
    def creator(self) -> NamedUser: ...
    @property
    def created_at(self) -> datetime: ...
    @property
    def updated_at(self) -> datetime: ...

class CommitCombinedStatus:
    @property
    def state(self) -> str: ...
    @property
    def sha(self) -> str: ...
    @property
    def total_count(self) -> int: ...
    @property
    def statuses(self) -> list: ...
    @property
    def repository(self) -> Repository: ...
    @property
    def commit_url(self) -> str: ...

Usage Examples

Creating Files with Git Operations

from github import Github, Auth, InputGitAuthor, InputGitTreeElement
import base64

g = Github(auth=Auth.Token("your_token"))
repo = g.get_repo("owner/repository")

# Get current commit
main_branch = repo.get_branch("main")
base_commit = main_branch.commit

# Create a blob for new file content
content = "Hello, World!"
blob = repo.create_git_blob(content, "utf-8")

# Create tree element for the new file  
tree_element = InputGitTreeElement(
    path="hello.txt",
    mode="100644",  # Regular file
    type="blob",
    sha=blob.sha
)

# Create a new tree with the file
tree = repo.create_git_tree([tree_element], base_commit.commit.tree.sha)

# Create commit
author = InputGitAuthor("Your Name", "your.email@example.com")
commit = repo.create_git_commit(
    message="Add hello.txt file",
    tree=tree.sha,
    parents=[base_commit.sha],
    author=author
)

# Update main branch to point to new commit
ref = repo.get_git_ref("heads/main")
ref.edit(commit.sha)

print(f"Created commit: {commit.sha}")

Working with Multiple Files

# Create multiple files in one commit
files_to_create = [
    {"path": "src/main.py", "content": "print('Hello from main')"},
    {"path": "src/utils.py", "content": "def helper(): pass"},
    {"path": "README.md", "content": "# My Project"}
]

# Create blobs for all files
tree_elements = []
for file_info in files_to_create:
    blob = repo.create_git_blob(file_info["content"], "utf-8")
    tree_elements.append(InputGitTreeElement(
        path=file_info["path"],
        mode="100644",
        type="blob", 
        sha=blob.sha
    ))

# Create tree and commit
tree = repo.create_git_tree(tree_elements, base_commit.commit.tree.sha)
commit = repo.create_git_commit(
    message="Add project structure",
    tree=tree.sha,
    parents=[base_commit.sha],
    author=author
)

# Update branch
ref.edit(commit.sha)

Branch and Tag Management

# Create a new branch
repo.create_git_ref("refs/heads/feature-branch", commit.sha)

# Create an annotated tag
tag = repo.create_git_tag(
    tag="v1.0.0",
    message="Version 1.0.0 release",
    object=commit.sha,
    type="commit",
    tagger=author
)

# Create reference for the tag
repo.create_git_ref("refs/tags/v1.0.0", tag.sha)

print(f"Created tag: {tag.tag}")

Commit Status Management

# Create commit status for CI
status = repo.create_commit_status(
    sha=commit.sha,
    state="pending",
    target_url="https://ci.example.com/builds/123",
    description="Build is running",
    context="continuous-integration/jenkins"
)

# Update status after build completion
status = repo.create_commit_status(
    sha=commit.sha,
    state="success", 
    target_url="https://ci.example.com/builds/123",
    description="Build passed",
    context="continuous-integration/jenkins"
)

# Get all statuses for a commit
statuses = repo.get_commit_statuses(commit.sha)
for status in statuses:
    print(f"{status.context}: {status.state}")

Comparing Commits

# Compare two branches
comparison = repo.compare("main", "feature-branch")
print(f"Status: {comparison.status}")
print(f"Commits ahead: {comparison.ahead_by}")
print(f"Commits behind: {comparison.behind_by}")

# List changed files
for file in comparison.files:
    print(f"{file.status}: {file.filename} (+{file.additions}/-{file.deletions})")

# Get specific commit details
for commit in comparison.commits:
    print(f"Commit: {commit.sha[:8]} - {commit.commit.message}")

Install with Tessl CLI

npx tessl i tessl/pypi-pygithub

docs

authentication.md

git-operations.md

index.md

issues-pull-requests.md

repository-management.md

search-discovery.md

user-organization-management.md

workflows-actions.md

tile.json