tessl/pypi-pygit2

Python bindings for libgit2 providing comprehensive Git repository operations and version control functionality.

—

Pending

Overview

Eval results

Files

References and Branches

Name: tessl/pypi-pygit2
Author: tessl

Git reference and branch management including creation, deletion, and iteration. Handles both local and remote references, providing object-oriented access to Git's reference system.

Capabilities

Reference Management

References are named pointers to Git objects, forming the basis of branches, tags, and other named references.

class Reference:
    @property
    def name(self) -> str:
        """Full reference name (e.g., 'refs/heads/main')"""
    
    @property
    def shorthand(self) -> str:
        """Short reference name (e.g., 'main')"""
    
    @property
    def target(self) -> Oid | str:
        """Reference target (OID for direct, name for symbolic)"""
    
    @property
    def type(self) -> int:
        """Reference type (GIT_REF_OID or GIT_REF_SYMBOLIC)"""
    
    @property
    def is_valid_name(self) -> bool:
        """True if reference name is valid"""
    
    def resolve(self) -> Reference:
        """Resolve symbolic reference to direct reference"""
    
    def delete(self):
        """Delete this reference"""
    
    def rename(self, new_name: str) -> Reference:
        """Rename reference"""
    
    def set_target(self, target: Oid | str, message: str = None) -> Reference:
        """Update reference target"""
    
    def log(self) -> list[RefLogEntry]:
        """Get reference log entries"""
    
    def peel(self, object_type: int = None) -> Object:
        """Peel reference to object"""

# Reference Type Constants
GIT_REF_INVALID: int    # Invalid reference
GIT_REF_OID: int        # Direct reference (points to OID)
GIT_REF_SYMBOLIC: int   # Symbolic reference (points to name)

# Reference Filter Constants  
GIT_REFERENCES_BRANCHES: int  # Branch references only
GIT_REFERENCES_TAGS: int      # Tag references only
GIT_REFERENCES_ALL: int       # All references

Reference Collection

The References collection provides access to all repository references with iteration and filtering capabilities.

class References:
    def create(
        self,
        name: str,
        target: Oid | str,
        force: bool = False,
        message: str = None
    ) -> Reference:
        """
        Create new reference.
        
        Parameters:
        - name: Reference name
        - target: Target OID or symbolic name
        - force: Overwrite existing reference
        - message: Reflog message
        
        Returns:
        Reference object
        """
    
    def delete(self, name: str):
        """Delete reference by name"""
    
    def get(self, name: str) -> Reference:
        """Get reference by name"""
    
    def __getitem__(self, name: str) -> Reference:
        """Get reference by name"""
    
    def __contains__(self, name: str) -> bool:
        """Check if reference exists"""
    
    def __iter__(self):
        """Iterate over all references"""
    
    def __len__(self) -> int:
        """Number of references"""
    
    def objects(self, flag: int = GIT_REFERENCES_ALL):
        """Iterate filtered references"""
    
    def compress(self):
        """Compress loose references into packed-refs"""

Branch Management

Branches are a special type of reference with additional metadata and operations.

class Branch(Reference):
    @property
    def branch_name(self) -> str:
        """Branch name without refs/heads/ prefix"""
    
    @property
    def upstream(self) -> Branch | None:
        """Upstream tracking branch"""
    
    @property
    def upstream_name(self) -> str | None:
        """Name of upstream branch"""
    
    @property
    def is_head(self) -> bool:
        """True if this branch is current HEAD"""
    
    @property
    def is_checked_out(self) -> bool:
        """True if branch is checked out"""
    
    def set_upstream(self, upstream: Branch | str):
        """Set upstream tracking branch"""
    
    def unset_upstream(self):
        """Remove upstream tracking"""

class Branches:
    def create(
        self,
        name: str,
        commit: Commit | Oid,
        force: bool = False
    ) -> Branch:
        """
        Create new branch.
        
        Parameters:
        - name: Branch name
        - commit: Target commit
        - force: Overwrite existing branch
        
        Returns:
        Branch object
        """
    
    def delete(self, name: str):
        """Delete branch"""
    
    def get(self, name: str) -> Branch:
        """Get branch by name"""
    
    def __getitem__(self, name: str) -> Branch:
        """Get branch by name"""
    
    def __contains__(self, name: str) -> bool:
        """Check if branch exists"""
    
    def __iter__(self):
        """Iterate over local branches"""
    
    def local(self):
        """Iterate over local branches"""
    
    def remote(self):
        """Iterate over remote branches"""
    
    @property
    def with_commit(self, commit: Oid):
        """Get branches containing commit"""

