Porcelain API

def init(
    path: str = ".",
    bare: bool = False,
    **kwargs
) -> Repo:
    """
    Initialize a new Git repository.
    
    Parameters:
    - path: Path where to create the repository
    - bare: Create a bare repository (no working tree)
    
    Returns:
    Repo object for the new repository
    """

def clone(
    source: str,
    target: str = None,
    bare: bool = False,
    checkout: bool = None,
    errstream: BinaryIO = None,
    outstream: BinaryIO = None,
    origin: str = "origin",
    depth: int = None,
    branch: str = None,
    progress: Callable = None,
    **kwargs
) -> Repo:
    """
    Clone a Git repository.
    
    Parameters:
    - source: URL or path of source repository
    - target: Local directory for cloned repository
    - bare: Create bare clone
    - checkout: Whether to checkout HEAD after clone
    - branch: Branch to clone
    - depth: Create shallow clone with specified depth
    - progress: Progress callback function
    
    Returns:
    Repo object for cloned repository
    """

def open_repo(path: str = ".") -> Repo:
    """
    Open an existing Git repository.
    
    Parameters:
    - path: Path to repository
    
    Returns:
    Repo object
    """

def open_repo_closing(path: str = "."):
    """
    Context manager for opening a repository that automatically closes it.
    
    Parameters:
    - path: Path to repository
    
    Returns:
    Context manager yielding Repo object
    """

def add(
    repo,
    paths: List[str] = None,
    **kwargs
) -> None:
    """
    Add files to the staging area.
    
    Parameters:
    - repo: Repository object or path
    - paths: List of file paths to add
    """

def remove(
    repo,
    paths: List[str],
    cached: bool = False,
    **kwargs
) -> None:
    """
    Remove files from repository and/or working tree.
    
    Parameters:
    - repo: Repository object or path
    - paths: List of file paths to remove
    - cached: Only remove from index, keep in working tree
    """

def mv(
    repo,
    sources: List[str],
    destination: str,
    **kwargs
) -> None:
    """
    Move or rename files in the repository.
    
    Parameters:
    - repo: Repository object or path  
    - sources: Source file paths
    - destination: Destination path
    """

def clean(
    repo,
    target_dir: str = None,
    dry_run: bool = False,
    **kwargs
) -> List[str]:
    """
    Remove untracked files from working tree.
    
    Parameters:
    - repo: Repository object or path
    - target_dir: Directory to clean (default: repository root)
    - dry_run: Show what would be deleted without doing it
    
    Returns:
    List of files that were (or would be) removed
    """

def commit(
    repo,
    message: str = None,
    author: str = None,
    committer: str = None,
    encoding: str = "utf-8",
    no_verify: bool = False,
    **kwargs
) -> bytes:
    """
    Create a new commit.
    
    Parameters:
    - repo: Repository object or path
    - message: Commit message
    - author: Author in format "Name <email>"
    - committer: Committer in format "Name <email>"
    - encoding: Text encoding for commit message
    - no_verify: Skip pre-commit and commit-msg hooks
    
    Returns:
    SHA-1 hash of created commit
    """

def commit_tree(
    repo,
    tree: bytes,
    message: str,
    parents: List[bytes] = None,
    author: str = None,
    committer: str = None,
    **kwargs
) -> bytes:
    """
    Create commit object from tree.
    
    Parameters:
    - repo: Repository object or path
    - tree: Tree SHA-1 hash
    - message: Commit message
    - parents: List of parent commit SHA-1 hashes
    - author: Author in format "Name <email>"
    - committer: Committer in format "Name <email>"
    
    Returns:
    SHA-1 hash of created commit
    """

def branch_create(
    repo,
    name: str,
    objectish: str = "HEAD",
    **kwargs
) -> None:
    """
    Create a new branch.
    
    Parameters:
    - repo: Repository object or path
    - name: Branch name
    - objectish: Starting point (commit, branch, or tag)
    """

def branch_delete(
    repo,
    name: str,
    **kwargs
) -> None:
    """
    Delete a branch.
    
    Parameters:
    - repo: Repository object or path
    - name: Branch name to delete
    """

def branch_list(repo) -> List[bytes]:
    """
    List all branches.
    
    Parameters:
    - repo: Repository object or path
    
    Returns:
    List of branch names
    """

def active_branch(repo) -> bytes:
    """
    Get the currently active branch.
    
    Parameters:
    - repo: Repository object or path
    
    Returns:
    Current branch name
    """

def checkout(
    repo,
    committish: str = None,
    **kwargs
) -> None:
    """
    Checkout files or switch branches.
    
    Parameters:
    - repo: Repository object or path
    - committish: Branch, tag, or commit to checkout
    """

def checkout_branch(
    repo,
    name: str,
    **kwargs
) -> None:
    """
    Checkout a specific branch.
    
    Parameters:
    - repo: Repository object or path
    - name: Branch name to checkout
    """

