gerrit-clone 2.2.1__tar.gz → 2.2.2__tar.gz

{gerrit_clone-2.2.1 → gerrit_clone-2.2.2}/.pre-commit-config.yaml

@@ -3,6 +3,7 @@
 # SPDX-FileCopyrightText: 2025 The Linux Foundation
 
 ci:
+  autofix_prs: false
   skip: [basedpyright, pytest, gha-workflow-linter]
   autofix_commit_msg: |
     Chore: pre-commit autofixes
@@ -51,7 +52,7 @@ repos:
         types: [yaml]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 01a675ea018f2fb714478a5ffb83fcea8374bb06  # frozen: v0.15.21
+    rev: aab412d509121cb5f7533134b7e67f9fab59c682  # frozen: v0.16.4
     hooks:
       - id: ruff
         files: ^(scripts|tests|custom_components)/.+\.py$
@@ -60,7 +61,7 @@ repos:
         files: ^(scripts|tests|custom_components)/.+\.py$
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 41e691678310dfd3833f7ab4e180ddb014310356  # frozen: v2.3.0
+    rev: 7ff8d35ae36a7d2b968f2f90b4c723e292e594ee  # frozen: v2.3.1
     hooks:
       - id: mypy
         additional_dependencies:
@@ -79,12 +80,12 @@ repos:
         args: ["--no-adverb"]
 
   - repo: https://github.com/shellcheck-py/shellcheck-py
-    rev: 745eface02aef23e168a8afb6b5737818efbea95 # frozen: v0.11.0.1
+    rev: a6564f5d57444e123433a5c9af733e3975c77229  # frozen: v0.11.0.1-1
     hooks:
       - id: shellcheck
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: a4d5d37e66ebcd6b3705204a1d6dbb56dea66338  # frozen: v0.49.0
+    rev: 5b5dddc4fb0f83c3ea1fc5616fa63e115dce83e0  # frozen: v0.49.1
     hooks:
       - id: markdownlint
         args: ["--fix"]
@@ -103,23 +104,23 @@ repos:
 
   # Check for misspellings in documentation files
   - repo: https://github.com/codespell-project/codespell
-    rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a  # frozen: v2.4.2
+    rev: 57b21406f092110c18776e39b0bda50d37c945c8  # frozen: v2.4.3
     hooks:
       - id: codespell
 
   # Requires a mirror, primary repo lacks .pre-commit-hooks.yaml
   - repo: https://github.com/DetachHead/basedpyright-prek-mirror
-    rev: d55eabd2531b4f4a4c49c30fba627ce3a636ab79  # frozen: 1.39.9
+    rev: 3c94d276aa3005fa1f5a977946c9dc106135c083  # frozen: 1.39.10
     hooks:
       - id: basedpyright
 
   - repo: https://github.com/lfreleng-actions/gha-workflow-linter
-    rev: 4c3079dcb6e9e3c295f961ce5bd5b8585db698ca  # frozen: v1.2.2
+    rev: 42aa4db931ab4c9da0930ae5ca2259ab08da79cb  # frozen: v1.5.2
     hooks:
       - id: gha-workflow-linter
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 1a4bb160cab6417b3045e1b37b6b72449243e658  # frozen: 0.37.4
+    rev: c4654a7e007c9619a5eb63c39a456572a0fa1851  # frozen: 0.38.0
     hooks:
       - id: check-github-actions
       - id: check-github-workflows

