mgit 2.0.0__py3-none-any.whl

mgit/__init__.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import runez
+
+from mgit.git import GitDir, Reporter
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class ProjectDir:
+    """One requested workspace, represented as one or more git dirs."""
+
+    def __init__(self, path: Path):
+        """
+        :param Path path: Path to folder
+        """
+        self.path = path
+        self.git_dirs: list[GitDir] = []
+        self.name_size: int | None = None
+        self.scan()
+
+    def scan(self):
+        self.git_dirs = [
+            GitDir(source_path)
+            for source_path in self.path.iterdir()
+            if not source_path.name.startswith(".") and source_path.is_dir() and (source_path / ".git").is_dir()
+        ]
+        self.git_dirs = sorted(self.git_dirs, key=lambda x: x.basename)
+        Reporter.abort_if(not self.git_dirs, f"{runez.short(self.path)}: no git folders")
+        self.name_size = min(36, max(len(git.basename) for git in self.git_dirs)) if len(self.git_dirs) > 1 else None
+
+    def prefixed_line(self, git: GitDir, line: str) -> str:
+        name = git.basename
+        if self.name_size:
+            name = f"{name:>{self.name_size}}"
+
+        return f"{name}: {line}"

mgit/cli.py

@@ -0,0 +1,371 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import re
+import sys
+from abc import ABC, abstractmethod
+from importlib.metadata import version
+from pathlib import Path
+
+import runez
+
+from mgit import ProjectDir, Reporter
+from mgit.git import GitDir
+
+
+def command_name_from_class(cls: type) -> str:
+    name = cls.__name__.removesuffix("Command")
+    return re.sub(r"(?<!^)(?=[A-Z])", "-", name).lower()
+
+
+class CliCommand(ABC):
+    """API for all CLI commands."""
+
+    short_name: str | None = None
+
+    @classmethod
+    def command_name(cls) -> str:
+        return command_name_from_class(cls)
+
+    @classmethod
+    def summary(cls) -> str:
+        """Every command class must have a summary (intentional crash otherwise)"""
+        assert cls.__doc__  # noqa: S101, internal error
+        return cls.__doc__.splitlines()[0]
+
+    @classmethod  # noqa: B027 - optional hook
+    def add_arguments(cls, _parser: argparse.ArgumentParser):
+        """Add command-specific arguments."""
+
+    @classmethod
+    @abstractmethod
+    def from_namespace(cls, _namespace: argparse.Namespace) -> CliCommand:
+        """Create a command from parsed CLI arguments."""
+
+    @abstractmethod
+    def run(self):
+        """Run the command."""
+
+
+class FolderTargetCommand(CliCommand):
+    folder: Path | None = None
+
+    def __init__(self, folder: Path | None):
+        self.folder = folder
+
+    @classmethod
+    def add_arguments(cls, parser: argparse.ArgumentParser):
+        parser.add_argument("folder", nargs="?", type=Path)
+
+    @classmethod
+    def from_namespace(cls, namespace: argparse.Namespace) -> FolderTargetCommand:
+        return cls(folder=namespace.folder)
+
+    @staticmethod
+    def current_checkout() -> Path | None:
+        current = Path.cwd()
+        for candidate in (current, *current.parents):
+            if (candidate / ".git").is_dir():
+                return candidate
+
+    def target(self) -> GitDir | ProjectDir:
+        if self.folder is None:
+            current = self.current_checkout()
+            if current:
+                return GitDir(current)
+
+        folder = (self.folder or Path(".")).expanduser().absolute()
+        Reporter.abort_if(not folder.is_dir(), f"No folder '{runez.short(folder)}'")
+        if (folder / ".git").is_dir():
+            return GitDir(folder)
+
+        return ProjectDir(folder)
+
+    def run(self):
+        """Run the command."""
+        target = self.target()
+        if isinstance(target, GitDir):
+            return self.run_single(target)
+
+        return self.run_multi(target)
+
+    @abstractmethod
+    def run_single(self, git: GitDir):
+        """Run this command for one git dir."""
+
+    def run_multi(self, _project_dir: ProjectDir) -> None:
+        """Run this command for all git dirs in `project_dir`."""
+        Reporter.abort(f"{self.command_name()} only supports one git checkout")
+
+
+COMMANDS: list[type[CliCommand]] = []
+COMMAND_BY_TOKEN: dict[str, type[CliCommand]] = {}
+
+
+def register_cli_command(name: str | None, command: type[CliCommand]):
+    assert name  # noqa: S101, this would be an internal error, detected at test time
+    assert name not in COMMAND_BY_TOKEN  # noqa: S101
+    COMMAND_BY_TOKEN[name] = command
+
+
+def cli_command(command: type[CliCommand]) -> type[CliCommand]:
+    COMMANDS.append(command)
+    register_cli_command(command.command_name(), command)
+    register_cli_command(command.short_name, command)
+    return command
+
+
+@cli_command
+class StatusCommand(FolderTargetCommand):
+    """Show repo or workspace status."""
+
+    short_name = "s"
+
+    def run_single(self, git: GitDir):
+        print(git.status_line())
+        details = git.status_details()
+        if details:
+            print(details)
+
+    def run_multi(self, project_dir: ProjectDir):
+        for git in project_dir.git_dirs:
+            print(project_dir.prefixed_line(git, git.status_line()))
+
+
+@cli_command
+class FetchCommand(FolderTargetCommand):
+    """Fetch remotes, then show status."""
+
+    short_name = "f"
+
+    def run_single(self, git: GitDir):
+        report = git.fetch_now().require_success("fetch")
+        print(git.status_line(report))
+        details = git.status_details()
+        if details:
+            print(details)
+
+    def run_multi(self, project_dir: ProjectDir):
+        for git in project_dir.git_dirs:
+            report = git.fetch_now()
+            print(project_dir.prefixed_line(git, git.status_line(report)))
+
+
+@cli_command
+class PullCommand(FolderTargetCommand):
+    """Pull with rebase when the worktree is safe."""
+
+    short_name = "p"
+
+    def run_single(self, git: GitDir):
+        report = git.pull().require_success("pull")
+        print(git.status_line(report))
+        details = git.status_details()
+        if details:
+            print(details)
+
+    def run_multi(self, project_dir: ProjectDir):
+        for git in project_dir.git_dirs:
+            report = git.pull()
+            print(project_dir.prefixed_line(git, git.status_line(report)))
+
+
+@cli_command
+class MainCommand(FolderTargetCommand):
+    """Checkout the default branch."""
+
+    short_name = "m"
+
+    def run_single(self, git: GitDir):
+        report = git.checkout_default_branch()
+        print(git.status_line(report))
+        details = git.status_details()
+        if details:
+            print(details)
+
+
+@cli_command
+class BranchesCommand(FolderTargetCommand):
+    """Show local branches."""
+
+    short_name = "b"
+
+    def run_single(self, git: GitDir):
+        details = git.branch_details()
+        if details:
+            print(details)
+
+    def run_multi(self, project_dir: ProjectDir):
+        show_names = len(project_dir.git_dirs) > 1
+        for git in project_dir.git_dirs:
+            if show_names:
+                print(f"{git.basename}:")
+
+            indent = "  " if show_names else ""
+            details = git.branch_details(indent=indent)
+            if details:
+                print(details)
+
+
+@cli_command
+class GroomCommand(FolderTargetCommand):
+    """Fetch, return to default branch, pull, and clean the groomed branch."""
+
+    short_name = "g"
+
+    def _checkout_default_branch(self, git: GitDir, branch: str):
+        git.checked_git_command("checkout", branch)
+        git.clear_cached_state()
+        print(f"Checked out {git.represented_branch(branch)} branch")
+
+    def _delete_local_branch(self, git: GitDir, cleanup):
+        args = ["branch", "--delete", cleanup.name]
+        if cleanup.force_delete:
+            args.insert(2, "--force")
+
+        git.checked_git_command(*args)
+        print(f"Deleted branch {git.represented_branch(cleanup.name)}")
+        git.clear_cached_state()
+
+    def _delete_remote_branch(self, git: GitDir, cleanup):
+        branch_ref = f"refs/heads/{cleanup.branch}"
+        git.checked_git_command(
+            "push",
+            f"--force-with-lease={branch_ref}:{cleanup.expected_oid}",
+            "--delete",
+            cleanup.remote,
+            branch_ref,
+        )
+        print(f"Deleted remote branch {cleanup.remote}/{git.represented_branch(cleanup.branch)}")
+        git.clear_cached_state()
+
+    def run_single(self, git: GitDir):
+        report = git.fetch_now().require_success("groom")
+        refs = git.refs
+        current_branch = refs.current
+        default_branch = git.default_branch
+        if current_branch == default_branch:
+            report.add(note="already on default branch")
+            print(git.status_line(report))
+            return
+
+        git.status.require_clean("groom")
+        remote_cleanup = None
+        local_cleanup = git.cleanable_local_branch(current_branch, include_current=True)
+        if not local_cleanup:
+            Reporter.abort(f"Branch {git.represented_branch(current_branch)} can't be cleaned")
+
+        upstream = refs.upstreams.get(current_branch)
+        if upstream and refs.has_remote_branch(upstream.remote, upstream.branch):
+            remote_cleanup = git.cleanable_current_remote_branch()
+            if not remote_cleanup:
+                Reporter.abort(f"Remote branch {upstream.remote}/{git.represented_branch(upstream.branch)} can't be cleaned automatically")
+
+        self._checkout_default_branch(git, default_branch)
+        report = git.pull().require_success("groom")
+        git.clear_cached_state()
+        if remote_cleanup:
+            self._delete_remote_branch(git, remote_cleanup)
+
+        self._delete_local_branch(git, local_cleanup)
+        print(git.status_line(report))
+
+
+class CommandHelpFormatter(argparse.HelpFormatter):
+    """Show subcommands as a compact command list."""
+
+    def _format_action(self, action: argparse.Action) -> str:
+        if isinstance(action, argparse._SubParsersAction):
+            return "".join(self._format_action(choice_action) for choice_action in action._get_subactions())
+
+        return super()._format_action(action)
+
+
+def add_command_parser(subparsers: argparse._SubParsersAction, command: type[CliCommand]):
+    aliases = [command.short_name] if command.short_name else []
+    parser = subparsers.add_parser(
+        command.command_name(),
+        aliases=aliases,
+        description=command.summary(),
+        formatter_class=CommandHelpFormatter,
+        help=command.summary(),
+        prog=f"mgit {command.command_name()}",
+    )
+    parser._action_groups[0].title = "Arguments"
+    command.add_arguments(parser)
+    parser.set_defaults(command_type=command)
+
+
+def split_global_args(args: list[str]) -> tuple[list[str], list[str]]:
+    global_args = []
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg in {"--help", "-v", "--verbose", "--version"}:
+            global_args.append(arg)
+            i += 1
+            continue
+
+        if arg == "--color":
+            global_args.append(arg)
+            i += 1
+            if i < len(args):
+                global_args.append(args[i])
+                i += 1
+            continue
+
+        if arg.startswith("--color="):
+            global_args.append(arg)
+            i += 1
+            continue
+
+        if arg.startswith("-"):
+            global_args.append(arg)
+            i += 1
+
+        break
+
+    return global_args, args[i:]
+
+
+def normalized_cli_args(args: list[str]) -> list[str]:
+    global_args, command_args = split_global_args(args)
+    if global_args and global_args[-1] == "--color":
+        return global_args
+
+    if command_args:
+        command = COMMAND_BY_TOKEN.get(command_args[0])
+        if command:
+            command_args[0] = command.command_name()
+
+        else:
+            command_args.insert(0, StatusCommand.command_name())
+
+    else:
+        command_args.append(StatusCommand.command_name())
+
+    return global_args + command_args
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="mgit",
+        usage="mgit [GLOBAL_OPTIONS] [COMMAND] [ARGS...]",
+        description="Inspect and update git checkouts.",
+        formatter_class=CommandHelpFormatter,
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose logging.")
+    parser.add_argument("--color", choices=("auto", "always", "never"), default="auto", help="Control ANSI color output.")
+    parser.add_argument("--version", action="version", version=f"mgit {version('mgit')}")
+    subparsers = parser.add_subparsers(dest="command", title="Commands", metavar="COMMAND")
+    subparsers.required = True
+    for command in COMMANDS:
+        add_command_parser(subparsers, command)
+
+    namespace = parser.parse_args(normalized_cli_args(sys.argv[1:]))
+    command = namespace.command_type.from_namespace(namespace)
+    with runez.ActivateColors(None if namespace.color == "auto" else namespace.color == "always"):
+        runez.date.DEFAULT_DURATION_SPAN = -2
+        runez.log.setup(debug=namespace.verbose, level=logging.INFO, console_format="%(levelname)s %(message)s", locations=None)
+        command.run()