def push(
    repo,
    remote_location: str = None,
    refspecs: List[str] = None,
    outstream: BinaryIO = None,
    errstream: BinaryIO = None,
    progress: Callable = None,
    **kwargs
) -> Dict[bytes, str]:
    """
    Push changes to remote repository.
    
    Parameters:
    - repo: Repository object or path
    - remote_location: Remote URL or name
    - refspecs: List of refspecs to push
    - progress: Progress callback function
    
    Returns:
    Dictionary mapping refs to push status
    """

def pull(
    repo,
    remote_location: str = None,
    refspecs: List[str] = None,
    outstream: BinaryIO = None,
    errstream: BinaryIO = None,
    fast_forward_only: bool = False,
    **kwargs
) -> None:
    """
    Pull changes from remote repository.
    
    Parameters:
    - repo: Repository object or path
    - remote_location: Remote URL or name
    - refspecs: List of refspecs to pull
    - fast_forward_only: Only allow fast-forward merges
    """

def fetch(
    repo,
    remote_location: str = None,
    refspecs: List[str] = None,
    outstream: BinaryIO = None,
    errstream: BinaryIO = None,
    progress: Callable = None,
    **kwargs
) -> Dict[bytes, bytes]:
    """
    Fetch changes from remote repository.
    
    Parameters:
    - repo: Repository object or path
    - remote_location: Remote URL or name
    - refspecs: List of refspecs to fetch
    - progress: Progress callback function
    
    Returns:
    Dictionary mapping remote refs to local refs
    """

def remote_add(
    repo,
    name: str,
    url: str,
    **kwargs
) -> None:
    """
    Add a remote repository.
    
    Parameters:
    - repo: Repository object or path
    - name: Remote name
    - url: Remote URL
    """

def remote_remove(
    repo,
    name: str,
    **kwargs
) -> None:
    """
    Remove a remote repository.
    
    Parameters:
    - repo: Repository object or path
    - name: Remote name to remove
    """

def ls_remote(
    remote: str,
    **kwargs
) -> Dict[bytes, bytes]:
    """
    List remote references.
    
    Parameters:
    - remote: Remote URL
    
    Returns:
    Dictionary mapping ref names to SHA-1 hashes
    """

def status(repo) -> PorterStatus:
    """
    Get repository status.
    
    Parameters:
    - repo: Repository object or path
    
    Returns:
    PorterStatus object with staged, unstaged, and untracked files
    """

def log(
    repo,
    paths: List[str] = None,
    outstream: BinaryIO = None,
    max_entries: int = None,
    reverse: bool = False,
    name_status: bool = False,
    **kwargs
) -> None:
    """
    Show commit history.
    
    Parameters:
    - repo: Repository object or path
    - paths: Limit to specific paths
    - outstream: Output stream for log
    - max_entries: Maximum number of entries to show
    - reverse: Show in reverse chronological order
    - name_status: Show file change status
    """

def show(
    repo,
    objects: List[str] = None,
    outstream: BinaryIO = None,
    **kwargs
) -> None:
    """
    Show object contents.
    
    Parameters:
    - repo: Repository object or path
    - objects: List of objects to show
    - outstream: Output stream
    """

def diff(
    repo,
    paths: List[str] = None,
    outstream: BinaryIO = None,
    **kwargs
) -> None:
    """
    Show differences between commits, commit and working tree, etc.
    
    Parameters:
    - repo: Repository object or path
    - paths: Limit to specific paths
    - outstream: Output stream for diff
    """

def describe(
    repo,
    committish: str = "HEAD",
    **kwargs
) -> str:
    """
    Describe a commit using the most recent tag.
    
    Parameters:
    - repo: Repository object or path
    - committish: Commit to describe
    
    Returns:
    Description string
    """

def tag_create(
    repo,
    tag: str,
    author: str = None,
    message: str = None,
    annotated: bool = False,
    objectish: str = "HEAD",
    tag_time: int = None,
    tag_timezone: int = None,
    sign: bool = False,
    **kwargs
) -> Tag:
    """
    Create a new tag.
    
    Parameters:
    - repo: Repository object or path
    - tag: Tag name
    - author: Author in format "Name <email>"
    - message: Tag message (for annotated tags)
    - annotated: Create annotated tag
    - objectish: Object to tag
    - sign: Sign the tag with GPG
    
    Returns:
    Tag object
    """

def tag_delete(
    repo,
    name: str,
    **kwargs
) -> None:
    """
    Delete a tag.
    
    Parameters:
    - repo: Repository object or path
    - name: Tag name to delete
    """

def tag_list(
    repo,
    outstream: BinaryIO = None,
    **kwargs
) -> List[bytes]:
    """
    List all tags.
    
    Parameters:
    - repo: Repository object or path
    - outstream: Output stream for tag list
    
    Returns:
    List of tag names
    """

def stash_list(repo) -> List[bytes]:
    """
    List all stashes.
    
    Parameters:
    - repo: Repository object or path
    
    Returns:
    List of stash references
    """

def stash_push(
    repo,
    message: str = None,
    **kwargs
) -> bytes:
    """
    Save current changes to stash.
    
    Parameters:
    - repo: Repository object or path
    - message: Stash message
    
    Returns:
    Stash reference
    """

