cmd(git): Stub out Git.branch

Author: tony

src/libvcs/cmd/git.py

@@ -21,6 +21,7 @@ class Git:
     submodule: "GitSubmoduleCmd"
     remote: "GitRemoteCmd"
     stash: "GitStashCmd"
+    branch: "GitBranchCmd"
 
     def __init__(
         self,
@@ -82,6 +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)
 
     def __repr__(self) -> str:
         """Representation of Git repo command object."""
@@ -2952,3 +2954,83 @@ def save(
             check_returncode=check_returncode,
             log_in_real_time=log_in_real_time,
         )
+
+
+GitBranchCommandLiteral = Literal[
+    "create",  # checkout -b
+    "move",
+    "copy",
+    "delete",
+]
+
+
+class GitBranchCmd:
+    """Run commands directly against a git branch for a git repo."""
+
+    def __init__(self, *, path: StrPath, cmd: Optional[Git] = None) -> None:
+        """Lite, typed, pythonic wrapper for git-branch(1).
+
+        Parameters
+        ----------
+        path :
+            Operates as PATH in the corresponding git subcommand.
+
+        Examples
+        --------
+        >>> GitBranchCmd(path=tmp_path)
+        <GitBranchCmd path=...>
+
+        >>> GitBranchCmd(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)
+        ''
+        """
+        #: 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)
+
+    def __repr__(self) -> str:
+        """Representation of git branch storage command object."""
+        return f"<GitBranchCmd path={self.path}>"
+
+    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 storage.
+
+        Wraps `git branch <https://git-scm.com/docs/git-branch>`_.
+
+        Examples
+        --------
+        >>> GitBranchCmd(path=git_local_clone.path).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,
+        )