mgit/git.py

@@ -0,0 +1,712 @@
+from __future__ import annotations
+
+import logging
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from functools import cached_property
+from typing import NoReturn, TYPE_CHECKING
+
+import runez
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class Reporter:
+    """Central user-facing reporting helpers."""
+
+    log = logging.getLogger("mgit")
+
+    branch_default = runez.green
+    branch_orphaned = runez.orange
+    problem = runez.red
+    note = runez.purple
+    progress = runez.plain
+    index_change = runez.teal
+    worktree_change = runez.red
+    untracked_change = runez.orange
+
+    @staticmethod
+    def joined(*args, separator=" "):
+        """Join non-false-ish display fragments."""
+        return runez.joined(*args, delimiter=separator, keep_empty=None)
+
+    @staticmethod
+    def joined_lines(*args, header="", indent="", separator="\n"):
+        """Join non-false-ish display lines with optional header and indentation."""
+        lines = [f"{indent}{line}" for line in runez.flattened(args, keep_empty=None)]
+        return Reporter.joined(header, lines, separator=separator)
+
+    @staticmethod
+    def abort(message, exit_code: int = 1) -> NoReturn:
+        print(Reporter.problem(message), file=sys.stderr)
+        sys.exit(exit_code)
+
+    @staticmethod
+    def abort_if(condition: object, message, exit_code: int = 1):
+        if condition:
+            Reporter.abort(message, exit_code=exit_code)
+
+    @staticmethod
+    def debug(message: str, *args: object):
+        Reporter.log.debug(message, *args)
+
+
+FRESH_FETCH_THRESHOLD = 30
+FRESHNESS_THRESHOLD = 12 * runez.date.SECONDS_IN_ONE_HOUR
+LOCAL_REF_PREFIX = "refs/heads/"
+REMOTE_REF_PREFIX = "refs/remotes/"
+
+
+def git_error_message(proc: subprocess.CompletedProcess[str]) -> str | None:
+    """Short user-facing description of a failed git command."""
+    if proc.returncode:
+        detail = (proc.stderr or proc.stdout).strip() or f"git exited with code {proc.returncode}"
+        detail = detail.strip().lower()
+        if "following untracked" in detail:
+            return "untracked files would be overwritten"
+
+        if "repository not found" in detail:
+            return "repository not found"
+
+        lines = []
+        prefixed = []
+        for line in detail.splitlines():
+            line = line.strip().strip(".")
+            if line:
+                p = line.partition(":")
+                if p[2] and p[0] in ("git", "error", "fatal"):
+                    prefixed.append(p[2].strip())
+
+                else:
+                    lines.append(line)
+
+        return " ".join((prefixed or lines)[:2]).replace("  ", " ").strip()
+
+
+class GitRunReport:
+    """Convenient and easy to compose reporting class"""
+
+    def __init__(
+        self,
+        other: GitRunReport | None = None,
+        *,
+        progress: str | None = None,
+        note: str | None = None,
+        problem: str | None = None,
+    ):
+        self._progress = []
+        self._note = []
+        self._problem = []
+        self.add(other, progress=progress, note=note, problem=problem)
+
+    def __str__(self):
+        return self.representation()
+
+    def require_success(self, operation: str) -> GitRunReport:
+        if self.has_problems:
+            Reporter.abort(self.add(problem=f"<can't {operation}"))
+
+        return self
+
+    def cant_pull(self, reason=None):
+        self.add(problem="<can't pull")
+        if reason:
+            self.add(problem=reason)
+
+        return self
+
+    @property
+    def has_problems(self):
+        return bool(self._problem)
+
+    def representation(self, progress=True, note=True, max_chars=160, separator="; "):
+        """
+        :param bool progress: Show repos with progress mention (pulled/cloned)
+        :param bool note: Show repos with notes
+        :param int max_chars: Max chars to show (truncate if messages are longer)
+        :param str separator: Separator to use
+        :return str: Textual representation
+        """
+        result = []
+        n = _add_sorted(result, self._problem, Reporter.problem, 0, max_chars)
+
+        if progress:
+            n = _add_sorted(result, self._progress, Reporter.progress, n, max_chars)
+
+        if note:
+            _add_sorted(result, self._note, Reporter.note, n, max_chars)
+
+        result = separator.join(result)
+        if len(result) > max_chars:
+            result = f"{result[: max_chars - 3]}..."
+
+        return result
+
+    def add(
+        self,
+        other: GitRunReport | None = None,
+        *,
+        progress: str | None = None,
+        note: str | None = None,
+        problem: str | None = None,
+    ) -> GitRunReport:
+        if other is not None:
+            _add_messages(self._progress, other._progress)
+            _add_messages(self._note, other._note)
+            _add_messages(self._problem, other._problem)
+
+        _add_messages(self._progress, progress)
+        _add_messages(self._note, note)
+        _add_messages(self._problem, problem)
+        return self
+
+
+def git_error_report(proc: subprocess.CompletedProcess[str]) -> GitRunReport:
+    """GitRunReport describing a failed git command."""
+    return GitRunReport(problem=git_error_message(proc))
+
+
+@dataclass
+class BranchUpstream:
+    """Configured upstream for a local branch."""
+
+    remote: str
+    branch: str
+
+
+@dataclass(frozen=True)
+class CleanableLocalBranch:
+    """Local branch that is safe to delete."""
+
+    name: str
+    force_delete: bool = False
+
+
+@dataclass(frozen=True)
+class CleanableRemoteBranch:
+    """Tracked remote branch that is safe to delete with an exact-ref lease."""
+
+    remote: str
+    branch: str
+    expected_oid: str
+
+
+class GitRefs:
+    """Repository ref and upstream snapshot."""
+
+    current: str
+    detached: bool
+    local: set[str]
+    remotes: list[str]
+    by_remote: dict[str, set[str]]
+    default_branches: dict[str, str]
+    upstreams: dict[str, BranchUpstream]
+
+    def __init__(self, parent: GitDir):
+        self.current, self.detached = parent._current_branch()
+        self.local = set()
+        self.remotes = parent.checked_git_command_lines("remote")
+        self.by_remote = {}
+        self.default_branches = {}
+        self.upstreams = {}
+        lines = parent.checked_git_command_lines(
+            "for-each-ref",
+            "--format=%(refname)%09%(upstream:remotename)%09%(upstream:remoteref)%09%(symref)",
+            "refs/heads",
+            "refs/remotes",
+        )
+        for line in lines:
+            self._add_line(line)
+
+    def _add_line(self, line: str):
+        fields = (line + "\t" * 3).split("\t")
+        refname, upstream_remote, upstream_ref, symref = fields[:4]
+        if refname.startswith(LOCAL_REF_PREFIX):
+            local_branch_name = refname[len(LOCAL_REF_PREFIX) :]
+            self.local.add(local_branch_name)
+
+            if upstream_remote and upstream_ref:
+                upstream_branch = upstream_ref[len(LOCAL_REF_PREFIX) :] if upstream_ref.startswith(LOCAL_REF_PREFIX) else upstream_ref
+                upstream = BranchUpstream(remote=upstream_remote, branch=upstream_branch)
+                self.upstreams[local_branch_name] = upstream
+
+        elif refname.startswith(REMOTE_REF_PREFIX):
+            remote, _, branch = refname[len(REMOTE_REF_PREFIX) :].partition("/")
+            if remote and branch:
+                if branch == "HEAD":
+                    prefix = f"{REMOTE_REF_PREFIX}{remote}/"
+                    if len(symref) > len(prefix) and symref.startswith(prefix):
+                        self.default_branches[remote] = symref[len(prefix) :]
+
+                else:
+                    self.by_remote.setdefault(remote, set()).add(branch)
+
+    def has_remote_branch(self, remote: str, branch: str) -> bool:
+        remote_branches = self.by_remote.get(remote)
+        return bool(remote_branches and (branch in remote_branches))
+
+    def upstream_gone(self, branch=None) -> bool:
+        upstream = self.upstreams.get(branch or self.current)
+        return bool(upstream and not self.has_remote_branch(upstream.remote, upstream.branch))
+
+
+class GitDir:
+    """Model a local git repo"""
+
+    def __init__(self, path: Path):
+        """
+        :param Path path: Path to local repo
+        """
+        self.path = path
+        self.basename = path.name
+        self.age = self._current_age()
+
+    def _branch_annotations(self, name):
+        return Reporter.joined(
+            name == self.default_branch and Reporter.branch_default("[default]"),
+            self.is_orphan_branch(name) and Reporter.branch_orphaned("[orphaned]"),
+        )
+
+    @staticmethod
+    def _detail_lines(items, state_style, worktree_style=None) -> list[str]:
+        lines = []
+        for item in items:
+            state = item[0:2]
+            if worktree_style:
+                state = f"{state_style(item[0])}{worktree_style(item[1])}"
+
+            elif state_style:
+                state = state_style(state)
+
+            lines.append(f"{state} {item[3:]}")
+
+        return lines
+
+    def status_line(self, report: GitRunReport | None = None) -> str:
+        refs = self.refs
+        status = self.status
+        edits, deletes, new = status.pending_change_counts()
+        report = GitRunReport(report)
+        if self.age is not None and self.age > FRESHNESS_THRESHOLD:
+            report.add(note=f"⌛{runez.represented_duration(self.age)}")
+
+        other_branches = refs.local - {refs.current, self.default_branch}
+        cleanable = len(other_branches & self.local_cleanable_branches)
+        remaining = len(other_branches) - cleanable
+        branch_summary = Reporter.joined(cleanable and f"+{cleanable}🪦", remaining and f"+{remaining}", separator="")
+        if branch_summary:
+            branch_summary = f"[{branch_summary}]"
+
+        return Reporter.joined(
+            self.represented_current_branch(),
+            branch_summary,
+            status.upstream_delta(),
+            edits and f"✏️{edits}",
+            deletes and f"🗑️{deletes}",
+            new and f"🆕{new}",
+            report,
+        )
+
+    def represented_current_branch(self) -> str:
+        refs = self.refs
+        branch = refs.current
+        if refs.detached:
+            icon = " 👻"
+
+        elif self.is_orphan_branch(branch):
+            icon = " 🪦"
+
+        else:
+            icon = " ✅" if self.age is not None and self.age <= FRESH_FETCH_THRESHOLD else " ☑️"
+
+        return self.represented_branch(branch) + icon
+
+    def status_details(self, indent="  ") -> str:
+        result = []
+        orphan_branches = [branch for branch in self.orphan_branches if branch != self.refs.current and self.is_orphan_branch(branch)]
+        if orphan_branches:
+            result.append(f"Orphan branches: {', '.join(self.represented_branch(branch) for branch in orphan_branches)}")
+
+        status = self.status
+        result.extend(self._detail_lines(status.modified, Reporter.index_change, Reporter.worktree_change))
+        result.extend(self._detail_lines(status.untracked, Reporter.untracked_change))
+        return Reporter.joined_lines(result, indent=indent)
+
+    def branch_details(self, indent="") -> str:
+        refs = self.refs
+        branches = sorted(refs.local) or [refs.current]
+        width = max(len(name) for name in branches)
+        result = []
+        for name in branches:
+            padding = " " * (width - len(name))
+            line = f"{'*' if name == refs.current else ' '} {self.represented_branch(name)}{padding}"
+            annotations = self._branch_annotations(name)
+            if annotations:
+                line += f"  {annotations}"
+
+            result.append(line)
+
+        return Reporter.joined_lines(result, indent=indent)
+
+    def run_git_command(self, *args: str) -> subprocess.CompletedProcess[str]:
+        """
+        :param args: Execute git command with provided args
+        :return subprocess.CompletedProcess: Result from git
+        """
+        cmd = ["git", "-C", str(self.path), *args]
+        Reporter.debug("Running: git -C %s %s", runez.short(self.path), " ".join(args))
+        return subprocess.run(cmd, check=False, capture_output=True, text=True)  # noqa: S603
+
+    def checked_git_command(self, *args: str) -> str:
+        """
+        :param args: Execute git command with provided args
+        :return str: Output from git command, aborting if git fails
+        """
+        proc = self.run_git_command(*args)
+        Reporter.abort_if(proc.returncode, f"git {' '.join(args)} failed: {git_error_message(proc)}")
+        return proc.stdout.strip()
+
+    def checked_git_command_lines(self, *args: str) -> list[str]:
+        return [line.strip() for line in self.checked_git_command(*args).splitlines() if line.strip()]
+
+    def clear_cached_state(self):
+        """Discard cached git state after a command may have changed refs or worktree state."""
+        for k, v in vars(self.__class__).items():
+            if isinstance(v, cached_property) and k in self.__dict__:
+                self.__dict__.pop(k, None)
+
+    def _current_branch(self) -> tuple[str, bool]:
+        proc = self.run_git_command("symbolic-ref", "--quiet", "--short", "HEAD")
+        if proc.returncode == 0:
+            return proc.stdout.strip(), False
+
+        Reporter.abort_if(proc.returncode != 1, f"Could not inspect git branch: {git_error_message(proc)}")
+        proc = self.run_git_command("rev-parse", "--verify", "--quiet", "HEAD")
+        if proc.returncode == 0 and proc.stdout.strip():
+            return "HEAD", True
+
+        Reporter.abort(f"Could not inspect git HEAD: {git_error_message(proc)}")
+
+    def fetch_now(self) -> GitRunReport:
+        proc = self.run_git_command("fetch", "--all", "--prune")
+        if proc.returncode == 0:
+            self.age = 0
+
+        return git_error_report(proc)
+
+    def checkout_default_branch(self) -> GitRunReport:
+        """
+        :return GitRunReport: Checkout report
+        """
+        branch = self.default_branch
+        if self.refs.current == branch:
+            return GitRunReport()
+
+        self.checked_git_command("checkout", branch)
+        self.clear_cached_state()
+        return GitRunReport(progress=f"checked out {self.represented_branch(branch)}")
+
+    def pull(self) -> GitRunReport:
+        """Pull from tracked remote"""
+        refs = self.refs
+        if not refs.remotes:
+            return GitRunReport().cant_pull("no remotes")
+
+        if refs.detached:
+            return GitRunReport().cant_pull("HEAD detached")
+
+        status = self.status
+        if status.has_pending_changes or status.report.has_problems:
+            reason = "pending changes" if status.has_pending_changes else None
+            return GitRunReport(status.report).cant_pull(reason)
+
+        note = status.upstream_delta() or "up-to-date"
+        proc = self.run_git_command("pull", "--rebase")
+        self.clear_cached_state()
+        report = GitRunReport(note=f"was {note}")
+        if proc.returncode:
+            report.cant_pull(git_error_message(proc))
+
+        else:
+            self.age = 0
+
+        return report
+
+    def _current_age(self) -> int | None:
+        """Elapsed time in seconds since last fetch"""
+        for name in ("FETCH_HEAD", "HEAD"):
+            try:
+                last_fetch = (self.path / ".git" / name).stat().st_mtime
+                return int(time.time() - last_fetch)
+
+            except OSError:
+                pass
+
+    @cached_property
+    def default_branch(self) -> str:
+        """Default branch name"""
+        refs = self.refs
+        branch = refs.default_branches.get("origin")
+        if branch:
+            return branch
+
+        origin_branches = refs.by_remote.get("origin")
+        if origin_branches:
+            for candidate in ("main", "master"):
+                if candidate in refs.local or candidate in origin_branches:
+                    return candidate
+
+        return "main"
+
+    @cached_property
+    def status(self) -> GitStatus:
+        """Parsed info from 'git status --porcelain=v2 --branch'"""
+        return GitStatus(self)
+
+    @cached_property
+    def refs(self) -> GitRefs:
+        return GitRefs(self)
+
+    @cached_property
+    def orphan_branches(self) -> list[str]:
+        """Local branch names that were deleted on their corresponding remote"""
+        result = []
+        refs = self.refs
+        for name in sorted(refs.local):
+            upstream = refs.upstreams.get(name)
+            if not upstream or not refs.has_remote_branch(upstream.remote, upstream.branch):
+                result.append(name)
+
+        return result
+
+    def is_protected_branch(self, name: str) -> bool:
+        """True if branch should not be cleaned or reported as orphaned"""
+        return bool(name and (name == self.default_branch or name in self.refs.default_branches.values()))
+
+    def is_orphan_branch(self, name: str) -> bool:
+        """True if branch is an unprotected orphan."""
+        return bool(name and name in self.orphan_branches and not self.is_protected_branch(name))
+
+    def represented_branch(self, name: str) -> str:
+        """Styled representation of a branch name."""
+        result = runez.bold(name)
+        if name == self.default_branch:
+            return runez.green(result)
+
+        if self.is_orphan_branch(name):
+            return runez.orange(result)
+
+        return result
+
+    @cached_property
+    def cleanable_base_ref(self) -> str:
+        """Ref that cleanup candidates must already be merged into"""
+        base_ref = self.default_branch
+        remote_branches = self.refs.by_remote.get("origin")
+        if remote_branches and base_ref in remote_branches:
+            base_ref = f"origin/{base_ref}"
+
+        return base_ref
+
+    def is_ancestor(self, ref: str, target_ref: str) -> bool:
+        """
+        :param str ref: Candidate ref
+        :param str target_ref: Ref that should contain the candidate
+        :return bool: True if 'ref' is an ancestor of 'target_ref'
+        """
+        proc = self.run_git_command("merge-base", "--is-ancestor", ref, target_ref)
+        Reporter.abort_if(proc.returncode > 1, f"Could not inspect git ancestry: {git_error_message(proc)}")
+        return proc.returncode == 0
+
+    def merge_is_noop(self, ref: str, target_ref: str) -> bool:
+        """
+        :param str ref: Candidate ref
+        :param str target_ref: Ref that should already contain the candidate content
+        :return bool: True if merging 'ref' into 'target_ref' would leave 'target_ref' unchanged
+        """
+        target_tree = self.checked_git_command("rev-parse", f"{target_ref}^{{tree}}")
+        proc = self.run_git_command("merge-tree", "--write-tree", "--no-messages", target_ref, ref)
+        if proc.returncode:
+            return False
+
+        trees = [line.strip() for line in proc.stdout.splitlines() if line.strip()]
+        return len(trees) == 1 and bool(target_tree) and trees[0] == target_tree
+
+    def cleanable_local_branch(self, name: str, include_current=False) -> CleanableLocalBranch | None:
+        """
+        :param str name: Local branch name
+        :param bool include_current: If True, allow checking the current branch
+        :return CleanableLocalBranch|None: Cleanup details if local branch is safe to clean
+        """
+        base_ref = self.cleanable_base_ref
+        refs = self.refs
+        if not base_ref or not name or self.is_protected_branch(name) or (not include_current and name == refs.current):
+            return None
+
+        if self.is_ancestor(name, base_ref):
+            return CleanableLocalBranch(name)
+
+        if self.merge_is_noop(name, base_ref):
+            return CleanableLocalBranch(name, force_delete=True)
+
+        return None
+
+    def cleanable_current_remote_branch(self) -> CleanableRemoteBranch | None:
+        """Return cleanup details for the current branch's safely deletable origin ref."""
+        refs = self.refs
+        upstream = refs.upstreams.get(refs.current)
+        default_branch = self.default_branch
+        if (
+            not upstream
+            or upstream.remote != "origin"
+            or upstream.branch == default_branch
+            or not refs.has_remote_branch(upstream.remote, upstream.branch)
+            or not refs.has_remote_branch(upstream.remote, default_branch)
+        ):
+            return None
+
+        branch_ref = f"{REMOTE_REF_PREFIX}{upstream.remote}/{upstream.branch}"
+        base_ref = f"{REMOTE_REF_PREFIX}{upstream.remote}/{default_branch}"
+        if not self.is_ancestor(branch_ref, base_ref) and not self.merge_is_noop(branch_ref, base_ref):
+            return None
+
+        expected_oid = self.checked_git_command("rev-parse", branch_ref)
+        return CleanableRemoteBranch(upstream.remote, upstream.branch, expected_oid)
+
+    @cached_property
+    def local_cleanable_branches(self) -> set[str]:
+        """
+        :return set: Local branches that can be cleaned
+        """
+        return {name for name in self.refs.local if self.cleanable_local_branch(name)}
+
+
+class GitStatus:
+    """Currently modified files"""
+
+    def __init__(self, parent: GitDir):
+        self.ahead = 0
+        self.behind = 0
+        self.modified = []
+        self.untracked = []
+        self.report = GitRunReport()
+        lines = parent.checked_git_command_lines("status", "--porcelain=v2", "--branch")
+        for line in lines:
+            prefix = line[0]
+            info = line[2:]
+            if prefix == "#":
+                keyword, _, value = info.partition(" ")
+                if keyword == "branch.ab":
+                    ab = value.partition(" ")
+                    self.ahead = int(ab[0])
+                    self.behind = -int(ab[2])
+
+            elif prefix == "?":
+                self.untracked.append(f" ? {info}")
+
+            else:
+                fields = info.split(" ")
+                state = fields[0].replace(".", " ")
+                path = fields[-1].partition("\t")[0]
+                self.modified.append(f"{state} {path}")
+
+        if parent.refs.upstream_gone():
+            self.report.add(problem="remote branch gone")
+
+    @property
+    def dirty_note(self) -> str:
+        """Short overview of pending changes."""
+        return Reporter.joined(
+            self.modified and Reporter.problem(runez.plural(self.modified, "diff")),
+            self.untracked and Reporter.untracked_change(f"{len(self.untracked)} untracked"),
+        )
+
+    @property
+    def has_pending_changes(self) -> bool:
+        return bool(self.modified or self.untracked)
+
+    def upstream_delta(self) -> str:
+        """Short report on divergence from the upstream branch."""
+        return Reporter.joined(
+            self.ahead and Reporter.note(f"{self.ahead} ahead"),
+            self.behind and Reporter.note(f"{self.behind} behind"),
+        )
+
+    def pending_change_counts(self) -> tuple[int, int, int]:
+        edits = 0
+        deletes = 0
+        new = len(self.untracked)
+        for item in self.modified:
+            state = item[0:2]
+            if "D" in state:
+                deletes += 1
+
+            elif "A" in state:
+                new += 1
+
+            else:
+                edits += 1
+
+        return edits, deletes, new
+
+    def require_clean(self, operation: str):
+        if self.has_pending_changes:
+            Reporter.abort(f"can't {operation}: pending changes: {self.dirty_note}")
+
+
+def _add_messages(target: list[str], messages: str | list[str] | None):
+    if messages:
+        if not isinstance(messages, list):
+            messages = [messages]
+
+        for message in messages:
+            if message not in target:
+                target.append(message)
+
+
+def _add_sorted(result, target, color, n, max_chars) -> int:
+    """
+    :param list(str) result: Where to accumulate sorted report
+    :param list(str) target: Target to sort, respecting '<' and '>' prefixing
+    :param color: Optional color to use
+    :param int n: How many chars were consumed so far
+    :param int|None max_chars: Maximum number of characters to yield
+    :return int: Number of chars accumulated
+    """
+    if max_chars and n > max_chars:
+        # We already reached limit
+        return n
+
+    items = []
+    for message in (s.lstrip("<>") for i, s in sorted(enumerate(target), key=_report_sorter)):
+        size = len(message)
+        if max_chars:
+            remaining = max_chars - n
+            if remaining < size:
+                items.append(message[:remaining])
+                n += size
+                break
+
+        n += size
+        items.append(message)
+
+    result.extend(color(s) for s in items)
+    return n
+
+
+def _report_sorter(enum):
+    """
+    :param tuple(int, str) enum: Tuple from enumerate()
+    :return int: Value to use for sorting messages in this report
+    """
+    _, message = enum
+    if message[0] == "<":
+        return -enum[0]  # '<' makes message sort towards front, but keeping order with other such prefixed messages
+
+    if message[0] == ">":
+        return 1000000 + enum[0]  # '>' makes message sort towards end
+
+    return enum[0]  # Non-prefixed message stay where they were