def stash_pop(
    repo,
    stash: str = None,
    **kwargs
) -> None:
    """
    Apply and remove a stash.
    
    Parameters:
    - repo: Repository object or path
    - stash: Stash reference (default: most recent)
    """

def stash_drop(
    repo,
    stash: str = None,
    **kwargs
) -> None:
    """
    Delete a stash.
    
    Parameters:
    - repo: Repository object or path
    - stash: Stash reference (default: most recent)
    """

def merge(
    repo: Union[str, os.PathLike, Repo],
    committish: Union[str, bytes, Commit, Tag],
    no_commit: bool = False,
    no_ff: bool = False,
    message: str = None,
    author: str = None,
    committer: str = None,
) -> tuple[bytes, list]:
    """
    Merge a commit into the current branch.
    
    Parameters:
    - repo: Repository object or path
    - committish: Branch or commit to merge
    - no_commit: If True, do not create a merge commit
    - no_ff: If True, force creation of a merge commit
    - message: Optional merge commit message
    - author: Optional author for merge commit
    - committer: Optional committer for merge commit
    
    Returns:
    Tuple of (merge_commit_sha, conflicts)
    """

def merge_tree(
    repo,
    base_tree: Optional[Union[str, bytes, Tree, Commit, Tag]],
    our_tree: Union[str, bytes, Tree, Commit, Tag],
    their_tree: Union[str, bytes, Tree, Commit, Tag],
) -> tuple[bytes, list[bytes]]:
    """
    Perform a three-way tree merge without touching the working directory.
    
    Parameters:
    - repo: Repository containing the trees
    - base_tree: Tree-ish of the common ancestor (or None)
    - our_tree: Tree-ish of our side of the merge
    - their_tree: Tree-ish of their side of the merge
    
    Returns:
    Tuple of (merged_tree_id, conflicts)
    """

def cherry_pick(
    repo: Union[str, os.PathLike, Repo],
    committish: Union[str, bytes, Commit, Tag, None],
    no_commit: bool = False,
    continue_: bool = False,
    abort: bool = False,
) -> bytes:
    """
    Cherry-pick a commit onto the current branch.
    
    Parameters:
    - repo: Repository object or path
    - committish: Commit to cherry-pick
    - no_commit: If True, do not create a commit after applying changes
    - continue_: Continue an in-progress cherry-pick after resolving conflicts
    - abort: Abort an in-progress cherry-pick
    
    Returns:
    SHA of newly created commit, or None if no_commit=True
    """

def revert(
    repo: Union[str, os.PathLike, Repo],
    commits: Union[str, bytes, Commit, Tag, list],
    no_commit: bool = False,
    message: str = None,
    author: str = None,
    committer: str = None,
) -> bytes:
    """
    Revert one or more commits.
    
    Parameters:
    - repo: Repository object or path
    - commits: List of commit-ish to revert, or a single commit-ish
    - no_commit: If True, apply changes but don't commit
    - message: Optional commit message
    - author: Optional author for revert commit
    - committer: Optional committer for revert commit
    
    Returns:
    SHA1 of new revert commit, or None if no_commit=True
    """

def rebase(
    repo: Union[Repo, str],
    upstream: Union[bytes, str],
    onto: Optional[Union[bytes, str]] = None,
    branch: Optional[Union[bytes, str]] = None,
    abort: bool = False,
    continue_rebase: bool = False,
    skip: bool = False,
) -> list[bytes]:
    """
    Rebase commits onto another branch.
    
    Parameters:
    - repo: Repository to rebase in
    - upstream: Upstream branch/commit to rebase onto
    - onto: Specific commit to rebase onto (defaults to upstream)
    - branch: Branch to rebase (defaults to current branch)
    - abort: Abort an in-progress rebase
    - continue_rebase: Continue an in-progress rebase
    - skip: Skip current commit and continue rebase
    
    Returns:
    List of new commit SHAs created by rebase
    """

def reset(
    repo: Union[str, os.PathLike, Repo],
    mode: str,
    treeish: Union[str, bytes, Commit, Tree, Tag] = "HEAD",
) -> None:
    """
    Reset current HEAD to specified state.
    
    Parameters:
    - repo: Repository object or path
    - mode: Reset mode ("soft", "mixed", "hard")
    - treeish: Target tree or commit
    """

def reset_file(
    repo,
    file_path: str,
    target: Union[str, bytes, Commit, Tree, Tag] = b"HEAD",
    symlink_fn = None,
) -> None:
    """
    Reset a specific file to a commit or branch.
    
    Parameters:
    - repo: Repository object
    - file_path: File to reset, relative to repository path
    - target: Branch or commit to reset to
    - symlink_fn: Optional symlink function
    """

def bisect_start(
    repo: Union[str, os.PathLike, Repo] = ".",
    bad: Optional[Union[str, bytes, Commit, Tag]] = None,
    good: Optional[Union[str, bytes, Commit, Tag, list]] = None,
    paths = None,
    no_checkout: bool = False,
    term_bad: str = "bad",
    term_good: str = "good",
) -> bytes:
    """
    Start a new bisect session.
    
    Parameters:
    - repo: Repository object or path
    - bad: The bad commit (defaults to HEAD)
    - good: List of good commits or a single good commit
    - paths: Optional paths to limit bisect to
    - no_checkout: If True, don't checkout commits during bisect
    - term_bad: Term to use for bad commits
    - term_good: Term to use for good commits
    
    Returns:
    SHA of next commit to test
    """

