Skip to main content

git-rexec: Find Git Repositories and Execute Commands Against Them, either Sequentially or in Parallel

Build Status License: GPL v3 PyPI Version Linux Windows macOS

The 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:

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:

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:

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):

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:

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).
  • Optional pygit2 dependency speeds up discovery across large directory trees by using libgit2 bindings instead of spawning git subprocesses.
  • Optional colorama dependency provides color coded terminal output for better visibility and easier parsing of parallel execution results.
  • Optional setproctitle dependency sets the process title to git-rexec for easier tracking in process monitoring tools.

Installation

Here is how to install git-rexec using pip:

pip install --user git-rexec

The pip command above will install the pathaction executable in the directory ~/.local/bin/.

Optional Dependencies

The git-rexec CLI offers optional dependencies that extend its functionality. These extras can be installed according to environment requirements.

Colored Terminal Output (colors): Installs colorama to provide consistent cross-platform ANSI color support. This enhances the readability of standard output and error messages.

pip install "git-rexec[colors]"

Custom Process Title (proctitle): Installs setproctitle to rename the running process from python to git-rexec. This simplifies identification in system monitoring tools such as top, htop, and ps.

pip install "git-rexec[proctitle]"

To install both extras at once, use a comma-separated list:

pip install "git-rexec[colors,proctitle]"

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.
  • pygit2: Speeds up discovery and execution time by using libgit2 bindings for Git operations instead of spawning git subprocesses.

You can install the optional Python dependencies via pip:

pip install colorama setproctitle pygit2

Usage

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)

Frequently Asked Questions

Why use git-rexec instead of find and xargs?

It is possible to use find and xargs to achieve a flexible pipeline. For example, to discover all Git repositories starting from the current directory and run git status in parallel, one could use:

find . \
    -type d \
    -exec bash -c '[[ "$(git -C "$1" rev-parse --is-inside-work-tree 2>/dev/null)" == true ]]' '' {} \; \
    -prune \
    -print0 \
| xargs -0 -P10 -I{} git -C {} status

While standard shell utilities like find and xargs are highly capable, git-rexec addresses performance limitations and edge cases in shell pipelines, reducing complex commands to a single command:

git-rexec -p -j 10 -- git status

The git-rexec command-line tool offers significant performance improvements. A traditional find -exec bash -c 'git ...' spawns separate processes for every directory visited during discovery. By avoiding this, git-rexec is faster. According to the author's benchmark, git-rexec is 4.36 times faster than the find and xargs command.

Additionally, git-rexec improves output readability. Standard xargs makes it difficult to trace output back to a specific repository when operating concurrently. The git-rexec tool automatically prefixes all output with the corresponding repository context, adding indentation and optional colors during parallel execution. It also executes non-Git commands directly within the repository root, removing the need for sh -c 'cd "$1" && ...' wrappers, and includes built-in arguments for handling sub-repositories (-s), exclusions (--exclude-dir), and conditional execution (--if-exec).

Furthermore, git-rexec handles nested repository edge cases natively. Using find with git rev-parse --is-inside-work-tree often fails within umbrella repositories containing nested clones. The shell evaluation triggers a prune at the root directory, preventing the discovery of the nested repositories. The git-rexec command parses these structures correctly by default.

For workflows requiring strict separation between discovery and execution, or to cache a static list of repositories, git-rexec provides the --print and --print0 arguments:

git-rexec --print0 | xargs -0 -P10 -I{} git -C {} fetch --verbose

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.

Metadata

Release files for git-rexec 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for git-rexec 1.1.1
File Size Uploaded Provenance Actions
git_rexec-1.1.1.tar.gz 40.0 kB Without provenance Details for git_rexec-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for git-rexec 1.1.1
File Interpreter ABI Platform Actions
git_rexec-1.1.1-py3-none-any.whl Python 3 none any Details for git_rexec-1.1.1-py3-none-any.whl

Total release size: 66.1 kB

Release files / git_rexec-1.1.1.tar.gz

Download URL git_rexec-1.1.1.tar.gz
Size 40.0 kB
Tags Source
SHA-256 checksum
How to use checksums
b8c0744bdb0b9a225ca279db3c39bb9a1f417dc4e701284e6ea704d60c2776e8
BLAKE2b-256 checksum
How to use checksums
e42c57f9b8a55c50544df04841b95ec9e446ca0a2158c3c5fd4116831afccafa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / git_rexec-1.1.1-py3-none-any.whl

Download URL git_rexec-1.1.1-py3-none-any.whl
Size 26.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
97442ba180a3af4a5f1a66b1b293902d99114d853ae46715d815032b4869af2a
BLAKE2b-256 checksum
How to use checksums
876d04edf224338db4ca494bbbe351f92130ca3ffee2f8d586d1535d6b7a04c4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for git-rexec 1.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page