{gerrit_clone-2.2.1 → gerrit_clone-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: gerrit-clone
-Version: 2.2.1
+Version: 2.2.2
 Summary: A multi-threaded CLI tool for bulk cloning repositories from Gerrit servers
 Project-URL: Homepage, https://github.com/lfreleng-actions/gerrit-clone-action
 Project-URL: Documentation, https://github.com/lfreleng-actions/gerrit-clone-action#readme
@@ -30,7 +30,7 @@ Requires-Python: <3.14,>=3.11
 Requires-Dist: httpx<0.29.0,>=0.28.1
 Requires-Dist: pyyaml<7.0.0,>=6.0.3
 Requires-Dist: rich<16.0.0,>=14.2.0
-Requires-Dist: typer<0.27.0,>=0.21.1
+Requires-Dist: typer<0.28.0,>=0.21.1
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio<1.5.0,>=0.25.3; extra == 'dev'
 Requires-Dist: pytest-cov<8.0.0,>=6.3.0; extra == 'dev'

{gerrit_clone-2.2.1 → gerrit_clone-2.2.2}/pyproject.toml

@@ -45,7 +45,7 @@ classifiers = [
 ]
 requires-python = ">=3.11,<3.14"
 dependencies = [
-    "typer>=0.21.1,<0.27.0",
+    "typer>=0.21.1,<0.28.0",
     "rich>=14.2.0,<16.0.0",
     "httpx>=0.28.1,<0.29.0",
     "pyyaml>=6.0.3,<7.0.0",
@@ -192,11 +192,32 @@ select = [
 ignore = [
     "E501",   # line too long, handled by formatter
     "PLR0913", # too many arguments
+    "PLR0917", # too many positional arguments — see note below
     "PLR0912", # too many branches
     "PLR0915", # too many statements — CLI commands and managers are complex by design
     "PLR2004", # magic value used in comparison
 ]
 
+# PLR0917 was stabilised in ruff 0.16.0.  This project already selects
+# the "PL" category, so a routine pre-commit autoupdate crossing that
+# release began failing on code nobody had touched.
+#
+# It is ignored globally rather than only under tests because both
+# call sites are legitimate:
+#
+#   - tests/ stack @patch decorators, and unittest.mock injects each
+#     mock positionally, so a keyword-only signature is impossible
+#     rather than merely inconvenient.
+#   - src/gerrit_clone/refresh_worker.py declares RefreshWorker.__init__
+#     with eleven defaulted parameters.  The closely related PLR0913
+#     (too many arguments) is already ignored directly above for exactly
+#     that constructor.  PLR0917 counts only those arguments that may be
+#     passed positionally, so it is the narrower of the two; ignoring one
+#     while enforcing the other would be inconsistent.
+#
+# Scoping it to tests alone would leave src/ latently failing the moment
+# the ruff hook's `files:` pattern is corrected to include src/.
+
 [tool.ruff.lint.per-file-ignores]
 "tests/**/*" = ["ARG", "S101", "PLR2004"]
 "src/gerrit_clone/cli.py" = ["B008"]  # Typer requires function calls in defaults

{gerrit_clone-2.2.1 → gerrit_clone-2.2.2}/src/gerrit_clone/__init__.py

@@ -5,6 +5,7 @@
 
 try:
     from importlib.metadata import version
+
     __version__ = version("gerrit-clone")
 except ImportError:
     # Fallback for development/editable installs

gerrit_clone-2.2.2/src/gerrit_clone/cli.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2025 Matthew Watkins <mwatkins@linuxfoundation.org>
+
+"""Typer-based CLI for gerrit-clone tool.
+
+This module is the public entry point for the command line interface.  It
+assembles the Typer application by importing every command module and
+re-exports the collaborators that the command bodies resolve at call time, so
+that ``gerrit_clone.cli.<name>`` remains the single place to substitute them.
+"""
+
+from __future__ import annotations
+
+from gerrit_clone.cli_app import app, main, version_callback
+from gerrit_clone.cli_clone import clone
+from gerrit_clone.cli_config import show_config
+from gerrit_clone.cli_mirror import mirror
+from gerrit_clone.cli_refresh import refresh
+from gerrit_clone.cli_reset import reset
+from gerrit_clone.clone_manager import clone_repositories
+from gerrit_clone.netrc import resolve_gerrit_credentials
+from gerrit_clone.unified_discovery import discover_projects
+
+# Registered explicitly rather than by decorator so that the order the
+# commands appear in ``--help`` does not depend on import order.
+app.command()(clone)
+app.command()(refresh)
+app.command(name="mirror")(mirror)
+app.command()(reset)
+app.command(name="config")(show_config)
+
+__all__ = [
+    "app",
+    "clone",
+    "clone_repositories",
+    "discover_projects",
+    "main",
+    "mirror",
+    "refresh",
+    "reset",
+    "resolve_gerrit_credentials",
+    "show_config",
+    "version_callback",
+]
+
+
+if __name__ == "__main__":
+    app()

gerrit_clone-2.2.2/src/gerrit_clone/cli_app.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+
+"""Typer application object shared by every gerrit-clone command module.
+
+The application lives here rather than in :mod:`gerrit_clone.cli` so that the
+per-command modules can register themselves against it without importing the
+public facade that aggregates them.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import typer
+from rich.console import Console
+
+from gerrit_clone import __version__
+from gerrit_clone.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def is_github_actions_context() -> bool:
+    """Detect if running in GitHub Actions environment."""
+    return (
+        os.getenv("GITHUB_ACTIONS") == "true"
+        or os.getenv("GITHUB_EVENT_NAME", "").strip() != ""
+    )
+
+
+def format_version_string(command: str = "", styled: bool = True) -> str:
+    """Format version string with consistent styling.
+
+    Args:
+        command: Optional command name to include (e.g., "mirror")
+        styled: Whether to include Rich markup styling
+
+    Returns:
+        Formatted version string
+    """
+    if styled:
+        if command:
+            return f"🏷️  [bold]gerrit-clone {command}[/bold] version [cyan]{__version__}[/cyan]"
+        return f"🏷️  gerrit-clone version [cyan]{__version__}[/cyan]"
+    else:
+        if command:
+            return f"🏷️  gerrit-clone {command} version {__version__}"
+        return f"🏷️  gerrit-clone version {__version__}"
+
+
+# Show version information when --help is used.
+#
+# This runs at import time, before Typer takes over, so it writes to
+# stdout directly: the Rich console the commands share is not built yet,
+# and this is user-facing CLI output rather than diagnostics, so routing
+# it through the logger (stderr, silenceable by level) would be wrong.
+if "--help" in sys.argv:
+    try:
+        sys.stdout.write(f"{format_version_string(styled=False)}\n")
+    except Exception as exc:
+        logger.debug("Failed to format version string: %s", exc, exc_info=True)
+        sys.stdout.write(
+            "\u26a0\ufe0f gerrit-clone version information not available\n"
+        )
+
+
+def version_callback(value: bool) -> None:
+    """Show version information."""
+    if value:
+        console = Console()
+        console.print(format_version_string())
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="gerrit-clone",
+    help="A multi-threaded CLI tool for bulk cloning repositories from Gerrit servers.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    add_completion=True,
+)
+
+VERSION = typer.Option(
+    None,
+    "--version",
+    callback=version_callback,
+    is_eager=True,
+    help="Show version information",
+)
+
+
+@app.callback()
+def main(
+    version: bool | None = VERSION,
+) -> None:
+    """Main CLI entry point with top-level options."""
+    pass

gerrit_clone-2.2.2/src/gerrit_clone/cli_clone.py

@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+
+"""Definition of the ``clone`` command.
+
+Declares the command line surface and hands the parsed arguments to
+:mod:`gerrit_clone.cli_clone_run`, which performs the work.
+
+Unlike the rest of the package this module deliberately omits
+``from __future__ import annotations``: Typer resolves the command
+signature's annotations at runtime to derive each parameter type.
+"""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from gerrit_clone import cli_options_clone as opts
+from gerrit_clone.cli_clone_models import CloneRequest
+from gerrit_clone.cli_clone_run import handle_crash, handle_interrupt, run_clone
+from gerrit_clone.cli_session import CliSession
+from gerrit_clone.concurrent_utils import handle_sigint_gracefully
+
+
+def clone(
+    host: str = opts.HOST,
+    source_type: str | None = opts.SOURCE_TYPE,
+    github_token: str | None = opts.GITHUB_TOKEN,
+    github_org: str | None = opts.GITHUB_ORG,
+    use_gh_cli: bool = opts.USE_GH_CLI,
+    port: int | None = opts.PORT,
+    base_url: str | None = opts.BASE_URL,
+    ssh_user: str | None = opts.SSH_USER,
+    ssh_identity_file: Path | None = opts.SSH_IDENTITY_FILE,
+    output_path: Path = opts.OUTPUT_PATH,
+    skip_archived: bool = opts.SKIP_ARCHIVED,
+    include_projects: list[str] | None = opts.INCLUDE_PROJECTS,
+    exclude_projects: list[str] | None = opts.EXCLUDE_PROJECTS,
+    ssh_debug: bool = opts.SSH_DEBUG,
+    discovery_method: str | None = opts.DISCOVERY_METHOD,
+    allow_nested_git: bool = opts.ALLOW_NESTED_GIT,
+    nested_protection: bool = opts.NESTED_PROTECTION,
+    move_conflicting: bool = opts.MOVE_CONFLICTING,
+    threads: int | None = opts.THREADS,
+    depth: int | None = opts.DEPTH,
+    branch: str | None = opts.BRANCH,
+    mirror: bool | None = opts.MIRROR,
+    use_https: bool = opts.USE_HTTPS,
+    keep_remote_protocol: bool = opts.KEEP_REMOTE_PROTOCOL,
+    strict_host_checking: bool = opts.STRICT_HOST_CHECKING,
+    clone_timeout: int = opts.CLONE_TIMEOUT,
+    retry_attempts: int = opts.RETRY_ATTEMPTS,
+    retry_base_delay: float = opts.RETRY_BASE_DELAY,
+    retry_factor: float = opts.RETRY_FACTOR,
+    retry_max_delay: float = opts.RETRY_MAX_DELAY,
+    manifest_filename: str = opts.MANIFEST_FILENAME,
+    config_file: Path | None = opts.CONFIG_FILE,
+    verbose: bool = opts.VERBOSE,
+    quiet: bool = opts.QUIET,
+    cleanup: bool = opts.CLEANUP,
+    no_refresh: bool = opts.NO_REFRESH,
+    force: bool = opts.FORCE,
+    fetch_only: bool = opts.FETCH_ONLY,
+    skip_conflicts: bool = opts.SKIP_CONFLICTS,
+    exit_on_error: bool = opts.EXIT_ON_ERROR,
+    log_file: Path | None = opts.LOG_FILE,
+    disable_log_file: bool = opts.DISABLE_LOG_FILE,
+    log_level: str = opts.LOG_LEVEL,
+    http_user: str | None = opts.HTTP_USER,
+    http_password: str | None = opts.HTTP_PASSWORD,
+    no_netrc: bool = opts.NO_NETRC,
+    netrc_file: Path | None = opts.NETRC_FILE,
+    netrc_optional: bool = opts.NETRC_OPTIONAL,
+    remove_files: str | None = opts.REMOVE_FILES,
+    git_filter: str | None = opts.GIT_FILTER,
+    redact_secrets: bool = opts.REDACT_SECRETS,
+) -> None:
+    """Clone all repositories from a Gerrit server or GitHub organization.
+
+    This command discovers all projects/repositories from the specified source and clones
+    them in parallel while preserving the project hierarchy. For Gerrit, repositories are
+    cloned over SSH by default. For GitHub, SSH is also default (HTTPS with --https).
+
+    By default, existing repositories are refreshed (git pull) instead of skipped.
+    Use --no-refresh to skip existing repositories without updating them.
+
+    Examples:
+
+        # Clone all active repositories from Gerrit server
+        gerrit-clone clone --host gerrit.example.org
+
+        # Clone all repositories from GitHub organization (auto-refresh existing)
+        gerrit-clone clone --host github.com/lfreleng-actions
+
+        # Clone without refreshing existing repos
+        gerrit-clone clone --host github.com/myorg --no-refresh
+
+        # Force refresh existing repos (stash local changes)
+        gerrit-clone clone --host github.com/myorg --force
+
+        # Clone GitHub org with gh CLI (preserves upstream/origin)
+        gerrit-clone clone --host github.com/myorg --use-gh-cli
+
+        # Clone to specific directory with custom threads
+        gerrit-clone clone --host gerrit.example.org --output-path ./repos --threads 8
+
+        # Clone with shallow depth and specific branch
+        gerrit-clone clone --host gerrit.example.org --no-mirror --depth 10 --branch main
+
+        # Clone with explicit HTTP credentials (highest priority)
+        gerrit-clone clone --host gerrit.example.org --https --http-user myuser --http-password mypass
+
+        # Clone with credentials from specific .netrc file
+        gerrit-clone clone --host gerrit.example.org --netrc-file ~/.netrc.gerrit
+
+        # Clone requiring .netrc credentials (fail if not found)
+        gerrit-clone clone --host gerrit.example.org --netrc-required
+    """
+    # Configure graceful interrupt handling for multi-threaded operations
+    handle_sigint_gracefully()
+
+    console = Console(stderr=True)
+    session = CliSession(console=console)
+    request = CloneRequest(
+        host=host,
+        source_type=source_type,
+        github_token=github_token,
+        github_org=github_org,
+        use_gh_cli=use_gh_cli,
+        port=port,
+        base_url=base_url,
+        ssh_user=ssh_user,
+        ssh_identity_file=ssh_identity_file,
+        output_path=output_path,
+        skip_archived=skip_archived,
+        include_projects=include_projects,
+        exclude_projects=exclude_projects,
+        ssh_debug=ssh_debug,
+        discovery_method=discovery_method,
+        allow_nested_git=allow_nested_git,
+        nested_protection=nested_protection,
+        move_conflicting=move_conflicting,
+        threads=threads,
+        depth=depth,
+        branch=branch,
+        mirror=mirror,
+        use_https=use_https,
+        keep_remote_protocol=keep_remote_protocol,
+        strict_host_checking=strict_host_checking,
+        clone_timeout=clone_timeout,
+        retry_attempts=retry_attempts,
+        retry_base_delay=retry_base_delay,
+        retry_factor=retry_factor,
+        retry_max_delay=retry_max_delay,
+        manifest_filename=manifest_filename,
+        config_file=config_file,
+        verbose=verbose,
+        quiet=quiet,
+        cleanup=cleanup,
+        no_refresh=no_refresh,
+        force=force,
+        fetch_only=fetch_only,
+        skip_conflicts=skip_conflicts,
+        exit_on_error=exit_on_error,
+        log_file=log_file,
+        disable_log_file=disable_log_file,
+        log_level=log_level,
+        http_user=http_user,
+        http_password=http_password,
+        no_netrc=no_netrc,
+        netrc_file=netrc_file,
+        netrc_optional=netrc_optional,
+        remove_files=remove_files,
+        git_filter=git_filter,
+        redact_secrets=redact_secrets,
+    )
+
+    try:
+        run_clone(request, session)
+    except KeyboardInterrupt:
+        handle_interrupt(session)
+    except typer.Exit:
+        # Re-raise typer.Exit exceptions without catching them as generic exceptions
+        session.write_summary()
+        raise
+    except Exception as e:
+        handle_crash(session, e, verbose=verbose)

gerrit_clone-2.2.2/src/gerrit_clone/cli_clone_models.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+
+"""The parsed ``clone`` command line.
+
+``CloneRequest`` carries the command's arguments unchanged between the
+pipeline steps in :mod:`gerrit_clone.cli_clone_setup` and
+:mod:`gerrit_clone.cli_clone_run`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CloneRequest:
+    """Command line arguments supplied to the ``clone`` command."""
+
+    host: str
+    source_type: str | None
+    github_token: str | None
+    github_org: str | None
+    use_gh_cli: bool
+    port: int | None
+    base_url: str | None
+    ssh_user: str | None
+    ssh_identity_file: Path | None
+    output_path: Path
+    skip_archived: bool
+    include_projects: list[str] | None
+    exclude_projects: list[str] | None
+    ssh_debug: bool
+    discovery_method: str | None
+    allow_nested_git: bool
+    nested_protection: bool
+    move_conflicting: bool
+    threads: int | None
+    depth: int | None
+    branch: str | None
+    mirror: bool | None
+    use_https: bool
+    keep_remote_protocol: bool
+    strict_host_checking: bool
+    clone_timeout: int
+    retry_attempts: int
+    retry_base_delay: float
+    retry_factor: float
+    retry_max_delay: float
+    manifest_filename: str
+    config_file: Path | None
+    verbose: bool
+    quiet: bool
+    cleanup: bool
+    no_refresh: bool
+    force: bool
+    fetch_only: bool
+    skip_conflicts: bool
+    exit_on_error: bool
+    log_file: Path | None
+    disable_log_file: bool
+    log_level: str
+    http_user: str | None
+    http_password: str | None
+    no_netrc: bool
+    netrc_file: Path | None
+    netrc_optional: bool
+    remove_files: str | None
+    git_filter: str | None
+    redact_secrets: bool