def bisect_bad(
    repo: Union[str, os.PathLike, Repo] = ".",
    rev: Optional[Union[str, bytes, Commit, Tag]] = None,
) -> bytes:
    """
    Mark a commit as bad.
    
    Parameters:
    - repo: Repository object or path
    - rev: Commit to mark as bad (defaults to HEAD)
    
    Returns:
    SHA of next commit to test, or None if bisect is complete
    """

def bisect_good(
    repo: Union[str, os.PathLike, Repo] = ".",
    rev: Optional[Union[str, bytes, Commit, Tag]] = None,
) -> bytes:
    """
    Mark a commit as good.
    
    Parameters:
    - repo: Repository object or path
    - rev: Commit to mark as good (defaults to HEAD)
    
    Returns:
    SHA of next commit to test, or None if bisect is complete
    """

def bisect_skip(
    repo: Union[str, os.PathLike, Repo] = ".",
    revs: Optional[Union[str, bytes, Commit, Tag, list]] = None,
) -> bytes:
    """
    Skip one or more commits during bisect.
    
    Parameters:
    - repo: Repository object or path
    - revs: List of commits to skip (defaults to [HEAD])
    
    Returns:
    SHA of next commit to test, or None if bisect is complete
    """

def bisect_reset(
    repo: Union[str, os.PathLike, Repo] = ".",
    commit: Optional[Union[str, bytes, Commit, Tag]] = None,
) -> None:
    """
    Reset bisect state and return to original branch/commit.
    
    Parameters:
    - repo: Repository object or path
    - commit: Optional commit to reset to (defaults to original branch)
    """

def bisect_log(repo: Union[str, os.PathLike, Repo] = ".") -> str:
    """
    Get the bisect log.
    
    Parameters:
    - repo: Repository object or path
    
    Returns:
    The bisect log as a string
    """

def bisect_replay(repo: Union[str, os.PathLike, Repo], log_file) -> None:
    """
    Replay a bisect log.
    
    Parameters:
    - repo: Repository object or path
    - log_file: Path to log file or file-like object
    """

def notes_add(
    repo,
    object_sha,
    note,
    ref: bytes = b"commits",
    author = None,
    committer = None,
    message = None,
) -> bytes:
    """
    Add or update a note for an object.
    
    Parameters:
    - repo: Repository object or path
    - object_sha: SHA of the object to annotate
    - note: Note content
    - ref: Notes ref to use (defaults to "commits")
    - author: Author identity (defaults to committer)
    - committer: Committer identity (defaults to config)
    - message: Commit message for the notes update
    
    Returns:
    SHA of the new notes commit
    """

def notes_remove(
    repo,
    object_sha,
    ref: bytes = b"commits",
    author = None,
    committer = None,
    message = None,
) -> bytes:
    """
    Remove a note for an object.
    
    Parameters:
    - repo: Repository object or path
    - object_sha: SHA of the object to remove notes from
    - ref: Notes ref to use (defaults to "commits")
    - author: Author identity (defaults to committer)
    - committer: Committer identity (defaults to config)
    - message: Commit message for the notes removal
    
    Returns:
    SHA of new notes commit, or None if no note existed
    """

def notes_show(
    repo: Union[str, os.PathLike, Repo],
    object_sha,
    ref: bytes = b"commits",
) -> bytes:
    """
    Show the note for an object.
    
    Parameters:
    - repo: Repository object or path
    - object_sha: SHA of the object
    - ref: Notes ref to use (defaults to "commits")
    
    Returns:
    Note content as bytes, or None if no note exists
    """

def notes_list(repo: RepoPath, ref: bytes = b"commits") -> list[tuple]:
    """
    List all notes in a notes ref.
    
    Parameters:
    - repo: Repository object or path
    - ref: Notes ref to use (defaults to "commits")
    
    Returns:
    List of tuples of (object_sha, note_content)
    """

def gc(
    repo,
    auto: bool = False,
    aggressive: bool = False,
    prune: bool = True,
    grace_period: Optional[int] = 1209600,
    dry_run: bool = False,
    progress = None,
) -> GCStats:
    """
    Run garbage collection on a repository.
    
    Parameters:
    - repo: Repository object or path
    - auto: If True, only run gc if needed
    - aggressive: If True, use more aggressive settings
    - prune: If True, prune unreachable objects
    - grace_period: Grace period in seconds for pruning (default 2 weeks)
    - dry_run: If True, only report what would be done
    - progress: Optional progress callback
    
    Returns:
    GCStats object with garbage collection statistics
    """

def prune(
    repo,
    grace_period: Optional[int] = None,
    dry_run: bool = False,
    progress = None,
) -> None:
    """
    Prune/clean up a repository's object store.
    
    Parameters:
    - repo: Repository object or path
    - grace_period: Grace period in seconds for removing temporary files
    - dry_run: If True, only report what would be done
    - progress: Optional progress callback
    """

