qgis-manage 0.6.0

A modern CLI for managing QGIS plugin development, deployment, and packaging.

QGIS Plugin Manager

A professional CLI for managing QGIS plugin development, deployment, and packaging. Modernized for Python 3.10+ and uv.

[!IMPORTANT] This is a CLI tool, not a QGIS plugin

This project is a command-line tool for managing QGIS plugin development. It should be installed as a Python package using uv or pip, not as a plugin in QGIS.

• ✅ Use it to develop and deploy QGIS plugins
• ❌ Do NOT install it as a plugin in QGIS

🚀 Features

• Dynamic Deployment: Automatically detects your QGIS profile directory (Linux, Windows, macOS).
• Smart Discovery: Reads metadata.txt to identify your plugin and automatically selects source files.
• Safety First: Automatically creates timestamped backups of your plugin folder before every deployment.
• Qt & Documentation Integration: Compiles .qrc resources, .ts translations, and Sphinx documentation automatically.
• Clean Workflow: Removes __pycache__ and artifacts recursively.
• Interactive Mode: Option for step-by-step confirmation of critical steps.
• Customizable Hooks: Support for shell commands before and after deployment.
• Persistent Config: Global and project-level settings management.

📦 Installation

Install system-wide as a tool using uv:

uv tool install git+https://github.com/geociencio/qgis-plugin-manager.git

Or add it to your project's development dependencies:

uv add --group dev qgis-plugin-manager @ git+https://github.com/geociencio/qgis-plugin-manager.git

🛠️ Usage

From your plugin project root:

# Initialize a new plugin project scaffolding
qgis-manage init "My Plugin" --author "Juan" --email "[e-mail]" --template processing

# Install external dependencies to local libs/ folder
qgis-manage install-deps

# Deploy to QGIS profile (with automatic backup and compilation)
qgis-manage deploy

# Deploy to a specific profile
qgis-manage deploy --profile production

# Deploy with interactive step-by-step confirmation
qgis-manage deploy --interactive

# Create distributable ZIP package (automatically installs dependencies)
qgis-manage package

# Create package without dev files
qgis-manage package --output ./releases

# Run QGIS Plugin Analyzer on the project
qgis-manage analyze

# Validate metadata.txt compliance
qgis-manage validate --strict

# Compile all resources, translations, and documentation
qgis-manage compile

# Compile only documentation
qgis-manage compile --type docs

# Clean Python artifacts and build files
qgis-manage clean

⚙️ Configuration

Robust Exclusions (.qgisignore)

You can control which files are excluded from deployment and packaging by creating a .qgisignore file in your project root. It supports gitignore-style patterns:

# Exclude CSV data files
data/*.csv

# Exclude specific folders
temp/
tests/data/

# Recursive match (anywhere in the project)
debug.log

Dependency Management

Define your plugin's external Python dependencies in pyproject.toml:

[tool.qgis-manager]
dependencies = [
    "requests",
    "six",
    "pandas"
]

Running qgis-manage install-deps will install these into a local libs/ folder. Remember to add this folder to sys.path in your plugin's __init__.py.

📖 Documentation

• CHANGELOG.md: History of changes and releases.
• RULES.md: Coding standards and project rules.

📄 License

GPL-2.0-or-later