diff --git a/README.md b/README.md index d49f237..124ca39 100644 --- a/README.md +++ b/README.md @@ -2,154 +2,149 @@
-**Your AI Powerhouse for Git & Project Management.** -Stop wasting time on repetitive tasks. Automate your commits, changelogs, and project essentials with a single CLI. +**AI-Powered Git & Project Workflows in One CLI** + +Stop wasting time on repetitive tasks. DevGen automates commits, changelogs, `.gitignore`, and license files using AI — from cloud providers or a local Ollama model. > PyPI didn't allow the original name, so you'll find it as **devgen-cli** on PyPI > PyPI > Python > License -> Build Status -> Pre-Commit Status +> CI +> Pre-Commit
-## Overview +## Why DevGen -DevGen is an innovative CLI tool designed to streamline your development workflow by automating repetitive tasks such as commits, changelogs, and project essentials. Leveraging state-of-the-art AI models, DevGen transforms tedious manual tasks into one-click magic, enabling you to focus on building and improving your projects. +DevGen is a CLI for the parts of development that should be invisible. It writes Conventional Commits from your diff, drafts SemVer changelogs, fetches `.gitignore` and license templates, and routes everything through whichever AI provider you prefer — including a fully local Ollama model if you don't want to send code to the cloud. ## Features -- **AI-Powered Commits**: Generate semantic, context-aware commit messages using AI models from Gemini, OpenAI, Anthropic, HuggingFace, OpenRouter, and local Ollama. -- **Battle-Tested**: Produces Conventional Commits and Semantic Versioning compliant changelogs that make sense. -- **Lightning Fast**: Utilizes smart caching and async operations for speedy performance. -- **Project Essentials**: Quickly add `.gitignore` and license files to your projects, with access to cached templates even offline. -- **Zero Friction**: Interactive setup gets you running in seconds. -- **Customizable**: Define your own commit message structure using Jinja2 templates. +- **AI-Powered Commits** — Conventional Commit messages generated from your staged diff, grouped by directory, with optional emoji prefixes. +- **Multiple Providers** — Google Gemini, OpenAI, Anthropic, OpenRouter, HuggingFace, and local Ollama, all behind one CLI. +- **Smart Caching** — `.gitignore` and license templates are cached for offline use; AI responses are de-duplicated. +- **Conventional Changelogs** — `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `ci`, `chore`, `style`, and a `BREAKING CHANGES` section. +- **Project Scaffolding** — Pull `.gitignore` from GitHub's collection and drop in SPDX license files (MIT, Apache-2.0, GPL-3.0, AGPL-3.0, BSD, MPL-2.0, …). +- **Custom Templates** — Override the commit-message prompt via a `.tpl` file in your config. +- **Interactive Setup** — `devgen setup` walks you through provider + API key + options. +- **Undo Support** — `devgen commit undo` rolls back the last AI commit while keeping changes staged. +- **Token-Limit Aware** — When a diff exceeds a model's context window, you get a single actionable error with `--max-groups` and `--max-diff-size` hints. -## Tech Stack +## Supported AI Providers -- **Python 3.10+**: The primary programming language. -- **Typer & Rich**: For building the intuitive and responsive CLI interface. -- **Questionary**: For interactive prompts and selection menus. -- **Jinja2**: For the powerful template engine. -- **AI Models**: From Google Gemini, OpenAI, Anthropic, HuggingFace, OpenRouter, and local Ollama. -- **Rich**: For text-based user interfaces. -- **Uv**: For dependency management and installation. -- **OpenAI**: For AI model integration. -- **Anthropic**: For AI model integration. -- **Ruff**: For code linting and formatting. -- **Google GenAI**: For AI model integration. +| Provider | Notes | +|---|---| +| **Google Gemini** | Default-friendly, generous free tier | +| **OpenAI** | GPT-4o, GPT-4.1, o-series | +| **Anthropic** | Claude 3.5 / 3.7 / 4 | +| **OpenRouter** | Single key, many models | +| **HuggingFace** | Inference API | +| **Ollama** | Fully local, no API key, no data leaves your machine | ## Installation -Get started with DevGen in seconds using one of the following methods: - ```bash -# Recommended: Install via pipx for an isolated environment +# Recommended: isolated environment pipx install devgen-cli -# Or use uv for blazing speed +# Or use uv for speed uv tool install devgen-cli -# Standard pip install +# Or plain pip pip install devgen-cli -# Enable Shell Completion (bash/zsh/fish) +# Shell completion (bash/zsh/fish) devgen --install-completion ``` -## Usage +Requires **Python 3.10 or newer**. -### Initialize & Configure - -Tell DevGen which AI provider to use. +## Quick Start ```bash +# 1. Configure a provider and API key devgen setup config -``` -### Stage & Commit - -Stage your files and let AI write the message. - -```bash +# 2. Stage your work as usual git add . + +# 3. Let DevGen write the commit message devgen commit run -``` -### Preview Commit Message - -Preview what DevGen will generate without committing. - -```bash +# 4. Or preview first, then commit devgen commit run --dry-run -``` - -### Commit and Push - -Commit and push in one go. - -```bash devgen commit run --push ``` -### Review and Edit +## Commands -Review and edit AI messages before committing. +| Command | Description | +|---|---| +| `devgen setup config` | Interactive provider / API key / options wizard | +| `devgen commit run` | Stage, generate message, commit (optionally `--push`, `--check`, `--dry-run`) | +| `devgen commit undo` | Undo the last AI commit, keep changes staged | +| `devgen changelog` | Generate a Conventional Commits changelog from recent history | +| `devgen release-notes` | Generate release notes for a version range | +| `devgen gitignore list` | List available GitHub `.gitignore` templates | +| `devgen gitignore add …` | Add `.gitignore` entries to the current project | +| `devgen license list` | List available SPDX licenses | +| `devgen license add ` | Add a LICENSE file to the current project | -```bash -devgen commit run --check +Run `devgen --help` for full options on any subcommand. + +## Custom Templates + +DevGen uses `.tpl` files for its commit prompt. To override the default, set `custom_template` in your config (see `devgen config info`) and point it at a `.tpl` file with `{{ diff_text }}`, `{{ context }}`, `{{ group_name }}`, and the conditional `{% if use_emoji %}` block. + +Example minimal template: + +``` +{{ diff_text }} +Summarize the change above in one Conventional Commit line. ``` -### Undo Last Commit +## Architecture -Undo the last AI commit and keep changes staged. +DevGen is built around a small set of composable components: -```bash -devgen commit undo -``` +- **`BaseProvider`** — abstract base for every AI provider; handles API-key validation, token-limit detection, and error wrapping. Adding a new provider is one subclass with a single `_generate()` method. +- **`GitOperator`** — all `subprocess` calls to `git` live here, behind a `GitError` exception. +- **`DiffBuilder` / `FileGrouper` / `ManifestInspector`** — split a staged diff into per-directory groups with compact project context, so the model sees a focused slice instead of a wall of text. +- **`Section` enum** — single source of truth for changelog ordering and emoji, shared by `ChangelogGenerator` and `ReleaseNotesGenerator`. -## API Documentation - -For more detailed API information and available commands, please refer to the [DevGen CLI Documentation](https://devgen.readthedocs.io/). - -## Contributing - -We welcome contributions! Found a bug? Want a new feature? Open an issue or submit a PR. +The CLI entry point is `devgen.cli.main:app` (Typer), exposed as the `devgen` script. ## Development -To set up the development environment, follow these steps: +```bash +git clone https://github.com/S4NKALP/DevGen.git +cd DevGen +uv sync --all-extras --dev # install runtime + dev deps +uv run pre-commit run --all-files +uv run devgen --help +``` -1. Clone the repository: `git clone https://github.com/S4NKALP/DevGen.git` -2. Install dependencies: `pip install -r requirements.txt` -3. Run tests: `pytest` +The project uses `uv` for dependency management, `ruff` for lint + format, and `pyright` for type checking. CI runs all three on Python 3.10 through 3.13 (see `.github/workflows/ci.yml`). -## Deployment +## Contributing -To deploy DevGen, follow these steps: - -1. Build the package: `python setup.py sdist` -2. Upload to PyPI: `twine upload dist/*` - -## Troubleshooting - -If you encounter any issues, please refer to our [Troubleshooting Guide](https://devgen.readthedocs.io/en/latest/troubleshooting.html). +Issues and PRs welcome. Please run `uv run pre-commit run --all-files` before opening a PR so CI stays green. ## License -Proudly open source under the [GPL-3.0-or-later](LICENSE) License. +GPL-3.0-or-later. See [LICENSE](LICENSE). ## Acknowledgments -DevGen wouldn't be possible without these amazing open-source projects and AI providers: +Built on the shoulders of: -- **Typer** & **Rich** for the CLI interface. -- **Questionary** for interactive prompts. -- **Jinja2** for the template engine. -- **Google Gemini**, **OpenAI**, **Anthropic**, **HuggingFace**, **OpenRouter**, and local **Ollama** for the AI models. +- **Typer** & **Rich** — CLI and terminal UI +- **Questionary** — interactive prompts +- **Jinja2** — template rendering under the hood +- **Google Gemini**, **OpenAI**, **Anthropic**, **OpenRouter**, **HuggingFace**, and **Ollama** — AI providers +- **Ruff** — lint and format
Made with ❤️ by Sankalp