def repack(repo: RepoPath) -> None:
    """
    Repack loose files in a repository.
    
    Parameters:
    - repo: Repository object or path
    """

def pack_objects(
    repo,
    object_ids,
    packf,
    idxf,
    delta_window_size = None,
    deltify = None,
    reuse_deltas: bool = True,
    pack_index_version = None,
) -> None:
    """
    Pack objects into a file.
    
    Parameters:
    - repo: Repository object or path
    - object_ids: List of object ids to write
    - packf: File-like object to write to
    - idxf: File-like object to write to (can be None)
    - delta_window_size: Sliding window size for searching deltas
    - deltify: Whether to deltify objects
    - reuse_deltas: Allow reuse of existing deltas while deltifying
    - pack_index_version: Pack index version to use (1, 2, or 3)
    """

def unpack_objects(pack_path, target: str = ".") -> int:
    """
    Unpack objects from a pack file into the repository.
    
    Parameters:
    - pack_path: Path to the pack file to unpack
    - target: Path to the repository to unpack into
    
    Returns:
    Number of objects unpacked
    """

def count_objects(repo: RepoPath = ".", verbose: bool = False) -> CountObjectsResult:
    """
    Count unpacked objects and their disk usage.
    
    Parameters:
    - repo: Repository object or path
    - verbose: Whether to return verbose information
    
    Returns:
    CountObjectsResult object with detailed statistics
    """

def fsck(repo: RepoPath) -> Iterator[tuple[bytes, Exception]]:
    """
    Check a repository for errors.
    
    Parameters:
    - repo: Repository object or path
    
    Returns:
    Iterator over errors/warnings as (sha, exception) tuples
    """

def archive(
    repo,
    committish: Optional[Union[str, bytes, Commit, Tag]] = None,
    outstream = default_bytes_out_stream,
    errstream = default_bytes_err_stream,
) -> None:
    """
    Create an archive.
    
    Parameters:
    - repo: Repository object or path
    - committish: Commit SHA1 or ref to use
    - outstream: Output stream (defaults to stdout)
    - errstream: Error stream (defaults to stderr)
    """

def update_server_info(repo: RepoPath = ".") -> None:
    """
    Update server info files for a repository.
    
    Parameters:
    - repo: Repository object or path
    """

def write_commit_graph(repo: RepoPath = ".", reachable: bool = True) -> None:
    """
    Write a commit graph file for a repository.
    
    Parameters:
    - repo: Repository object or path
    - reachable: If True, include all commits reachable from refs
    """

def pack_refs(repo: RepoPath, all: bool = False) -> None:
    """
    Pack references into a single file for efficiency.
    
    Parameters:
    - repo: Repository object or path
    - all: Pack all refs, not just heads and tags
    """

def write_tree(repo: RepoPath) -> bytes:
    """
    Write a tree object from the index.
    
    Parameters:
    - repo: Repository for which to write tree
    
    Returns:
    Tree id for the tree that was written
    """

def submodule_add(
    repo: Union[str, os.PathLike, Repo],
    url,
    path = None,
    name = None,
) -> None:
    """
    Add a new submodule.
    
    Parameters:
    - repo: Repository object or path
    - url: URL of repository to add as submodule
    - path: Path where submodule should live
    - name: Name for the submodule
    """

def submodule_init(repo: Union[str, os.PathLike, Repo]) -> None:
    """
    Initialize submodules.
    
    Parameters:
    - repo: Repository object or path
    """

def submodule_list(repo: RepoPath) -> Iterator[tuple[str, str]]:
    """
    List submodules.
    
    Parameters:
    - repo: Repository object or path
    
    Returns:
    Iterator of (path, sha) tuples
    """

def submodule_update(
    repo: Union[str, os.PathLike, Repo],
    paths = None,
    init: bool = False,
    force: bool = False,
    errstream = None,
) -> None:
    """
    Update submodules.
    
    Parameters:
    - repo: Repository object or path
    - paths: Optional list of specific submodule paths to update
    - init: If True, initialize submodules first
    - force: Force update even if local changes exist
    - errstream: Error stream for output
    """

def lfs_init(repo: Union[str, os.PathLike, Repo] = ".") -> None:
    """
    Initialize Git LFS in a repository.
    
    Parameters:
    - repo: Repository object or path
    """

def lfs_track(
    repo: Union[str, os.PathLike, Repo] = ".",
    patterns = None,
) -> list[str]:
    """
    Track file patterns with Git LFS.
    
    Parameters:
    - repo: Repository object or path
    - patterns: List of file patterns to track (e.g., ["*.bin", "*.pdf"])
    
    Returns:
    List of tracked patterns
    """

def lfs_untrack(
    repo: Union[str, os.PathLike, Repo] = ".",
    patterns = None,
) -> list[str]:
    """
    Untrack file patterns from Git LFS.
    
    Parameters:
    - repo: Repository object or path
    - patterns: List of file patterns to untrack
    
    Returns:
    List of remaining tracked patterns
    """

