{"id":29035363,"url":"https://github.com/andyvandaric/avcmt-py","last_synced_at":"2025-06-26T12:08:21.252Z","repository":{"id":299274327,"uuid":"1002508471","full_name":"andyvandaric/avcmt-py","owner":"andyvandaric","description":"AI-powered, fully automated Semantic Release style Git commit message generator and workflow automation CLI for Python projects.","archived":false,"fork":false,"pushed_at":"2025-06-23T12:55:20.000Z","size":295,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-23T13:49:32.330Z","etag":null,"topics":["ai","automation","cicd","cli","code-quality","commit-message-generator","devtools","git-commit","github-actions","open-source","pre-commit","python","release-management","semantic-release","workflow-automation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andyvandaric.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-15T16:13:16.000Z","updated_at":"2025-06-23T03:02:46.000Z","dependencies_parsed_at":"2025-06-15T18:30:18.693Z","dependency_job_id":"ccfd2a78-e5fc-4098-bfbb-8091467b1237","html_url":"https://github.com/andyvandaric/avcmt-py","commit_stats":null,"previous_names":["andyvandaric/avcmt-py"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/andyvandaric/avcmt-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyvandaric%2Favcmt-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyvandaric%2Favcmt-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyvandaric%2Favcmt-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyvandaric%2Favcmt-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andyvandaric","download_url":"https://codeload.github.com/andyvandaric/avcmt-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyvandaric%2Favcmt-py/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262063486,"owners_count":23252765,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","cicd","cli","code-quality","commit-message-generator","devtools","git-commit","github-actions","open-source","pre-commit","python","release-management","semantic-release","workflow-automation"],"created_at":"2025-06-26T12:08:20.384Z","updated_at":"2025-06-26T12:08:21.246Z","avatar_url":"https://github.com/andyvandaric.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AVCMT-PY - AI-Powered Semantic Release Style Git Commit Automation for Python Projects\n\n[![PyPI version](https://img.shields.io/pypi/v/avcmt-py.svg)](https://pypi.org/project/avcmt-py/) [![Downloads](https://static.pepy.tech/badge/avcmt-py)](https://pepy.tech/project/avcmt-py) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=for-the-badge)](LICENSE) [![Ruff](https://img.shields.io/badge/Ruff-%20-fastapi?style=for-the-badge\u0026labelColor=202020\u0026logo=ruff\u0026logoColor=white)](https://docs.astral.sh/ruff/) [![PyPI](https://img.shields.io/badge/pypi-v0.11.13-orange?style=for-the-badge\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/ruff/) [![CI](https://img.shields.io/badge/main-passing-brightgreen?style=for-the-badge\u0026logo=github)](https://github.com/andyvandaric/avcmt-py/actions)\n\n\nTired of manually crafting Git commit messages? Supercharge your Python development workflow with **[avcmt-py](https://github.com/andyvandaric/avcmt-py)**, the intelligent CLI tool that automates semantic, structured commit message generation using AI. Boost productivity and maintain a crystal-clear repository history effortlessly.\n\n\u003e **TL;DR:**\n\u003e AI-powered, semantic-release-style git commit automation for Python projects.\n\u003e One command, zero guesswork: meaningful, structured commits using your Pollinations AI API Token.\n\u003e Install, configure your API key, and enjoy never writing boring commit messages again!\n\n\n\n## 🚀 What is avcmt-py?\n\n**AVCMT-PY** (Automated Version Control \u0026 Management Tool for Python) is a blazing-fast, fully-automated CLI tool for generating *meaningful*, *structured* git commit messages using AI (Gemini, OpenAI, Pollinations, etc) — optimized for Python developers who want clean semantic-release workflow, better productivity, and crystal-clear repo history.\n\n- **No more generic \"fix bug\", \"update code\" commits.**\n- **Just run `avcmt` and get a ready-to-commit, semantic-release-formatted message,** automatically grouped by directory or file.\n- **Integrates with pre-commit, CI/CD, and release workflows.**\n- **Flexible AI provider: choose your favorite (support for Gemini, Pollinations, OpenAI out-of-the-box).**\n\n\n\n## ✨ Features\n\n-   **AI-Powered Commit Messages:** Generate detailed, semantic-release-style commit messages from git diff with a single command.\n\n-   **Directory Grouping:** Automatically groups and commits related changes per directory (or as a catch-all).\n\n-   **Semantic Release Ready:** Commit format fully compatible with [semantic-release](https://semantic-release.gitbook.io/) for auto versioning \u0026 changelogs.\n\n-   **Multi-Provider AI:** Easily switch between Gemini, Pollinations, OpenAI (or extend to your own LLM API).\n\n-   **Jinja2 Prompt Templates:** Fully customizable prompt rendering using Jinja2 templates for flexible commit messaging.\n\n-   **Zero Hardcoded Secrets:** API keys are loaded from `.env` or environment variables.\n\n-   **Easy to Install, Easy to Use:** Works on any Python project, no lock-in.\n\n-   **Developer Tools Included:** Scripts for linting, formatting, preflight check, and triggering semantic release.\n\n-   **Pre-commit \u0026 CI/CD Friendly:** Fully integrated with pre-commit and GitHub Actions for automated workflows.\n\n\n\n## 📦 Installation\n\n```bash\npip install avcmt-py\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/andyvandaric/avcmt-py.git\ncd avcmt-py\npip install .\n```\n\n## ⚡️ Quick Start (TL;DR)\n\n1.  **Add your API key**\n\n    -   Copy `.env.example` to `.env`\n\n    -   Edit `.env` and fill your Pollinations or OpenAI API key\n\n    ```env\n    # Example (.env)\n    OPENAI_API_KEY=your_openai_token\n    POLLINATIONS_TOKEN=your_pollinations_token\n    ```\n\n2.  (Optional) Enable pre-commit hook:\n\n    ```\n    pre-commit install\n    ```\n\n3.  **Run avcmt:**\n\n    ```bash\n    avcmt           # AI generates \u0026 applies grouped commits!\n    ```\n    -   Optionally use:\n\n        -   `--dry-run` (preview messages)\n\n        -   `--push` (auto-push after commit)\n\n        -   `--debug` (show AI prompts \u0026 raw response)\n\n4.  **Done!**\n\n    -   Check your git log for clean, structured, semantic-release-ready commit messages.\n\n\n\n## 🛠️ Usage\n\n```bash\navcmt [OPTIONS]\n```\n\n-   `--dry-run` : Preview commit messages without applying\n\n-   `--push` : Push commits to remote after done\n\n-   `--debug` : Show debug info (prompts \u0026 AI response)\n\n#### Example\n\n```bash\navcmt --dry-run\navcmt --push\n```\n\n\n\n## 🔒 Environment \u0026 Configuration\n\n-   Place `.env` in your project root (or set env vars globally)\n\n-   Supported ENV:\n\n    -   `POLLINATIONS_API_TOKEN`\n\n    -   (other providers: applied next update)\n\n\n\n## 📦 **Project Structure** (`avcmt-py/`)\n\n```bash\navcmt-py/\n├── .env.example\n├── .github/\n│   └── workflows/\n│       ├── pre-commit.yml\n│       └── release.yaml\n├── .gitignore\n├── .pre-commit-config.yaml\n├── CHANGELOG.md\n├── LICENSE\n├── README.md\n├── pyproject.toml\n├── avcmt/\n│   ├── __init__.py\n│   ├── ai.py\n│   ├── cli.py\n│   ├── commit.py\n│   ├── utils.py\n│   ├── prompt_templates/\n│   │   └── commit_message.j2\n│   └── providers/\n│       ├── __init__.py\n│       ├── openai.py\n│       └── pollinations.py\n├── scripts/\n│   ├── check.py\n│   ├── clean.py\n│   ├── format.py\n│   ├── helper.py\n│   ├── lintfix.py\n│   ├── preflight.py\n│   ├── semrel.py\n│   └── setup.py\n└── setup.cfg\n```\n\n### ✨ **File Descriptions**\n\n-   `avcmt/cli.py` --- CLI entry point, handles argument parsing and triggers auto-commit.\n\n-   `avcmt/commit.py` --- Core logic for grouping, git interaction, and structured AI commit message generation.\n\n-   `avcmt/ai.py` --- Manages prompt rendering and request to the AI provider (Jinja2-powered).\n\n-   `avcmt/utils.py` --- Helper functions for environment, logging, and file operations.\n\n-   `avcmt/__init__.py` --- Marks the core package.\n\n-   `avcmt/prompt_templates/commit_message.j2` --- Jinja2 template for AI commit prompt.\n\n-   `avcmt/providers/openai.py` --- Adapter for OpenAI API.\n\n-   `avcmt/providers/pollinations.py` --- Adapter for Pollinations API.\n\n-   `avcmt/providers/__init__.py` --- Provider interface loader.\n\n-   `scripts/check.py` --- Run validation checks on repo status.\n\n-   `scripts/clean.py` --- Optional cleanup utility.\n\n-   `scripts/format.py` --- Format code using Ruff or Black.\n\n-   `scripts/helper.py` --- Shared utilities across scripts.\n\n-   `scripts/lintfix.py` --- Lint and auto-fix with Ruff.\n\n-   `scripts/preflight.py` --- Pre-commit safety check runner.\n\n-   `scripts/semrel.py` --- Trigger python-semantic-release publish process.\n\n-   `scripts/setup.py` --- One-shot setup script for dev environment.\n\n-   `.env.example` --- Environment file template. Copy to `.env` and fill your token.\n\n-   `.pre-commit-config.yaml` --- Pre-commit hook configuration.\n\n-   `.gitignore` --- Ignore compiled files, .env, cache, etc.\n\n-   `pyproject.toml` --- Project metadata and dependency configuration.\n\n-   `setup.cfg` --- Optional setup file for tools compatibility.\n\n-   `README.md` --- Full project description and usage.\n\n-   `LICENSE` --- MIT License.\n\n-   `CHANGELOG.md` --- Auto-generated changelog via semantic release.\n\n-   `.github/workflows/release.yaml` --- CI workflow for auto versioning and publishing.\n\n-   `.github/workflows/pre-commit.yaml` --- CI pre-commit hook runner.\n\n## 🧩 Advanced\n\n-   **Custom AI Providers:**\n    See `avcmt/ai.py` to extend with your own LLM API.\n\n-   **Integration with pre-commit:**\n    Works out-of-the-box, can be called in hooks or CI.\n\n-   **Full CLI options:**\n    Run `avcmt --help` for all flags.\n\n\n\n## 📚 FAQ\n\n**Q: Will this overwrite my changes or commit everything automatically?**\nA: No, only staged files are affected. You're always in control.\n\n**Q: Can I use it for monorepos?**\nA: Yes, directory grouping is automatic, but fully configurable.\n\n**Q: What if my provider's API token is missing or invalid?**\nA: You'll see a clear error and nothing will be committed.\n\n**Q: Is it safe for public/private repos?**\nA: Yes, no token or diff is ever sent to any server except the AI you choose.\n\n\n\n## 🌟 Why avcmt-py?\n\n-   ✨ *Stop wasting time on commit messages*\n\n-   ✨ *Zero learning curve, drop-in to any Python repo*\n\n-   ✨ *Works everywhere: CLI, hook, CI/CD, local/dev/remote*\n\n-   ✨ *Your AI, your rules: bring your own API key, use any LLM*\n\n\n\n## 🔗 Links\n\n-   [GitHub](https://github.com/andyvandaric/avcmt-py)\n\n-   [PyPI](https://pypi.org/project/avcmt-py/)\n\n\n\n## 📝 License\n\n[Apache 2.0](LICENSE)  Made by [Andy Vandaric](https://github.com/andyvandaric)\n\n\n\n## 👏 Credits\n\n-   Inspired by semantic-release, and real-life productivity pain points.\n\n-   Powered by Pollinations AI.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyvandaric%2Favcmt-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandyvandaric%2Favcmt-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyvandaric%2Favcmt-py/lists"}