# Branch Type Constants
GIT_BRANCH_LOCAL: int   # Local branches
GIT_BRANCH_REMOTE: int  # Remote branches  
GIT_BRANCH_ALL: int     # All branches

Reference Log

RefLog tracks changes to references over time.

class RefLogEntry:
    @property
    def id_old(self) -> Oid:
        """Previous OID"""
    
    @property
    def id_new(self) -> Oid:
        """New OID"""
    
    @property
    def committer(self) -> Signature:
        """Committer who made change"""
    
    @property
    def message(self) -> str:
        """Reflog message"""

Revision Parsing

Parse revision specifications into Git objects.

def revparse_single(repo: Repository, spec: str) -> Object:
    """Parse revision spec to single object"""

def revparse(repo: Repository, spec: str) -> RevSpec:
    """Parse revision spec"""

class RevSpec:
    @property
    def from_object(self) -> Object:
        """Start object for range"""
    
    @property  
    def to_object(self) -> Object:
        """End object for range"""
    
    @property
    def flags(self) -> int:
        """RevSpec flags"""

# RevSpec Flag Constants
GIT_REVSPEC_SINGLE: int      # Single object
GIT_REVSPEC_RANGE: int       # Range of objects
GIT_REVSPEC_MERGE_BASE: int  # Merge base

Usage Examples

Working with References

import pygit2

repo = pygit2.Repository('/path/to/repo')

# List all references
for ref in repo.references:
    print(f"{ref.name} -> {ref.target}")

# Create new reference
commit = repo[repo.head.target]
new_ref = repo.references.create('refs/heads/feature', commit.oid)

# Get specific reference
main_ref = repo.references['refs/heads/main']
print(f"Main branch points to: {main_ref.target}")

# Update reference
new_commit = repo.revparse_single('HEAD~1')
main_ref.set_target(new_commit.oid, "Reset to previous commit")

# Delete reference
repo.references.delete('refs/heads/old-feature')

Branch Operations

# List branches
print("Local branches:")
for branch in repo.branches.local:
    marker = " (HEAD)" if branch.is_head else ""
    upstream = f" -> {branch.upstream_name}" if branch.upstream else ""
    print(f"  {branch.branch_name}{marker}{upstream}")

print("\nRemote branches:")
for branch in repo.branches.remote:
    print(f"  {branch.branch_name}")

# Create new branch
new_branch = repo.branches.create('feature-branch', repo.head.target)

# Set upstream tracking
origin_main = repo.branches['origin/main']
new_branch.set_upstream(origin_main)

# Switch to branch (checkout)
repo.checkout(new_branch)

# Delete branch
repo.branches.delete('old-feature')

Reference Logs

# View reflog for HEAD
head_ref = repo.references['HEAD']
reflog = head_ref.log()

print("Recent HEAD changes:")
for entry in reflog[:5]:  # Last 5 entries
    print(f"{entry.id_old} -> {entry.id_new}")
    print(f"  {entry.committer.name}: {entry.message}")
    print()

Revision Parsing

# Parse various revision specifications
head_commit = repo.revparse_single('HEAD')
previous_commit = repo.revparse_single('HEAD~1')
tag_commit = repo.revparse_single('v1.0.0')
branch_commit = repo.revparse_single('feature-branch')

# Parse ranges
revspec = repo.revparse('HEAD~5..HEAD')
print(f"Range from {revspec.from_object.oid} to {revspec.to_object.oid}")

# Find merge base
base_commit = repo.revparse_single('main...feature')
print(f"Merge base: {base_commit.oid}")

Advanced Reference Operations

# Find branches containing specific commit
commit_oid = repo.revparse_single('HEAD~3').oid
branches_with_commit = repo.branches.with_commit(commit_oid)
print(f"Branches containing {commit_oid}:")
for branch in branches_with_commit:
    print(f"  {branch.branch_name}")

# Compress loose references
repo.references.compress()

# Validate reference name
if pygit2.reference_is_valid_name('refs/heads/my-feature'):
    print("Valid reference name")

# Resolve symbolic reference
head = repo.references['HEAD']
if head.type == pygit2.GIT_REF_SYMBOLIC:
    resolved = head.resolve()
    print(f"HEAD -> {resolved.name} -> {resolved.target}")

Install with Tessl CLI