def lfs_clean(
    repo: Union[str, os.PathLike, Repo] = ".",
    path = None,
) -> bytes:
    """
    Clean a file by converting it to an LFS pointer.
    
    Parameters:
    - repo: Repository object or path
    - path: Path to file to clean (relative to repo root)
    
    Returns:
    LFS pointer content as bytes
    """

def lfs_smudge(
    repo: Union[str, os.PathLike, Repo] = ".",
    pointer_content = None,
) -> bytes:
    """
    Smudge an LFS pointer by retrieving the actual content.
    
    Parameters:
    - repo: Repository object or path
    - pointer_content: LFS pointer content as bytes
    
    Returns:
    Actual file content as bytes
    """

def lfs_ls_files(
    repo: Union[str, os.PathLike, Repo] = ".",
    ref = None,
) -> list[tuple[str, str, int]]:
    """
    List files tracked by Git LFS.
    
    Parameters:
    - repo: Repository object or path
    - ref: Git ref to check (defaults to HEAD)
    
    Returns:
    List of (path, oid, size) tuples for LFS files
    """

def lfs_migrate(
    repo: Union[str, os.PathLike, Repo] = ".",
    include = None,
    exclude = None,
    everything: bool = False,
) -> int:
    """
    Migrate files to Git LFS.
    
    Parameters:
    - repo: Repository object or path
    - include: Patterns of files to include
    - exclude: Patterns of files to exclude
    - everything: Migrate all files above a certain size
    
    Returns:
    Number of migrated files
    """

def lfs_fetch(
    repo: Union[str, os.PathLike, Repo] = ".",
    remote: str = "origin",
    refs = None,
) -> int:
    """
    Fetch LFS objects from remote.
    
    Parameters:
    - repo: Repository object or path
    - remote: Remote name (default: origin)
    - refs: Specific refs to fetch LFS objects for (default: all refs)
    
    Returns:
    Number of objects fetched
    """

def lfs_pull(
    repo: Union[str, os.PathLike, Repo] = ".",
    remote: str = "origin",
) -> int:
    """
    Pull LFS objects for current checkout.
    
    Parameters:
    - repo: Repository object or path
    - remote: Remote name (default: origin)
    
    Returns:
    Number of objects fetched
    """

def lfs_push(
    repo: Union[str, os.PathLike, Repo] = ".",
    remote: str = "origin",
    refs = None,
) -> int:
    """
    Push LFS objects to remote.
    
    Parameters:
    - repo: Repository object or path
    - remote: Remote name (default: origin)
    - refs: Specific refs to push LFS objects for
    
    Returns:
    Number of objects pushed
    """

def lfs_status(repo: Union[str, os.PathLike, Repo] = ".") -> dict[str, list[str]]:
    """
    Show status of LFS files.
    
    Parameters:
    - repo: Repository object or path
    
    Returns:
    Dict with status information
    """

def lfs_pointer_check(
    repo: Union[str, os.PathLike, Repo] = ".",
    paths = None,
) -> dict:
    """
    Check if files are valid LFS pointers.
    
    Parameters:
    - repo: Repository object or path
    - paths: List of file paths to check (if None, check all files)
    
    Returns:
    Dict mapping paths to LFSPointer objects
    """

def worktree_list(repo = ".") -> list:
    """
    List all worktrees for a repository.
    
    Parameters:
    - repo: Repository object or path
    
    Returns:
    List of WorkTreeInfo objects
    """

def worktree_add(
    repo = ".",
    path = None,
    branch = None,
    commit = None,
    detach: bool = False,
    force: bool = False,
) -> str:
    """
    Add a new worktree.
    
    Parameters:
    - repo: Repository object or path
    - path: Path for new worktree
    - branch: Branch to checkout (creates if doesn't exist)
    - commit: Specific commit to checkout
    - detach: Create with detached HEAD
    - force: Force creation even if branch is already checked out
    
    Returns:
    Path to the newly created worktree
    """

def worktree_remove(
    repo = ".",
    path = None,
    force: bool = False,
) -> None:
    """
    Remove a worktree.
    
    Parameters:
    - repo: Repository object or path
    - path: Path to worktree to remove
    - force: Force removal even if there are local changes
    """

def worktree_prune(
    repo = ".",
    dry_run: bool = False,
    expire = None,
) -> list[str]:
    """
    Prune worktree administrative files.
    
    Parameters:
    - repo: Repository object or path
    - dry_run: Only show what would be removed
    - expire: Only prune worktrees older than this many seconds
    
    Returns:
    List of pruned worktree names
    """

def worktree_lock(
    repo = ".",
    path = None,
    reason = None,
) -> None:
    """
    Lock a worktree to prevent it from being pruned.
    
    Parameters:
    - repo: Repository object or path
    - path: Path to worktree to lock
    - reason: Optional reason for locking
    """

def worktree_unlock(
    repo = ".",
    path = None,
) -> None:
    """
    Unlock a worktree.
    
    Parameters:
    - repo: Repository object or path
    - path: Path to worktree to unlock
    """