mgit-2.0.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: mgit
+Version: 2.0.0
+Summary: Fetch collections of git projects
+Author-email: Zoran Simic <zoran@simicweb.com>
+License-Expression: MIT
+Project-URL: Source, https://github.com/zsimic/mgit
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+Requires-Dist: runez<6
+
+mgit
+====
+
+A small companion for humans who like tidy git checkouts.
+
+.. image:: https://img.shields.io/pypi/v/mgit.svg
+    :target: https://pypi.org/project/mgit/
+    :alt: Version on pypi
+
+.. image:: https://github.com/zsimic/mgit/workflows/Tests/badge.svg
+    :target: https://github.com/zsimic/mgit/actions
+    :alt: Tested with Github Actions
+
+.. image:: https://img.shields.io/pypi/pyversions/mgit.svg
+    :target: https://pypi.org/project/mgit/
+    :alt: Python versions tested
+
+
+What it is
+==========
+
+``mgit`` is a tiny CLI for people who like their git checkouts clean, current,
+and easy to scan. It gives you a quick read on one repo, or on every repo
+directly inside a workspace folder.
+
+- What state did I leave this checkout in?
+- Can I pull, or did I leave work pending here?
+- Is a merged branch still hanging around, waiting to be cleaned?
+- I just wrapped up a branch; can I safely get back to ``main`` and clear it away?
+
+``mgit`` is not a git replacement. It is the compact, careful layer for those
+ordinary moments where you would rather see the answer than reconstruct it
+from a handful of commands.
+
+
+The rhythm
+==========
+
+Start with a glance::
+
+    mgit        # show status here, or across a workspace
+
+Refresh or move forward only when you mean to::
+
+    mgit f      # fetch --all --prune, then show the refreshed status
+    mgit p      # pull --rebase, but never over pending work
+
+And for the wonderfully common ``PR merged`` moment::
+
+    mgit g      # fetch, return to the default branch, pull, clean this branch
+
+The short names are the intended interface:
+
+- ``status`` / ``s``: show whether anything here needs attention. This is the default.
+- ``fetch`` / ``f``: refresh remote refs, then show what changed.
+- ``pull`` / ``p``: pull with rebase only when pending work will not be disturbed.
+- ``main`` / ``m``: checkout the default branch, even if it is ``master``.
+- ``branches`` / ``b``: list local branches with useful small annotations.
+- ``groom`` / ``g``: safely finish with the merged branch you are currently on.
+
+The command shape is::
+
+    mgit [-v] [--color auto|always|never] [COMMAND] [FOLDER]
+
+You can pass a folder to most commands::
+
+    mgit ~/github
+    mgit f ~/github
+    mgit g ~/github/mgit
+
+Workspace scans are shallow on purpose: ``mgit ~/github`` inspects direct
+children like ``~/github/*/.git`` and does not crawl nested folders.
+
+
+What you see
+============
+
+A workspace stays pleasantly skimmable::
+
+        mgit: main ✅
+     pickley: main ☑️ [+1🪦] ⌛4w 6d
+       runez: feature 🪦 ✏️1
+    detached: HEAD 👻
+
+In one glance you get:
+
+- the current branch
+- local diffs and untracked files
+- ahead/behind/gone tracking state
+- fetch freshness
+- a compact hint that a stale local branch is still lurking
+
+``✅`` means recently refreshed, ``☑️`` means the local picture may be older,
+``⌛`` calls out notably stale fetch information, a branch-level ``🪦`` means
+its upstream is gone, and ``👻`` means detached ``HEAD``. A bracket such as
+``[+2🪦+1]`` says that, besides the current and default branches, two local
+branches have been proven cleanable and one remains.
+
+For a single checkout, status also prints the pending paths. Workspace output
+keeps to one line per repo, so you can keep checking a directory full of
+projects without turning the terminal into a log dump::
+
+    mgit ~/github/mgit
+
+Color is automatic on terminals and can be controlled explicitly::
+
+    mgit --color auto
+    mgit --color always
+    mgit --color never
+
+
+Safety model
+============
+
+``mgit`` is read-only by default. Asking how things look does not change your repos.
+
+Commands that act are explicit:
+
+- ``mgit f`` updates local remote refs with ``git fetch --all --prune``.
+- ``mgit p`` pulls with rebase only when the checkout passes safety checks.
+- ``mgit g`` fetches, verifies that the current branch can be cleaned before
+  switching branches, pulls safely, and deletes that local branch only. If it
+  still exists on ``origin``, it deletes that one remote branch only after
+  independently proving that the fetched remote ref is merged or
+  content-equivalent to the fetched default branch; an exact-ref lease prevents
+  deleting a branch that advanced meanwhile. No other branch is deleted.
+  When already on the default branch, it fetches and reports that fact without
+  pulling or cleaning branches. Use ``mgit m`` when you only want to switch to
+  the default branch.
+
+
+Coming next
+===========
+
+A larger convenience waiting in the wings is ``mgit clone``: give it a full
+repo URL and let ``mgit`` choose the local destination from simple config
+rules.
+
+Planned config shape::
+
+    locations = [
+        { match = "github.com/zsimic/*", dir = "~/github" },
+        { match = "github.com/*",        dir = "~/ext" },
+        { match = "git.mycompany.com/*", dir = "~/dev" },
+    ]
+
+The goal is predictable placement without memorizing where each family of repos
+belongs. Status, fetch, pull, main, and groom do not require any mgit config.
+
+
+Install
+=======
+
+Install with pickley_ or pipx_::
+
+    pickley install mgit
+
+or::
+
+    pipx install mgit
+
+Install from a checkout for development::
+
+    git clone https://github.com/zsimic/mgit.git
+    cd mgit
+    uv sync
+    .venv/bin/mgit --help
+
+
+Develop
+=======
+
+Fast local checks::
+
+    .venv/bin/pytest -q
+    ruff check
+
+Full confidence check::
+
+    tox
+
+
+.. _pickley: https://pypi.org/project/pickley/
+
+.. _pipx: https://pypi.org/project/pipx/

mgit-2.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mgit/__init__.py,sha256=WFknd94Qx8PF7nbKisHfTWCRIIB0dOMGGET4oAozdvQ,1222
+mgit/cli.py,sha256=9txUWea8gXbOenLejisc21bnGv_FeEaLcSvnP4lM3Fc,11818
+mgit/git.py,sha256=ohWVH4rSb0q9hhskuWr2BtAJ4Rab20Vv2aEFFh3y3Pk,24996
+mgit-2.0.0.dist-info/METADATA,sha256=mySUrAEMWiWiTb5SWs_w1Wqhr_B-q6j1pyzpSNyScsk,6458
+mgit-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mgit-2.0.0.dist-info/entry_points.txt,sha256=v21pcJu2JM5QemmoJW0uFhodNmkexZo6SxLWSaEjDr4,39
+mgit-2.0.0.dist-info/top_level.txt,sha256=CGzko63KesRtbSeVDtbZD5WEvyunRhTxnYStEDpeXvQ,5
+mgit-2.0.0.dist-info/RECORD,,

mgit-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mgit-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mgit = mgit.cli:main

mgit-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mgit