git-rexec 1.0.2__tar.gz → 1.0.4__tar.gz

{git_rexec-1.0.2/git_rexec.egg-info → git_rexec-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-rexec
-Version: 1.0.2
+Version: 1.0.4
 Summary: Locate Git repositories and execute commands against them in parallel.
 Author: James Cherti
 License-Expression: GPL-3.0-or-later
@@ -21,36 +21,36 @@ Requires-Dist: setproctitle; extra == "extras"
 The [git-rexec](https://github.com/jamescherti/git-rexec/) command-line tool recursively locates Git repositories within a directory and executes commands against them, either sequentially or in parallel.
 
 Here are examples demonstrating how to use `git-rexec`:
-- Execute `git status -s` across all discovered Git repositories (found by searching recursively under the current working directory) in parallel (`-p` or `--parallel`):
-  ```
-  git-rexec -p -- git status -s
-  ```
 
-- Fetch updates across all discovered repositories, limiting the concurrency to 5 background jobs (`-j 5`), which helps avoid network congestion or server rate limits when communicating with upstream Git remotes:
-  ```bash
-  git-rexec -j 5 --parallel -- git fetch
-  ```
+Example 1: Execute `git status -s` across all discovered Git repositories (found by searching recursively under the current working directory) in parallel (`-p` or `--parallel`):
+```
+git-rexec -p -- git status -s
+```
 
+Example 2: Fetch updates across all discovered repositories, limiting the concurrency to 5 background jobs (`-j 5`), which helps avoid network congestion or server rate limits when communicating with upstream Git remotes:
+```bash
+git-rexec -j 5 --parallel -- git fetch
+```
 
-- Include sub-repositories (e.g., Git worktrees and submodules) alongside standard Git repositories during discovery (`-s` or `--include-sub-repos`), and execute `git status` against them:
-  ```bash
-  git-rexec -s -p -- git status
-  ```
+Example 3: Include sub-repositories (e.g., Git worktrees and submodules) alongside standard Git repositories during discovery (`-s` or `--include-sub-repos`), and execute `git status` against them:
+```bash
+git-rexec -s -p -- git status
+```
 
-- Target a specific base directory (`~/projects`) using the `-C` flag to recursively discover repositories within it, while explicitly excluding a specific subfolder (`~/projects/archive`). This example executes `git status -s` in parallel for all discovered repositories except those within the excluded path:
-  ```bash
-  git-rexec -C ~/projects --exclude-dir ~/projects/archive --parallel -- git status -s
-  ```
+Example 4: Target a specific base directory (`~/projects`) using the `-C` flag to recursively discover repositories within it, while explicitly excluding a specific subfolder (`~/projects/archive`). This example executes `git status -s` in parallel for all discovered repositories except those within the excluded path:
+```bash
+git-rexec -C ~/projects --exclude-dir ~/projects/archive --parallel -- git status -s
+```
 
-- Evaluate whether a `README.md` file exists in the repository (`sh -c "test -f README.md"`). If the condition returns an exit status of 0 (success), it counts the number of lines in that file (`wc -l README.md`):
-  ```bash
-  git-rexec --if-exec 'sh -c "test -f README.md"' --parallel -- wc -l README.md
-  ```
+Example 5: Evaluate whether a `README.md` file exists in the repository (`sh -c "test -f README.md"`). If the condition returns an exit status of 0 (success), it counts the number of lines in that file (`wc -l README.md`):
+```bash
+git-rexec --if-exec 'sh -c "test -f README.md"' --parallel -- wc -l README.md
+```
 
-- Print the paths of all discovered Git repositories:
-  ```bash
-  git-rexec --print
-  ```
+Example 6: Print the paths of all discovered Git repositories:
+```bash
+git-rexec --print
+```
 
 If this helps your workflow, please support the project by **⭐ starring git-rexec on GitHub** and sharing it on your website, blog, Mastodon, Reddit, X, LinkedIn, or other social media platforms to help more Git users discover its benefits.
 
@@ -101,7 +101,7 @@ pip install colorama setproctitle
 ## Usage
 
 ```bash
-git-rexec [OPTIONS] [exec_cmd ...]
+git-rexec [OPTIONS] -- [exec_cmd ...]
 ```
 
 *(Assuming the `git-rexec` script is executable and in your PATH.)*
@@ -112,14 +112,31 @@ git-rexec [OPTIONS] [exec_cmd ...]
 
 ### Options
 
-- `-C, --directory <path>`: The root directory to start searching for Git repositories. Defaults to the current working directory (`.`).
-- `--exclude-dir <path>`: Exclude a specific directory and all of its subdirectories from the search. This option can be provided multiple times.
-- `-p, --parallel`: Execute the command in parallel using threads.
-- `-i, --if-exec <command>`: Execute the main command only if this check command returns an exit code of `0`.
-- `-j, --jobs <int>`: The maximum number of concurrent workers/processors to use for parallel execution. Defaults to the number of CPU cores available.
-- `-s, --include-sub-repos`: Include sub-repositories (e.g., Git worktrees and submodules) in the search target list.
-- `-h, --help`: Show the help message and exit.
-- `-q, --quiet`: Quiet mode. Suppresses the informational tracking headers (`[EXEC]` and `[EXEC-P]`) that prefix execution output. In sequential mode, it hides the `[EXEC]` repository delimiter line entirely; in parallel mode (`-p`), it strips the yellow `[EXEC-P]` header track and removes the four-space indentation, printing only the raw, unindented stdout and stderr streams. This flag has no effect when no execution command is supplied, allowing discovered repository paths to print normally.
+```
+usage: git-rexec [-h] [-C DIRECTORY] [--exclude-dir EXCLUDE_DIR] [-p] [-i IF_EXEC] [-j MAX_WORKERS] [-q] [-s] [--print] [--print0] [exec_cmd ...]
+
+Find Git repositories and execute commands against them in parallel.
+
+positional arguments:
+  exec_cmd              The command to execute. You can use -- to pass options.
+
+options:
+  -h, --help            show this help message and exit
+  -C, --directory DIRECTORY
+                        Root directory to search (defaults to current directory)
+  --exclude-dir EXCLUDE_DIR
+                        Exclude a specific directory and all of its subdirectories
+  -p, --parallel        Execute the command in parallel using threads
+  -i, --if-exec IF_EXEC
+                        Execute commands only if this check returns exit code 0.
+  -j, --jobs MAX_WORKERS
+                        Maximum number of processors/workers to use
+  -q, --quiet           Quiet mode. Suppresses the informational log prefixes ([EXEC] and [EXEC-P]) that precede execution output.
+  -s, --include-sub-repos
+                        Include sub-repositories (e.g., Git worktrees and submodules)
+  --print               Print the paths (only when no command is provided)
+  --print0              Separate the paths with a null character (only when no command is provided)
+```
 
 ## License
 

git_rexec-1.0.4/README.md

@@ -0,0 +1,131 @@
+# git-rexec: Find Git Repositories and Execute Commands Against Them, either Sequentially or in Parallel
+
+The [git-rexec](https://github.com/jamescherti/git-rexec/) command-line tool recursively locates Git repositories within a directory and executes commands against them, either sequentially or in parallel.
+
+Here are examples demonstrating how to use `git-rexec`:
+
+Example 1: Execute `git status -s` across all discovered Git repositories (found by searching recursively under the current working directory) in parallel (`-p` or `--parallel`):
+```
+git-rexec -p -- git status -s
+```
+
+Example 2: Fetch updates across all discovered repositories, limiting the concurrency to 5 background jobs (`-j 5`), which helps avoid network congestion or server rate limits when communicating with upstream Git remotes:
+```bash
+git-rexec -j 5 --parallel -- git fetch
+```
+
+Example 3: Include sub-repositories (e.g., Git worktrees and submodules) alongside standard Git repositories during discovery (`-s` or `--include-sub-repos`), and execute `git status` against them:
+```bash
+git-rexec -s -p -- git status
+```
+
+Example 4: Target a specific base directory (`~/projects`) using the `-C` flag to recursively discover repositories within it, while explicitly excluding a specific subfolder (`~/projects/archive`). This example executes `git status -s` in parallel for all discovered repositories except those within the excluded path:
+```bash
+git-rexec -C ~/projects --exclude-dir ~/projects/archive --parallel -- git status -s
+```
+
+Example 5: Evaluate whether a `README.md` file exists in the repository (`sh -c "test -f README.md"`). If the condition returns an exit status of 0 (success), it counts the number of lines in that file (`wc -l README.md`):
+```bash
+git-rexec --if-exec 'sh -c "test -f README.md"' --parallel -- wc -l README.md
+```
+
+Example 6: Print the paths of all discovered Git repositories:
+```bash
+git-rexec --print
+```
+
+If this helps your workflow, please support the project by **⭐ starring git-rexec on GitHub** and sharing it on your website, blog, Mastodon, Reddit, X, LinkedIn, or other social media platforms to help more Git users discover its benefits.
+
+## Features
+
+- Recursively discover Git repositories starting from a specified root directory.
+- Optional flag to include sub-repositories (e.g., Git worktrees and submodules) in the execution target list.
+- Execute shell commands across multiple repositories in parallel using worker threads.
+- Filter target repositories based on the exit code of a conditional check (`--if-exec`).
+- Exclude specific directories from the search path.
+- Export discovered repository paths for integration with other shell tools (using `--print` or `--print0`).
+
+## Installation
+
+### Method 1: Manual Installation (System-wide)
+
+Download the `git-rexec` script, make it executable, and copy it to a directory in your system PATH (e.g., `/usr/local/bin`):
+
+```bash
+sudo cp git-rexec /usr/local/bin/
+```
+
+### Method 2: Installation via pip
+
+Install the package directly from the Git repository using `pip`:
+
+```bash
+pip install --user git-rexec
+```
+
+## Dependencies
+
+### System Dependencies
+
+- `git`: Required for repository validation and execution.
+
+### Python Dependencies (Optional)
+
+- `colorama`: Provides color-coded terminal output.
+- `setproctitle`: Sets the process title for process monitoring tools.
+
+You can install the optional Python dependencies via pip:
+
+```bash
+pip install colorama setproctitle
+```
+
+## Usage
+
+```bash
+git-rexec [OPTIONS] -- [exec_cmd ...]
+```
+
+*(Assuming the `git-rexec` script is executable and in your PATH.)*
+
+### Positional Arguments
+
+- `exec_cmd`: The shell command to execute within each discovered Git repository. You can use `--` to pass options directly to the command. If omitted, the script simply prints the paths of the discovered repositories.
+
+### Options
+
+```
+usage: git-rexec [-h] [-C DIRECTORY] [--exclude-dir EXCLUDE_DIR] [-p] [-i IF_EXEC] [-j MAX_WORKERS] [-q] [-s] [--print] [--print0] [exec_cmd ...]
+
+Find Git repositories and execute commands against them in parallel.
+
+positional arguments:
+  exec_cmd              The command to execute. You can use -- to pass options.
+
+options:
+  -h, --help            show this help message and exit
+  -C, --directory DIRECTORY
+                        Root directory to search (defaults to current directory)
+  --exclude-dir EXCLUDE_DIR
+                        Exclude a specific directory and all of its subdirectories
+  -p, --parallel        Execute the command in parallel using threads
+  -i, --if-exec IF_EXEC
+                        Execute commands only if this check returns exit code 0.
+  -j, --jobs MAX_WORKERS
+                        Maximum number of processors/workers to use
+  -q, --quiet           Quiet mode. Suppresses the informational log prefixes ([EXEC] and [EXEC-P]) that precede execution output.
+  -s, --include-sub-repos
+                        Include sub-repositories (e.g., Git worktrees and submodules)
+  --print               Print the paths (only when no command is provided)
+  --print0              Separate the paths with a null character (only when no command is provided)
+```
+
+## License
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+Copyright (C) 2019-2026 [James Cherti](https://www.jamescherti.com).
+
+## Links
+
+- [git-rexec @GitHub](https://github.com/jamescherti/git-rexec)

{git_rexec-1.0.2 → git_rexec-1.0.4}/git-rexec

@@ -6,7 +6,7 @@
 #
 # Author: James Cherti
 # URL: https://github.com/jamescherti/git-rexec
-# Version: 1.0.2
+# Version: 1.0.4
 #
 # Copyright (C) 2019-2026 James Cherti
 #
@@ -30,6 +30,8 @@ and executing commands against them. It supports conditional filtering,
 background execution, and sequential foreground execution.
 """
 
+from __future__ import annotations
+
 import argparse
 import os
 import shlex
@@ -41,16 +43,18 @@ from concurrent.futures import Future, ThreadPoolExecutor, as_completed
 from dataclasses import dataclass
 from multiprocessing import cpu_count
 from pathlib import Path
-from typing import Optional
 
 try:
     from colorama import Fore
     from colorama import init as colorama_init
+
     HAS_COLORAMA: bool = True
 except ImportError:
     HAS_COLORAMA = False
 
     class Fore:  # type: ignore
+        """Provide fallback empty strings for missing colorama Fore attributes."""
+
         YELLOW: str = ""
         RED: str = ""
         RESET: str = ""
@@ -65,6 +69,7 @@ class CommandResult:
     :param stdout: Standard output content.
     :param stderr: Standard error content.
     """
+
     command: list[str]
     returncode: int
     stdout: str = ""
@@ -78,11 +83,12 @@ class RepoContext:
     :param path: The absolute path to the repository root.
     :param parallel_result: The result of the parallel execution, if any.
     """
+
     path: Path
-    parallel_result: Optional[CommandResult] = None
+    parallel_result: CommandResult | None = None
 
 
-def git_toplevel(repo_path: Path) -> Optional[Path]:
+def git_toplevel(repo_path: Path) -> Path | None:
     """Return the absolute path to the top-level directory of a Git repository.
 
     :param repo_path: Path inside the Git repository.
@@ -90,39 +96,78 @@ def git_toplevel(repo_path: Path) -> Optional[Path]:
              Git repo.
     """
     try:
-        proc: subprocess.CompletedProcess[str] = subprocess.run(
-            ["git", "-C", str(repo_path), "rev-parse", "--show-toplevel"],
-            capture_output=True,
-            text=True,
-            check=True
-        )
+        proc: subprocess.CompletedProcess[str] = \
+            subprocess.run(["git", "-C", str(repo_path), "rev-parse",
+                            "--show-toplevel"],
+                           capture_output=True,
+                           text=True,
+                           check=True)
         return Path(proc.stdout.strip()).resolve()
     except subprocess.CalledProcessError:
         return None
 
 
-def git_py_find_repo(root: Path) -> tuple[set[Path], set[Path]]:
+def git_find_repo(root: Path, exclude_paths: list[Path] | None = None) \
+        -> tuple[set[Path], set[Path]]:
     """Recursively find all Git repositories under the root path using Python.
 
     :param root: Directory to search under.
+    :param exclude_paths: Directories to exclude to optimize traversal.
     :return: A tuple containing standard repository paths and sub-repository
     paths.
     """
+    root_res: Path = root.resolve()
+
+    # Paths are already resolved by discover_repos
+    ex_resolved: set[Path] = set(exclude_paths) if exclude_paths else set()
+
+    # Do not begin traversal if the root itself is excluded
     repos: set[Path] = set()
     sub_repos: set[Path] = set()
-
-    for dirpath, dirnames, filenames in os.walk(root):
-        if ".git" in dirnames:
-            repos.add(Path(dirpath).absolute())
-        elif ".git" in filenames:
-            sub_repos.add(Path(dirpath).absolute())
-        else:
+    if ex_resolved and any((root_res == ex_path or
+                            root_res.is_relative_to(ex_path))
+                           for ex_path in ex_resolved):
+        return repos, sub_repos
+
+    # Store Path objects internally to simplify maintenance
+    dirs_to_visit: list[Path] = [root_res]
+    while dirs_to_visit:
+        current_dir: Path = dirs_to_visit.pop()
+
+        try:
+            with os.scandir(current_dir) as iter_scandir:
+                dirs_in_current: list[Path] = []
+                is_repo: bool = False
+
+                for entry in iter_scandir:
+                    if entry.name == ".git":
+                        is_repo = True
+                        if entry.is_dir():
+                            repos.add(current_dir)
+                        elif entry.is_file():
+                            sub_repos.add(current_dir)
+
+                        # Found the repository, stop evaluating this directory
+                        break
+
+                    try:
+                        # Using follow_symlinks=False avoids an extra
+                        # is_symlink() call
+                        if entry.is_dir(follow_symlinks=False):
+                            entry_path: Path = Path(entry.path)
+                            if ex_resolved and entry_path in ex_resolved:
+                                continue
+                            dirs_in_current.append(entry_path)
+                    except OSError:
+                        continue
+
+                if not is_repo:
+                    # Append collected directories only if we are not inside a
+                    # repository
+                    dirs_to_visit.extend(dirs_in_current)
+        except OSError:
             continue
 
-        # Clear dirnames to prevent os.walk from descending into
-        # subdirectories
-        dirnames.clear()
-
     return repos, sub_repos
 
 
@@ -133,18 +178,19 @@ def get_sub_repos(repo_path: Path) -> set[Path]:
     :return: A set of absolute paths to worktrees and submodules.
     """
     sub_repos: set[Path] = set()
+    repo_path_resolved: Path = repo_path.resolve()
 
     # Discover worktrees
     # pylint: disable=too-many-try-statements
     try:
-        wt_proc: subprocess.CompletedProcess[str] = subprocess.run(
-            ["git", "-C", str(repo_path), "worktree", "list", "--porcelain"],
-            capture_output=True,
-            text=True,
-            check=True,
-        )
-
-        current_wt: Optional[Path] = None
+        wt_proc: subprocess.CompletedProcess[str] = \
+            subprocess.run(["git", "-C", str(repo_path),
+                            "worktree", "list", "--porcelain"],
+                           capture_output=True,
+                           text=True,
+                           check=True)
+
+        current_wt: Path | None = None
         is_bare: bool = False
 
         for line in wt_proc.stdout.splitlines():
@@ -152,8 +198,8 @@ def get_sub_repos(repo_path: Path) -> set[Path]:
 
             # Git porcelain separates blocks with a blank line
             if not line:
-                if current_wt and not is_bare \
-                        and current_wt != repo_path.resolve():
+                if (current_wt and
+                        not is_bare and current_wt != repo_path_resolved):
                     sub_repos.add(current_wt)
                 # Reset state for the next block
                 current_wt = None
@@ -166,7 +212,7 @@ def get_sub_repos(repo_path: Path) -> set[Path]:
                 is_bare = True
 
         # Process the final block in case the output lacks a trailing newline
-        if current_wt and not is_bare and current_wt != repo_path.resolve():
+        if current_wt and not is_bare and current_wt != repo_path_resolved:
             sub_repos.add(current_wt)
 
     except subprocess.CalledProcessError:
@@ -174,13 +220,12 @@ def get_sub_repos(repo_path: Path) -> set[Path]:
 
     # Discover submodules
     try:
-        sm_proc: subprocess.CompletedProcess[str] = subprocess.run(
-            ["git", "-C", str(repo_path),
-             "submodule", "foreach", "--quiet", "pwd"],
-            capture_output=True,
-            text=True,
-            check=True,
-        )
+        sm_proc: subprocess.CompletedProcess[str] = \
+            subprocess.run(["git", "-C", str(repo_path), "submodule",
+                            "foreach", "--quiet", "pwd",],
+                           capture_output=True,
+                           text=True,
+                           check=True)
 
         for line in sm_proc.stdout.splitlines():
             sm_path: Path = Path(line.strip()).resolve()
@@ -192,7 +237,8 @@ def get_sub_repos(repo_path: Path) -> set[Path]:
     return sub_repos
 
 
-def run_command_get_output(repo_path: Path, cmd_list: list[str],
+def run_command_get_output(repo_path: Path,
+                           cmd_list: list[str],
                            capture: bool = True) -> CommandResult:
     """Execute a shell command within a specific directory.
 
@@ -205,19 +251,13 @@ def run_command_get_output(repo_path: Path, cmd_list: list[str],
         return CommandResult(command=[], returncode=0)
 
     try:
-        proc: subprocess.CompletedProcess[str] = subprocess.run(
-            cmd_list,
-            cwd=repo_path,
-            capture_output=capture,
-            text=True,
-            check=False
-        )
-        return CommandResult(
-            command=cmd_list,
-            returncode=proc.returncode,
-            stdout=proc.stdout if proc.stdout else "",
-            stderr=proc.stderr if proc.stderr else ""
-        )
+        proc: subprocess.CompletedProcess[str] = \
+            subprocess.run(cmd_list, cwd=repo_path, capture_output=capture,
+                           text=True, check=False,)
+        return CommandResult(command=cmd_list,
+                             returncode=proc.returncode,
+                             stdout=proc.stdout if proc.stdout else "",
+                             stderr=proc.stderr if proc.stderr else "")
     except FileNotFoundError:
         return CommandResult(
             command=cmd_list,
@@ -226,8 +266,8 @@ def run_command_get_output(repo_path: Path, cmd_list: list[str],
         )
 
 
-def format_parallel_output(
-        repo_path: Path, result: CommandResult, quiet: bool = False) -> str:
+def format_parallel_output(repo_path: Path,
+                           result: CommandResult, quiet: bool = False) -> str:
     """Format the output of a parallel command for display.
 
     :param repo_path: The repository path.
@@ -255,8 +295,9 @@ def format_parallel_output(
     return header + indented_body
 
 
-def process_repo(repo_path: Path, exec_parallel_cmd: Optional[list[str]],
-                 if_exec_cmd: Optional[list[str]]) -> Optional[RepoContext]:
+def process_repo(repo_path: Path,
+                 exec_parallel_cmd: list[str] | None,
+                 if_exec_cmd: list[str] | None) -> RepoContext | None:
     """Process a single repository: check conditions and run parallel commands.
 
     :param repo_path: The repository path.
@@ -265,22 +306,23 @@ def process_repo(repo_path: Path, exec_parallel_cmd: Optional[list[str]],
     :return: RepoContext if processed successfully, None if filtered out.
     """
     # Filter: if-exec
-    if_exec_cmd_list: Optional[list[str]] = if_exec_cmd
+    if_exec_cmd_list: list[str] | None = if_exec_cmd
     if if_exec_cmd_list:
         # We discard output for the filter check, only caring about exit code
-        filter_res: CommandResult = run_command_get_output(
-            repo_path, if_exec_cmd_list, capture=True
-        )
+        filter_res: CommandResult = run_command_get_output(repo_path,
+                                                           if_exec_cmd_list,
+                                                           capture=True)
         if filter_res.returncode != 0:
             return None
 
     # Action: exec-parallel
-    parallel_result: Optional[CommandResult] = None
-    exec_parallel_cmd_list: Optional[list[str]] = exec_parallel_cmd
+    parallel_result: CommandResult | None = None
+    exec_parallel_cmd_list: list[str] | None = exec_parallel_cmd
     if exec_parallel_cmd_list:
-        parallel_result = run_command_get_output(
-            repo_path, exec_parallel_cmd_list, capture=True
-        )
+        parallel_result = \
+            run_command_get_output(repo_path,
+                                   exec_parallel_cmd_list,
+                                   capture=True)
 
     return RepoContext(path=repo_path, parallel_result=parallel_result)
 
@@ -300,12 +342,18 @@ def discover_repos(directory: Path,
     repos: set[Path] = set()
     worktrees: set[Path] = set()
 
+    list_ex_paths: list[Path] = (
+        [Path(ex_dir).resolve() for ex_dir in exclude_dirs]
+        if exclude_dirs
+        else []
+    )
+
     # Discover all repositories
-    toplevel: Optional[Path] = git_toplevel(directory)
+    toplevel: Path | None = git_toplevel(directory)
     if toplevel:
         repos = {toplevel}
     else:
-        repos, worktrees = git_py_find_repo(directory)
+        repos, worktrees = git_find_repo(directory, list_ex_paths)
 
     # Extract and append sub-repositories concurrently if requested
     if include_sub_repos:
@@ -321,25 +369,22 @@ def discover_repos(directory: Path,
 
         repos.update(sub_repos)
 
-    # Filter out excluded directories
-    if not exclude_dirs:
+    # Filter out excluded directories (applies dynamically to sub-repos too)
+    if not list_ex_paths:
         return repos
 
-    list_ex_paths: list[Path] = [Path(ex_dir).resolve()
-                                 for ex_dir in exclude_dirs]
     return {
-        repo for repo in repos
-        if not any(repo.resolve().is_relative_to(ex_path)
+        repo
+        for repo in repos
+        if not any(repo.is_relative_to(ex_path)
                    for ex_path in list_ex_paths)
     }
 
 
-def execute_parallel_tasks(
-    repos: set[Path],
-    exec_parallel: Optional[list[str]],
-    if_exec: Optional[list[str]],
-    max_workers: int
-) -> list[RepoContext]:
+def execute_parallel_tasks(repos: set[Path],
+                           exec_parallel: list[str] | None,
+                           if_exec: list[str] | None,
+                           max_workers: int) -> list[RepoContext]:
     """Run discovery and parallel execution tasks.
 
     :param repos: set of repositories to process.
@@ -351,16 +396,15 @@ def execute_parallel_tasks(
     results: list[RepoContext] = []
 
     with ThreadPoolExecutor(max_workers=max_workers) as executor:
-        futures: dict[Future[Optional[RepoContext]], Path] = {
-            executor.submit(
-                process_repo, repo, exec_parallel, if_exec
-            ): repo for repo in repos
+        futures: dict[Future[RepoContext | None], Path] = {
+            executor.submit(process_repo, repo, exec_parallel, if_exec): repo
+            for repo in repos
         }
 
         for future in as_completed(futures):
             repo_path: Path = futures[future]
             try:
-                result: Optional[RepoContext] = future.result()
+                result: RepoContext | None = future.result()
                 if result:
                     results.append(result)
             except (OSError, ValueError) as exc:
@@ -376,71 +420,82 @@ def parse_args() -> argparse.Namespace:
     :return: Parsed arguments.
     """
     parser: argparse.ArgumentParser = argparse.ArgumentParser(
-        description="Find git repos and execute commands.",
-        formatter_class=argparse.RawDescriptionHelpFormatter
+        description=("Find Git repositories and execute commands against "
+                     "them in parallel."),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     parser.add_argument(
-        "-C", "--directory",
+        "-C",
+        "--directory",
         type=Path,
         default=Path("."),
-        help="Root directory to search (defaults to current directory)"
+        help="Root directory to search (defaults to current directory)",
     )
     parser.add_argument(
         "--exclude-dir",
         action="append",
         default=[],
-        help="Exclude a specific directory and all of its subdirectories"
+        help="Exclude a specific directory and all of its subdirectories",
     )
     parser.add_argument(
-        "-p", "--parallel",
+        "-p",
+        "--parallel",
         action="store_true",
         help="Execute the command in parallel using threads",
-        default=False
+        default=False,
     )
     parser.add_argument(
-        "-i", "--if-exec",
+        "-i",
+        "--if-exec",
         type=str,
         help="Execute commands only if this check returns exit code 0.",
-        default=None
+        default=None,
     )
     parser.add_argument(
-        "-j", "--jobs",
+        "-j",
+        "--jobs",
         type=int,
         dest="max_workers",
         help="Maximum number of processors/workers to use",
-        default=(cpu_count() or 1)
+        default=(cpu_count() or 1),
     )
     parser.add_argument(
-        "-q", "--quiet",
+        "-q",
+        "--quiet",
         action="store_true",
-        help=("Quiet mode. Suppresses the informational tracking headers "
-              "([EXEC] and [EXEC-P]) that prefix execution output."),
-        default=False
+        help=(
+            "Quiet mode. Suppresses the informational log prefixes "
+            "([EXEC] and [EXEC-P]) that precede execution output."
+        ),
+        default=False,
     )
     parser.add_argument(
-        "-s", "--include-sub-repos",
+        "-s",
+        "--include-sub-repos",
         action="store_true",
         help="Include sub-repositories (e.g., Git worktrees and submodules)",
-        default=False
+        default=False,
     )
     parser.add_argument(
         "--print",
         action="store_true",
         help="Print the paths (only when no command is provided)",
-        default=False
+        default=False,
     )
     parser.add_argument(
         "--print0",
         action="store_true",
-        help=("Separate the paths with a null character (only when no "
-              "command is provided)"),
-        default=False
+        help=(
+            "Separate the paths with a null character (only when no "
+            "command is provided)"
+        ),
+        default=False,
     )
     parser.add_argument(
         "exec_cmd",
         type=str,
         nargs="*",
-        help="The command to execute. You can use -- to pass options."
+        help="The command to execute. You can use -- to pass options.",
     )
 
     args: argparse.Namespace = parser.parse_args()
@@ -484,6 +539,7 @@ def main() -> None:
     try:
         # pylint: disable=import-outside-toplevel
         from setproctitle import setproctitle
+
         setproctitle(Path(sys.argv[0]).name)  # type: ignore
     except ImportError:
         # Optional dependency 'setproctitle' is not installed.
@@ -500,13 +556,12 @@ def main() -> None:
     # Check for empty action
     if not args.exec_cmd and not args.print and not args.print0:
         print("Nothing to do.", file=sys.stderr)
-        sys.exit(0)
+        sys.exit(2)
 
     # Verify that the execution command exists
     if args.exec_cmd and not shutil.which(args.exec_cmd[0]):
-        print(
-            f"Error: Command not found: '{args.exec_cmd[0]}'",
-            file=sys.stderr)
+        print(f"Error: Command not found: '{args.exec_cmd[0]}'",
+              file=sys.stderr)
         sys.exit(127)
 
     # Discover Repositories
@@ -516,21 +571,20 @@ def main() -> None:
                                       args.include_sub_repos)
 
     # setup background command list if needed
-    exec_parallel_cmd: Optional[list[str]] = None
+    exec_parallel_cmd: list[str] | None = None
     if args.parallel and args.exec_cmd:
         exec_parallel_cmd = args.exec_cmd
 
-    if_exec_cmd: Optional[list[str]] = None
+    if_exec_cmd: list[str] | None = None
     if args.if_exec:
         if_exec_cmd = shlex.split(args.if_exec)
 
     # Parallel Processing (Filter + Background Exec)
-    processed_repos: list[RepoContext] = execute_parallel_tasks(
-        repos,
-        exec_parallel_cmd,
-        if_exec_cmd,
-        args.max_workers
-    )
+    processed_repos: list[RepoContext] = \
+        execute_parallel_tasks(repos,
+                               exec_parallel_cmd,
+                               if_exec_cmd,
+                               args.max_workers)
 
     execution_errors: list[tuple[Path, CommandResult]] = []
 
@@ -540,8 +594,10 @@ def main() -> None:
 
         # Handle Background Execution Results
         if context.parallel_result:
-            output_display: str = format_parallel_output(
-                repo_path, context.parallel_result, args.quiet)
+            output_display: str = \
+                format_parallel_output(repo_path,
+                                       context.parallel_result,
+                                       args.quiet)
             if output_display:
                 print(output_display, end="")
 
@@ -551,11 +607,9 @@ def main() -> None:
         # Handle Foreground Execution
         if args.exec_cmd and not args.parallel:
             if not args.quiet:
-                print(
-                    f"{Fore.YELLOW}[EXEC] {repo_path}: "
-                    f"{subprocess.list2cmdline(args.exec_cmd)}"
-                    f"{Fore.RESET}"
-                )
+                print(f"{Fore.YELLOW}[EXEC] {repo_path}: "
+                      f"{shlex.join(args.exec_cmd)}"
+                      f"{Fore.RESET}")
 
             # Run interactively/sequentially (capture=False allows interaction)
             # However, for consistency with error tracking, we might want to
@@ -564,23 +618,18 @@ def main() -> None:
                 # We use subprocess.check_call to allow direct stdout/stderr
                 # flow unless we want to capture for error summary. To match
                 # previous logic, we let it flow to stdout.
-                subprocess.check_call(
-                    args.exec_cmd,
-                    cwd=repo_path
-                )
+                subprocess.check_call(args.exec_cmd, cwd=repo_path)
             except subprocess.CalledProcessError as err:
                 # Construct a dummy result for the error summary
-                failed_res: CommandResult = CommandResult(
-                    command=args.exec_cmd,
-                    returncode=err.returncode
-                )
-                execution_errors.append((repo_path, failed_res))
+                execution_errors.append(
+                    (repo_path,
+                     CommandResult(command=args.exec_cmd,
+                                   returncode=err.returncode)))
             except FileNotFoundError:
-                failed_res: CommandResult = CommandResult(
-                    command=args.exec_cmd,
-                    returncode=127
-                )
-                execution_errors.append((repo_path, failed_res))
+                execution_errors.append(
+                    (repo_path,
+                     CommandResult(command=args.exec_cmd,
+                                   returncode=127)))
 
         # If no commands were run, just list the repo
         if not args.exec_cmd:
@@ -596,6 +645,7 @@ def main() -> None:
 if __name__ == "__main__":
     try:
         main()
-    except (KeyboardInterrupt, BrokenPipeError):
-        print("\nInterrupting...", file=sys.stderr)
-        sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except BrokenPipeError:
+        sys.exit(141)

{git_rexec-1.0.2 → git_rexec-1.0.4/git_rexec.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-rexec
-Version: 1.0.2
+Version: 1.0.4
 Summary: Locate Git repositories and execute commands against them in parallel.
 Author: James Cherti
 License-Expression: GPL-3.0-or-later
@@ -21,36 +21,36 @@ Requires-Dist: setproctitle; extra == "extras"
 The [git-rexec](https://github.com/jamescherti/git-rexec/) command-line tool recursively locates Git repositories within a directory and executes commands against them, either sequentially or in parallel.
 
 Here are examples demonstrating how to use `git-rexec`:
-- Execute `git status -s` across all discovered Git repositories (found by searching recursively under the current working directory) in parallel (`-p` or `--parallel`):
-  ```
-  git-rexec -p -- git status -s
-  ```
 
-- Fetch updates across all discovered repositories, limiting the concurrency to 5 background jobs (`-j 5`), which helps avoid network congestion or server rate limits when communicating with upstream Git remotes:
-  ```bash
-  git-rexec -j 5 --parallel -- git fetch
-  ```
+Example 1: Execute `git status -s` across all discovered Git repositories (found by searching recursively under the current working directory) in parallel (`-p` or `--parallel`):
+```
+git-rexec -p -- git status -s
+```
 
+Example 2: Fetch updates across all discovered repositories, limiting the concurrency to 5 background jobs (`-j 5`), which helps avoid network congestion or server rate limits when communicating with upstream Git remotes:
+```bash
+git-rexec -j 5 --parallel -- git fetch
+```
 
-- Include sub-repositories (e.g., Git worktrees and submodules) alongside standard Git repositories during discovery (`-s` or `--include-sub-repos`), and execute `git status` against them:
-  ```bash
-  git-rexec -s -p -- git status
-  ```
+Example 3: Include sub-repositories (e.g., Git worktrees and submodules) alongside standard Git repositories during discovery (`-s` or `--include-sub-repos`), and execute `git status` against them:
+```bash
+git-rexec -s -p -- git status
+```
 
-- Target a specific base directory (`~/projects`) using the `-C` flag to recursively discover repositories within it, while explicitly excluding a specific subfolder (`~/projects/archive`). This example executes `git status -s` in parallel for all discovered repositories except those within the excluded path:
-  ```bash
-  git-rexec -C ~/projects --exclude-dir ~/projects/archive --parallel -- git status -s
-  ```
+Example 4: Target a specific base directory (`~/projects`) using the `-C` flag to recursively discover repositories within it, while explicitly excluding a specific subfolder (`~/projects/archive`). This example executes `git status -s` in parallel for all discovered repositories except those within the excluded path:
+```bash
+git-rexec -C ~/projects --exclude-dir ~/projects/archive --parallel -- git status -s
+```
 
-- Evaluate whether a `README.md` file exists in the repository (`sh -c "test -f README.md"`). If the condition returns an exit status of 0 (success), it counts the number of lines in that file (`wc -l README.md`):
-  ```bash
-  git-rexec --if-exec 'sh -c "test -f README.md"' --parallel -- wc -l README.md
-  ```
+Example 5: Evaluate whether a `README.md` file exists in the repository (`sh -c "test -f README.md"`). If the condition returns an exit status of 0 (success), it counts the number of lines in that file (`wc -l README.md`):
+```bash
+git-rexec --if-exec 'sh -c "test -f README.md"' --parallel -- wc -l README.md
+```
 
-- Print the paths of all discovered Git repositories:
-  ```bash
-  git-rexec --print
-  ```
+Example 6: Print the paths of all discovered Git repositories:
+```bash
+git-rexec --print
+```
 
 If this helps your workflow, please support the project by **⭐ starring git-rexec on GitHub** and sharing it on your website, blog, Mastodon, Reddit, X, LinkedIn, or other social media platforms to help more Git users discover its benefits.
 
@@ -101,7 +101,7 @@ pip install colorama setproctitle
 ## Usage
 
 ```bash
-git-rexec [OPTIONS] [exec_cmd ...]
+git-rexec [OPTIONS] -- [exec_cmd ...]
 ```
 
 *(Assuming the `git-rexec` script is executable and in your PATH.)*
@@ -112,14 +112,31 @@ git-rexec [OPTIONS] [exec_cmd ...]
 
 ### Options
 
-- `-C, --directory <path>`: The root directory to start searching for Git repositories. Defaults to the current working directory (`.`).
-- `--exclude-dir <path>`: Exclude a specific directory and all of its subdirectories from the search. This option can be provided multiple times.
-- `-p, --parallel`: Execute the command in parallel using threads.
-- `-i, --if-exec <command>`: Execute the main command only if this check command returns an exit code of `0`.
-- `-j, --jobs <int>`: The maximum number of concurrent workers/processors to use for parallel execution. Defaults to the number of CPU cores available.
-- `-s, --include-sub-repos`: Include sub-repositories (e.g., Git worktrees and submodules) in the search target list.
-- `-h, --help`: Show the help message and exit.
-- `-q, --quiet`: Quiet mode. Suppresses the informational tracking headers (`[EXEC]` and `[EXEC-P]`) that prefix execution output. In sequential mode, it hides the `[EXEC]` repository delimiter line entirely; in parallel mode (`-p`), it strips the yellow `[EXEC-P]` header track and removes the four-space indentation, printing only the raw, unindented stdout and stderr streams. This flag has no effect when no execution command is supplied, allowing discovered repository paths to print normally.
+```
+usage: git-rexec [-h] [-C DIRECTORY] [--exclude-dir EXCLUDE_DIR] [-p] [-i IF_EXEC] [-j MAX_WORKERS] [-q] [-s] [--print] [--print0] [exec_cmd ...]
+
+Find Git repositories and execute commands against them in parallel.
+
+positional arguments:
+  exec_cmd              The command to execute. You can use -- to pass options.
+
+options:
+  -h, --help            show this help message and exit
+  -C, --directory DIRECTORY
+                        Root directory to search (defaults to current directory)
+  --exclude-dir EXCLUDE_DIR
+                        Exclude a specific directory and all of its subdirectories
+  -p, --parallel        Execute the command in parallel using threads
+  -i, --if-exec IF_EXEC
+                        Execute commands only if this check returns exit code 0.
+  -j, --jobs MAX_WORKERS
+                        Maximum number of processors/workers to use
+  -q, --quiet           Quiet mode. Suppresses the informational log prefixes ([EXEC] and [EXEC-P]) that precede execution output.
+  -s, --include-sub-repos
+                        Include sub-repositories (e.g., Git worktrees and submodules)
+  --print               Print the paths (only when no command is provided)
+  --print0              Separate the paths with a null character (only when no command is provided)
+```
 
 ## License
 

{git_rexec-1.0.2 → git_rexec-1.0.4}/git_rexec.egg-info/SOURCES.txt

@@ -1,4 +1,3 @@
-.gitignore
 README.md
 git-rexec
 pyproject.toml

{git_rexec-1.0.2 → git_rexec-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "git-rexec"
-version = "1.0.2"
+version = "1.0.4"
 description = "Locate Git repositories and execute commands against them in parallel."
 readme = "README.md"
 requires-python = ">=3.9"

git_rexec-1.0.2/.gitignore

@@ -1,6 +0,0 @@
-/coverage.json
-/build
-/dist
-/*.egg-info
-*.pyc
-*/__pycache__

git_rexec-1.0.2/README.md

@@ -1,114 +0,0 @@
-# git-rexec: Find Git Repositories and Execute Commands Against Them, either Sequentially or in Parallel
-
-The [git-rexec](https://github.com/jamescherti/git-rexec/) command-line tool recursively locates Git repositories within a directory and executes commands against them, either sequentially or in parallel.
-
-Here are examples demonstrating how to use `git-rexec`:
-- Execute `git status -s` across all discovered Git repositories (found by searching recursively under the current working directory) in parallel (`-p` or `--parallel`):
-  ```
-  git-rexec -p -- git status -s
-  ```
-
-- Fetch updates across all discovered repositories, limiting the concurrency to 5 background jobs (`-j 5`), which helps avoid network congestion or server rate limits when communicating with upstream Git remotes:
-  ```bash
-  git-rexec -j 5 --parallel -- git fetch
-  ```
-
-
-- Include sub-repositories (e.g., Git worktrees and submodules) alongside standard Git repositories during discovery (`-s` or `--include-sub-repos`), and execute `git status` against them:
-  ```bash
-  git-rexec -s -p -- git status
-  ```
-
-- Target a specific base directory (`~/projects`) using the `-C` flag to recursively discover repositories within it, while explicitly excluding a specific subfolder (`~/projects/archive`). This example executes `git status -s` in parallel for all discovered repositories except those within the excluded path:
-  ```bash
-  git-rexec -C ~/projects --exclude-dir ~/projects/archive --parallel -- git status -s
-  ```
-
-- Evaluate whether a `README.md` file exists in the repository (`sh -c "test -f README.md"`). If the condition returns an exit status of 0 (success), it counts the number of lines in that file (`wc -l README.md`):
-  ```bash
-  git-rexec --if-exec 'sh -c "test -f README.md"' --parallel -- wc -l README.md
-  ```
-
-- Print the paths of all discovered Git repositories:
-  ```bash
-  git-rexec --print
-  ```
-
-If this helps your workflow, please support the project by **⭐ starring git-rexec on GitHub** and sharing it on your website, blog, Mastodon, Reddit, X, LinkedIn, or other social media platforms to help more Git users discover its benefits.
-
-## Features
-
-- Recursively discover Git repositories starting from a specified root directory.
-- Optional flag to include sub-repositories (e.g., Git worktrees and submodules) in the execution target list.
-- Execute shell commands across multiple repositories in parallel using worker threads.
-- Filter target repositories based on the exit code of a conditional check (`--if-exec`).
-- Exclude specific directories from the search path.
-- Export discovered repository paths for integration with other shell tools (using `--print` or `--print0`).
-
-## Installation
-
-### Method 1: Manual Installation (System-wide)
-
-Download the `git-rexec` script, make it executable, and copy it to a directory in your system PATH (e.g., `/usr/local/bin`):
-
-```bash
-sudo cp git-rexec /usr/local/bin/
-```
-
-### Method 2: Installation via pip
-
-Install the package directly from the Git repository using `pip`:
-
-```bash
-pip install --user git-rexec
-```
-
-## Dependencies
-
-### System Dependencies
-
-- `git`: Required for repository validation and execution.
-
-### Python Dependencies (Optional)
-
-- `colorama`: Provides color-coded terminal output.
-- `setproctitle`: Sets the process title for process monitoring tools.
-
-You can install the optional Python dependencies via pip:
-
-```bash
-pip install colorama setproctitle
-```
-
-## Usage
-
-```bash
-git-rexec [OPTIONS] [exec_cmd ...]
-```
-
-*(Assuming the `git-rexec` script is executable and in your PATH.)*
-
-### Positional Arguments
-
-- `exec_cmd`: The shell command to execute within each discovered Git repository. You can use `--` to pass options directly to the command. If omitted, the script simply prints the paths of the discovered repositories.
-
-### Options
-
-- `-C, --directory <path>`: The root directory to start searching for Git repositories. Defaults to the current working directory (`.`).
-- `--exclude-dir <path>`: Exclude a specific directory and all of its subdirectories from the search. This option can be provided multiple times.
-- `-p, --parallel`: Execute the command in parallel using threads.
-- `-i, --if-exec <command>`: Execute the main command only if this check command returns an exit code of `0`.
-- `-j, --jobs <int>`: The maximum number of concurrent workers/processors to use for parallel execution. Defaults to the number of CPU cores available.
-- `-s, --include-sub-repos`: Include sub-repositories (e.g., Git worktrees and submodules) in the search target list.
-- `-h, --help`: Show the help message and exit.
-- `-q, --quiet`: Quiet mode. Suppresses the informational tracking headers (`[EXEC]` and `[EXEC-P]`) that prefix execution output. In sequential mode, it hides the `[EXEC]` repository delimiter line entirely; in parallel mode (`-p`), it strips the yellow `[EXEC-P]` header track and removes the four-space indentation, printing only the raw, unindented stdout and stderr streams. This flag has no effect when no execution command is supplied, allowing discovered repository paths to print normally.
-
-## License
-
-This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
-
-Copyright (C) 2019-2026 [James Cherti](https://www.jamescherti.com).
-
-## Links
-
-- [git-rexec @GitHub](https://github.com/jamescherti/git-rexec)