def worktree_move(
    repo = ".",
    old_path = None,
    new_path = None,
) -> None:
    """
    Move a worktree to a new location.
    
    Parameters:
    - repo: Repository object or path
    - old_path: Current path of worktree
    - new_path: New path for worktree
    """

def reflog(
    repo: RepoPath = ".",
    ref: bytes = b"HEAD",
    all: bool = False,
) -> Iterator:
    """
    Show reflog entries for a reference or all references.
    
    Parameters:
    - repo: Repository object or path
    - ref: Reference name (defaults to HEAD)
    - all: If True, show reflogs for all refs
    
    Returns:
    Iterator over ReflogEntry objects or (ref_name, ReflogEntry) tuples
    """

def check_ignore(
    repo: RepoPath,
    paths,
    no_index: bool = False,
    quote_path: bool = True,
) -> Iterator[str]:
    """
    Debug gitignore files.
    
    Parameters:
    - repo: Repository object or path
    - paths: List of paths to check for
    - no_index: Don't check index
    - quote_path: If True, quote non-ASCII characters in returned paths
    
    Returns:
    Iterator over ignored files
    """

def annotate(
    repo: RepoPath,
    path,
    committish: Optional[Union[str, bytes, Commit, Tag]] = None,
) -> list:
    """
    Annotate the history of a file (blame).
    
    Parameters:
    - repo: Repository object or path
    - path: Path to annotate
    - committish: Commit id to find path in
    
    Returns:
    List of ((Commit, TreeChange), line) tuples
    """

def format_patch(
    repo = ".",
    committish = None,
    outstream = sys.stdout,
    outdir = None,
    n: int = 1,
    stdout: bool = False,
    version = None,
) -> list[str]:
    """
    Generate patches suitable for git am.
    
    Parameters:
    - repo: Repository object or path
    - committish: Commit-ish or commit range to generate patches for
    - outstream: Stream to write to if stdout=True
    - outdir: Directory to write patch files to
    - n: Number of patches to generate if committish is None
    - stdout: Write patches to stdout instead of files
    - version: Version string to include in patches
    
    Returns:
    List of patch filenames that were created
    """

def filter_branch(
    repo = ".",
    branch = "HEAD",
    filter_fn = None,
    filter_author = None,
    filter_committer = None,
    filter_message = None,
    tree_filter = None,
    index_filter = None,
    parent_filter = None,
    commit_filter = None,
    subdirectory_filter = None,
    prune_empty: bool = False,
    tag_name_filter = None,
    force: bool = False,
    keep_original: bool = True,
    refs = None,
) -> dict:
    """
    Rewrite branch history by creating new commits with filtered properties.
    
    Parameters:
    - repo: Repository object or path
    - branch: Branch to rewrite (defaults to HEAD)
    - filter_fn: Optional callable to filter commit properties
    - filter_author: Optional callable to filter author
    - filter_committer: Optional callable to filter committer
    - filter_message: Optional callable to filter commit message
    - tree_filter: Optional callable for tree modifications
    - index_filter: Optional callable for index modifications
    - parent_filter: Optional callable to modify parent list
    - commit_filter: Optional callable for commit filtering
    - subdirectory_filter: Optional subdirectory path to extract
    - prune_empty: Whether to prune commits that become empty
    - tag_name_filter: Optional callable to rename tags
    - force: Force operation even if branch has been filtered
    - keep_original: Keep original refs under refs/original/
    - refs: List of refs to rewrite
    
    Returns:
    Dict mapping old commit SHAs to new commit SHAs
    """

def for_each_ref(
    repo: Union[Repo, str] = ".",
    pattern: Optional[Union[str, bytes]] = None,
) -> list[tuple[bytes, bytes, bytes]]:
    """
    Iterate over all refs that match the (optional) pattern.
    
    Parameters:
    - repo: Repository object or path
    - pattern: Optional glob patterns to filter the refs with
    
    Returns:
    List of bytes tuples with: (sha, object_type, ref_name)
    """

def ls_files(repo: RepoPath) -> list[bytes]:
    """
    List all files in an index.
    
    Parameters:
    - repo: Repository object or path
    
    Returns:
    Sorted list of file paths in the index
    """

def ls_tree(
    repo,
    treeish: Union[str, bytes, Commit, Tree, Tag] = b"HEAD",
    outstream = sys.stdout,
    recursive: bool = False,
    name_only: bool = False,
) -> None:
    """
    List contents of a tree.
    
    Parameters:
    - repo: Repository object or path
    - treeish: Tree id to list
    - outstream: Output stream (defaults to stdout)
    - recursive: Whether to recursively list files
    - name_only: Only print item name
    """

def rev_list(
    repo: RepoPath,
    commits,
    outstream = sys.stdout,
) -> None:
    """
    Lists commit objects in reverse chronological order.
    
    Parameters:
    - repo: Repository object or path
    - commits: Commits over which to iterate
    - outstream: Stream to write to
    """

def get_object_by_path(
    repo,
    path,
    committish: Optional[Union[str, bytes, Commit, Tag]] = None,
):
    """
    Get an object by path.
    
    Parameters:
    - repo: Repository object or path
    - path: Path to look up
    - committish: Commit to look up path in
    
    Returns:
    A ShaFile object
    """

