Skip to content

Add porcelain-style convenience APIs on Repo (create_branch and merge) #2120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
huyhoang171106 wants to merge 1 commit into
base: main
Choose a base branch
from
+6 −0
Open

Add porcelain-style convenience APIs on Repo (create_branch and merge) #2120

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions git/repo/base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,12 @@ class Repo:
"""Subclasses may easily bring in their own custom types by placing a constructor or
type here."""

def create_branch(self, *args: Any, **kwargs: Any) -> Head:
return self.create_head(*args, **kwargs)

Comment on lines +173 to +175
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

create_branch is a new public API but currently just forwards *args/**kwargs with no docstring. That loses the explicit signature of create_head (path/commit/force/logmsg), weakens type checking and makes the API harder to discover in docs/IDE autocomplete. Consider giving create_branch the same explicit parameters and a short docstring that points to create_head/Head.create (and optionally place it next to create_head for discoverability).

Suggested change
def create_branch(self, *args: Any, **kwargs: Any) -> Head:
return self.create_head(*args, **kwargs)
def create_branch(
self,
path: str,
commit: Commit | str | None = "HEAD",
force: bool = False,
logmsg: str | None = None,
) -> Head:
"""Create a new branch pointing to the given commit.
This is a convenience wrapper around :meth:`create_head` /
:meth:`git.refs.Head.create`.
"""
return self.create_head(path, commit=commit, force=force, logmsg=logmsg)

Copilot uses AI. Check for mistakes.
def merge(self, *args: Any, **kwargs: Any) -> str:
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

merge is typed as returning str, but this is a raw passthrough to self.git.merge(*args, **kwargs). Callers can pass execution flags like as_process, with_extended_output, or stdout_as_string=False, which change the return type (process handle / bytes / tuple). Either constrain the wrapper to the porcelain use-case (no execution-control kwargs) or widen the return type accordingly so the annotation matches actual behavior.

Suggested change
def merge(self, *args: Any, **kwargs: Any) -> str:
def merge(self, *args: Any, **kwargs: Any) -> Any:

Copilot uses AI. Check for mistakes.
return self.git.merge(*args, **kwargs)
Comment on lines +176 to +177
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR/issue description suggests an ergonomic call like repo.merge(from=branch_name), but this wrapper doesn't introduce any named parameter (and Python can't accept a keyword named from). If the intent is a porcelain-style API, consider adding an explicit named argument (e.g., from_/other/rev) and mapping it to the positional merge target, rather than only exposing the low-level *args/**kwargs passthrough.

Copilot uses AI. Check for mistakes.
Comment on lines +173 to +177
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New public Repo convenience methods are added here (create_branch, merge), but there are no tests ensuring they behave as intended (e.g., create_branch being an alias of create_head, and merge delegating to git merge successfully). Given the existing test coverage around create_head/repo operations, adding a small test would help prevent regressions and clarify expected behavior (including error behavior on conflicts).

Copilot uses AI. Check for mistakes.

def __init__(
self,
path: Optional[PathLike] = None,
Expand Down
Loading