!squash more

src/libvcs/cmd/git.py

@@ -21,7 +21,7 @@ class Git:
     submodule: "GitSubmoduleCmd"
     remote: "GitRemoteCmd"
     stash: "GitStashCmd"
-    branch: "GitBranchCmd"
+    branch: "GitBranchManager"
 
     def __init__(
         self,
@@ -83,7 +83,7 @@ def __init__(
         self.submodule = GitSubmoduleCmd(path=self.path, cmd=self)
         self.remote = GitRemoteCmd(path=self.path, cmd=self)
         self.stash = GitStashCmd(path=self.path, cmd=self)
-        self.branch = GitBranchCmd(path=self.path, cmd=self)
+        self.branch = GitBranchManager(path=self.path, cmd=self)
 
     def __repr__(self) -> str:
         """Representation of Git repo command object."""
@@ -2974,7 +2974,15 @@ def save(
 class GitBranchCmd:
     """Run commands directly against a git branch for a git repo."""
 
-    def __init__(self, *, path: StrPath, cmd: Optional[Git] = None) -> None:
+    branch_name: str
+
+    def __init__(
+        self,
+        *,
+        path: StrPath,
+        branch_name: str,
+        cmd: Optional[Git] = None,
+    ) -> None:
         """Lite, typed, pythonic wrapper for git-branch(1).
 
         Parameters
@@ -2984,13 +2992,128 @@ def __init__(self, *, path: StrPath, cmd: Optional[Git] = None) -> None:
 
         Examples
         --------
-        >>> GitBranchCmd(path=tmp_path)
-        <GitBranchCmd path=...>
+        >>> GitBranchCmd(path=tmp_path, branch_name='master')
+        <GitBranchCmd path=... branch_name=master>
+
+        >>> GitBranchCmd(path=tmp_path, branch_name="master").run(quiet=True)
+        'fatal: not a git repository (or any of the parent directories): .git'
+
+        >>> GitBranchCmd(
+        ...     path=git_local_clone.path, branch_name="master").run(quiet=True)
+        '* master'
+        """
+        #: Directory to check out
+        self.path: pathlib.Path
+        if isinstance(path, pathlib.Path):
+            self.path = path
+        else:
+            self.path = pathlib.Path(path)
+
+        self.cmd = cmd if isinstance(cmd, Git) else Git(path=self.path)
+
+        self.branch_name = branch_name
+
+    def __repr__(self) -> str:
+        """Representation of git branch command object."""
+        return f"<GitBranchCmd path={self.path} branch_name={self.branch_name}>"
+
+    def run(
+        self,
+        command: Optional[GitBranchCommandLiteral] = None,
+        local_flags: Optional[list[str]] = None,
+        *,
+        quiet: Optional[bool] = None,
+        cached: Optional[bool] = None,  # Only when no command entered and status
+        # Pass-through to run()
+        log_in_real_time: bool = False,
+        check_returncode: Optional[bool] = None,
+        **kwargs: Any,
+    ) -> str:
+        """Run a command against a git repository's branch.
+
+        Wraps `git branch <https://git-scm.com/docs/git-branch>`_.
+
+        Examples
+        --------
+        >>> GitBranchCmd(path=git_local_clone.path, branch_name='master').run()
+        '* master'
+        """
+        local_flags = local_flags if isinstance(local_flags, list) else []
+        if command is not None:
+            local_flags.insert(0, command)
+
+        if quiet is True:
+            local_flags.append("--quiet")
+        if cached is True:
+            local_flags.append("--cached")
+
+        return self.cmd.run(
+            ["branch", *local_flags],
+            check_returncode=check_returncode,
+            log_in_real_time=log_in_real_time,
+        )
+
+    def checkout(self) -> str:
+        """Git branch checkout.
+
+        Examples
+        --------
+        >>> GitBranchCmd(path=git_local_clone.path, branch_name='master').checkout()
+        "Your branch is up to date with 'origin/master'."
+        """
+        return self.cmd.run(
+            [
+                "checkout",
+                *[self.branch_name],
+            ],
+        )
+
+    def create(self) -> str:
+        """Create a git branch.
+
+        Examples
+        --------
+        >>> GitBranchCmd(path=git_local_clone.path, branch_name='master').create()
+        "fatal: a branch named 'master' already exists"
+        """
+        return self.cmd.run(
+            [
+                "checkout",
+                *["-b", self.branch_name],
+            ],
+            # Pass-through to run()
+            check_returncode=False,
+        )
+
+
+class GitBranchManager:
+    """Run commands directly related to git branches of a git repo."""
+
+    branch_name: str
+
+    def __init__(
+        self,
+        *,
+        path: StrPath,
+        cmd: Optional[Git] = None,
+    ) -> None:
+        """Wrap some of git-branch(1), git-checkout(1), manager.
+
+        Parameters
+        ----------
+        path :
+            Operates as PATH in the corresponding git subcommand.
+
+        Examples
+        --------
+        >>> GitBranchManager(path=tmp_path)
+        <GitBranchManager path=...>
 
-        >>> GitBranchCmd(path=tmp_path).run(quiet=True)
+        >>> GitBranchManager(path=tmp_path).run(quiet=True)
         'fatal: not a git repository (or any of the parent directories): .git'
 
-        >>> GitBranchCmd(path=git_local_clone.path).run(quiet=True)
+        >>> GitBranchManager(
+        ...     path=git_local_clone.path).run(quiet=True)
         '* master'
         """
         #: Directory to check out
@@ -3003,8 +3126,8 @@ def __init__(self, *, path: StrPath, cmd: Optional[Git] = None) -> None:
         self.cmd = cmd if isinstance(cmd, Git) else Git(path=self.path)
 
     def __repr__(self) -> str:
-        """Representation of git branch storage command object."""
-        return f"<GitBranchCmd path={self.path}>"
+        """Representation of git branch manager object."""
+        return f"<GitBranchManager path={self.path}>"
 
     def run(
         self,
@@ -3018,13 +3141,13 @@ def run(
         check_returncode: Optional[bool] = None,
         **kwargs: Any,
     ) -> str:
-        """Run a command against a git repository's branch storage.
+        """Run a command against a git repository's branches.
 
         Wraps `git branch <https://git-scm.com/docs/git-branch>`_.
 
         Examples
         --------
-        >>> GitBranchCmd(path=git_local_clone.path).run()
+        >>> GitBranchManager(path=git_local_clone.path).run()
         '* master'
         """
         local_flags = local_flags if isinstance(local_flags, list) else []
@@ -3047,7 +3170,7 @@ def checkout(self, *, branch: str) -> str:
 
         Examples
         --------
-        >>> GitBranchCmd(path=git_local_clone.path).checkout(branch='master')
+        >>> GitBranchManager(path=git_local_clone.path).checkout(branch='master')
         "Your branch is up to date with 'origin/master'."
         """
         return self.cmd.run(
@@ -3062,7 +3185,7 @@ def create(self, *, branch: str) -> str:
 
         Examples
         --------
-        >>> GitBranchCmd(path=git_local_clone.path).create(branch='master')
+        >>> GitBranchManager(path=git_local_clone.path).create(branch='master')
         "fatal: a branch named 'master' already exists"
         """
         return self.cmd.run(
@@ -3079,7 +3202,7 @@ def ls(self) -> str:
 
         Examples
         --------
-        >>> GitBranchCmd(path=git_local_clone.path).ls()
+        >>> GitBranchManager(path=git_local_clone.path).ls()
         '* master'
         """
         return self.run(