def find_unique_abbrev(
    object_store,
    object_id,
    min_length: int = 7,
) -> str:
    """
    Find the shortest unique abbreviation for an object ID.
    
    Parameters:
    - object_store: Object store to search in
    - object_id: The full object ID to abbreviate
    - min_length: Minimum length of abbreviation (default 7)
    
    Returns:
    The shortest unique prefix of the object ID
    """

def check_mailmap(repo: RepoPath, contact) -> str:
    """
    Check canonical name and email of contact.
    
    Parameters:
    - repo: Repository object or path
    - contact: Contact name and/or email
    
    Returns:
    Canonical contact data
    """

def get_branch_remote(repo: Union[str, os.PathLike, Repo]) -> bytes:
    """
    Return the active branch's remote name, if any.
    
    Parameters:
    - repo: Repository to open
    
    Returns:
    Remote name
    """

def get_branch_merge(
    repo: RepoPath,
    branch_name = None,
) -> bytes:
    """
    Return the branch's merge reference (upstream branch), if any.
    
    Parameters:
    - repo: Repository to open
    - branch_name: Name of the branch (defaults to active branch)
    
    Returns:
    Merge reference name (e.g. b"refs/heads/main")
    """

def set_branch_tracking(
    repo: Union[str, os.PathLike, Repo],
    branch_name,
    remote_name,
    remote_ref,
) -> None:
    """
    Set up branch tracking configuration.
    
    Parameters:
    - repo: Repository to open
    - branch_name: Name of the local branch
    - remote_name: Name of the remote (e.g. b"origin")
    - remote_ref: Remote reference to track (e.g. b"refs/heads/main")
    """

def symbolic_ref(
    repo: RepoPath,
    ref_name,
    force: bool = False,
) -> None:
    """
    Set git symbolic ref into HEAD.
    
    Parameters:
    - repo: Repository object or path
    - ref_name: Short name of the new ref
    - force: Force settings without checking if it exists in refs/heads
    """

def update_head(
    repo: RepoPath,
    target,
    detached: bool = False,
    new_branch = None,
) -> None:
    """
    Update HEAD to point at a new branch/commit.
    
    Parameters:
    - repo: Repository object or path
    - target: Branch or committish to switch to
    - detached: Create a detached head
    - new_branch: New branch to create
    """

def daemon(
    path = ".",
    address = None,
    port = None,
) -> None:
    """
    Run a daemon serving Git requests over TCP/IP.
    
    Parameters:
    - path: Path to the directory to serve
    - address: Optional address to listen on (defaults to ::)
    - port: Optional port to listen on (defaults to TCP_GIT_PORT)
    """

def web_daemon(
    path = ".",
    address = None,
    port = None,
) -> None:
    """
    Run a daemon serving Git requests over HTTP.
    
    Parameters:
    - path: Path to the directory to serve
    - address: Optional address to listen on (defaults to ::)
    - port: Optional port to listen on (defaults to 80)
    """

def upload_pack(
    path = ".",
    inf = None,
    outf = None,
) -> int:
    """
    Upload a pack file after negotiating its contents using smart protocol.
    
    Parameters:
    - path: Path to the repository
    - inf: Input stream to communicate with client
    - outf: Output stream to communicate with client
    
    Returns:
    Exit code (0 for success)
    """

def receive_pack(
    path = ".",
    inf = None,
    outf = None,
) -> int:
    """
    Receive a pack file after negotiating its contents using smart protocol.
    
    Parameters:
    - path: Path to the repository
    - inf: Input stream to communicate with client
    - outf: Output stream to communicate with client
    
    Returns:
    Exit code (0 for success)
    """

def sparse_checkout(
    repo: Union[str, os.PathLike, Repo],
    patterns = None,
    force: bool = False,
    cone: Union[bool, None] = None,
) -> None:
    """
    Perform a sparse checkout in the repository.
    
    Parameters:
    - repo: Repository object or path
    - patterns: Optional list of sparse-checkout patterns to write
    - force: Whether to force removal of locally modified files
    - cone: Boolean indicating cone mode (True/False). If None, read from config
    """

def cone_mode_init(repo: Union[str, os.PathLike, Repo]) -> None:
    """
    Initialize a repository to use sparse checkout in 'cone' mode.
    
    Parameters:
    - repo: Repository object or path
    """

def cone_mode_set(
    repo: Union[str, os.PathLike, Repo],
    dirs,
    force: bool = False,
) -> None:
    """
    Overwrite the existing 'cone-mode' sparse patterns with new directories.
    
    Parameters:
    - repo: Repository object or path
    - dirs: List of directory names to include
    - force: Whether to forcibly discard local modifications
    """

def cone_mode_add(
    repo: Union[str, os.PathLike, Repo],
    dirs,
    force: bool = False,
) -> None:
    """
    Add new directories to existing 'cone-mode' sparse-checkout patterns.
    
    Parameters:
    - repo: Repository object or path
    - dirs: List of directory names to add to the sparse-checkout
    - force: Whether to forcibly discard local modifications
    """