mxrepo 1.0.0

Helper script for working with multiple git repositories.

mxrepo

Helper script for working on multiple git repositories in a specific directory.

This script is useful if you work with mxdev sources for project development or if you want to perform backups of a GitHub account.

The tool operates on all git repositories found in the current directory (those containing a .git folder) and executes git commands across them in batch.

Features

• Batch Operations: Execute git commands across multiple repositories at once
• GitHub Integration: Clone or backup all repositories from a GitHub organization or user
• Zero Dependencies: Uses only Python standard library (no external packages required)
• Smart API Access: Automatically tries organization endpoint first, then falls back to user endpoint
• Selective Operations: Target specific repositories or operate on all found repos
• Works with mxdev: Designed for managing mxdev source checkouts during development

Prerequisites

• Python 3.9 or higher
• Git must be installed and available in PATH
• GitHub Access: For clone and backup commands, repositories must be accessible via GitHub's public API (no authentication is performed)

Installation

From PyPI

pip install mxrepo

For Development

git clone https://github.com/mxstack/mxrepo
cd mxrepo
make install  # Sets up virtual environment and installs dependencies

Usage

Parameters

• <CONTEXT>: GitHub organization or user name (e.g., mxstack, octocat)
• [<PACKAGE>]: Optional repository name(s) to filter operations. When omitted, operates on all repositories found in the current directory

Commands

Command	Description	Usage	Example
clone	Clone repositories from GitHub org/user	mxrepo clone <CONTEXT> [<PACKAGE>...]	mxrepo clone mxstack mxdev
backup	Backup all repos from org/user (bare mirrors)	mxrepo backup <CONTEXT>	mxrepo backup myorganization
pull	Pull latest changes from origin	mxrepo pull [<PACKAGE>...]	mxrepo pull
status	Show git status for repositories	mxrepo status [<PACKAGE>...]	mxrepo status myproject
branch	List branches in repositories	mxrepo branch [<PACKAGE>...]	mxrepo branch
diff	Show git diff for repositories	mxrepo diff [<PACKAGE>...]	mxrepo diff
commit	Commit all changes with message	mxrepo commit "<MESSAGE>" [<PACKAGE>...]	mxrepo commit "Fix: update deps"
push	Push committed changes to origin	mxrepo push [<PACKAGE>...]	mxrepo push
checkout	⚠️ Discard all uncommitted changes	mxrepo checkout [<PACKAGE>...]	mxrepo checkout

⚠️ Warning: The checkout, commit, and push commands are destructive operations. Use with caution.

Examples

Clone all repositories from an organization

mxrepo clone mxstack

This fetches all repositories from the GitHub organization mxstack and clones them into the current directory.

Clone specific repositories only

mxrepo clone mxstack mxdev mxmake

Clones only mxdev and mxmake from the mxstack organization.

Backup all repositories from a user account

mkdir backups
cd backups
mxrepo backup octocat

Creates bare mirror clones of all repositories belonging to the GitHub user octocat. The backup command creates a subfolder named after the context.

Update all local repositories

mxrepo pull

Executes git pull origin <current-branch> in all git repositories found in the current directory.

Check status across all projects

mxrepo status

Shows git status for each repository, useful for seeing which projects have uncommitted changes.

Commit changes across multiple repositories

mxrepo commit "Update dependencies to latest versions"

Commits all changes in each repository with the same commit message. Equivalent to git commit -am "message" in each repo.

Update only specific repositories

mxrepo pull project1 project2

Pulls changes only for project1 and project2 repositories.

How It Works

1. Repository Discovery: Scans the current directory for subdirectories containing a .git folder
2. Batch Execution: Changes into each repository directory and executes the git command
3. GitHub API: For clone and backup commands, queries GitHub's REST API to fetch repository lists:
   • Tries organization endpoint: https://api.github.com/orgs/{context}/repos
   • Falls back to user endpoint: https://api.github.com/users/{context}/repos
   • Handles pagination (50 repos per page)
4. Branch Detection: Automatically detects the current branch for pull and push operations

Development

This project uses the MXStack tooling (mxdev and mxmake) for development.

Setup

make install      # Set up virtual environment and install dependencies

Code Quality

make check        # Run all checks (ruff + isort)
make format       # Auto-format code (ruff + isort)

Cleanup

make clean        # Remove virtual environment and generated files
make runtime-clean # Remove Python cache files (__pycache__, *.pyc)

Tools Used

• ruff: Linting and formatting
• isort: Import sorting (black profile, single-line imports)
• uv: Fast Python package installer

Project Structure

• src/mxrepo/main.py: Single-module implementation with all functionality
• No external dependencies (uses only Python stdlib)
• Simple argparse-based CLI with subcommands

Related Projects

• mxdev: Tools for managing multiple Python packages in development
• githelper: Original project that mxrepo was based on

Copyright

• Copyright (c) 2025 mxstack Contributors
• BSD 2-clause license (see LICENSE.md)

Contributors

• Robert Niederreiter
• Johannes Raggam

Changelog

1.0.0

• Added tests, CI workflows and hatchling/ trusted publishing and --version option [@jensens, 2025-11-03]
• Initial porting from https://github.com/rnixx/githelper [@rnix, 2025-03-03]

License

Copyright (c) 2025, mxstack Contributors

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.