Gradle-mirror/README.md

gradle-mirror

gradle-mirror is a production-quality Python CLI for switching Gradle repository mirrors on and off globally for Android/Gradle projects.

When enabled, it manages a safe, idempotent block inside your global Gradle init script (init.gradle.kts) and enforces mirror repositories for both project dependencies and plugin management.

Why this tool

• One command to activate mirrors globally
• One command to restore original behavior
• Backup/restore support for safe rollback
• Idempotent updates (no duplicated blocks)
• Colored console output and action logs
• Cross-platform support (Linux, macOS, Windows)

Project structure

gradle_mirror/
  __init__.py
  init.py
  cli.py
  mirror_manager.py
  gradle_locator.py
  constants.py
  utils.py
  main.py
pyproject.toml
README.md
README.fa.md

Requirements

• Python 3.10+
• pip

Installation

Install as CLI (recommended)

python -m pip install .

Then verify:

gradle-mirror --help

Run without install

python -m gradle_mirror.main --help

Usage

Activate mirrors:

gradle-mirror active

Deactivate mirrors:

gradle-mirror deactive

What active does

• Resolves Gradle home from GRADLE_USER_HOME or falls back to ~/.gradle
• Targets <gradle_home>/init.gradle.kts
• Creates backup init.gradle.kts.bak if file already exists
• Inserts/replaces content between:
  • /* gradle-mirror-start */
  • /* gradle-mirror-end */
• Enforces mirror repositories for:
  • allprojects.repositories
  • settings.pluginManagement.repositories

What deactive does

• Restores from init.gradle.kts.bak when available
• Otherwise removes managed marker block from init.gradle.kts
• Deletes init.gradle.kts if it becomes empty

Logging

• Log file: <gradle_home>/gradle-mirror.log

Example output

✅ Gradle mirror activated
📁 Updated /Users/you/.gradle/init.gradle.kts