{"id":15566848,"url":"https://github.com/lguibr/commitai","last_synced_at":"2026-03-08T11:31:20.634Z","repository":{"id":184505231,"uuid":"621552549","full_name":"lguibr/commitai","owner":"lguibr","description":"CommitAI is a command-line tool that helps you generate informative and relevant commit messages for your Git repositories using GPT-4 by OpenAI. It analyzes your staged changes, combines it with a high-level explanation provided by you, and creates a commit message based on this information","archived":false,"fork":false,"pushed_at":"2024-04-25T17:03:23.000Z","size":2803,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T23:47:57.772Z","etag":null,"topics":["commit","git","gpt","gpt-4"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lguibr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-03-30T22:36:34.000Z","updated_at":"2024-05-21T00:14:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"2e0c9c07-2279-45fd-9710-63b7edbe74bc","html_url":"https://github.com/lguibr/commitai","commit_stats":null,"previous_names":["lguibr/comai","lguibr/commitai"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lguibr%2Fcommitai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lguibr%2Fcommitai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lguibr%2Fcommitai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lguibr%2Fcommitai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lguibr","download_url":"https://codeload.github.com/lguibr/commitai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250535098,"owners_count":21446505,"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":["commit","git","gpt","gpt-4"],"created_at":"2024-10-02T17:07:30.389Z","updated_at":"2026-03-08T11:31:20.624Z","avatar_url":"https://github.com/lguibr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CommitAi - Your AI-Powered Commit Assistant\n\n[![CI and Publish](https://github.com/lguibr/commitai/actions/workflows/main.yml/badge.svg)](https://github.com/lguibr/commitai/actions/workflows/main.yml)\n[![codecov](https://codecov.io/gh/lguibr/commitai/graph/badge.svg?token=MXZKCXO6LA)](https://codecov.io/gh/lguibr/commitai) \u003c!-- Added Codecov Badge --\u003e\n[![PyPI](https://img.shields.io/pypi/v/CommitAi.svg)](https://pypi.org/project/CommitAi/)\n[![Python Version](https://img.shields.io/pypi/pyversions/CommitAi.svg)](https://pypi.org/project/CommitAi/)\n[![License](https://img.shields.io/pypi/l/CommitAi.svg)](https://github.com/lguibr/CommitAi/blob/main/LICENSE)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n\n\u003cimg\n  src=\"https://raw.githubusercontent.com/lguibr/commitai/main/bitmap.png\"\n  alt=\"logo\"\n  width=\"400\"\n/\u003e\n\n\u003cimg\n  src=\"https://raw.githubusercontent.com/lguibr/commitai/main/showcase.png\"\n  alt=\"screenshot\"\n  width=\"400\"\n/\u003e\n\n\n**Tired of writing Git commit messages? Let AI do the heavy lifting!**\n\n**CommitAi** streamlines your Git workflow by leveraging powerful AI models (OpenAI's GPT, Anthropic's Claude, Google's Gemini) to automatically generate clear, concise, and conventional commit messages based on your staged changes.\n\nSimply stage your files and run `commitai`. It analyzes the diff, optionally takes your high-level explanation, and crafts a commit message adhering to the [Conventional Commits](https://www.conventionalcommits.org/) standard. Review the message in your default Git editor, make any tweaks, save, and you're done!\n\n## Table of Contents\n\n- [CommitAi - Your AI-Powered Commit Assistant](#commitai---your-ai-powered-commit-assistant)\n  - [Table of Contents](#table-of-contents)\n  - [Features](#features)\n  - [Demo](#demo)\n  - [Installation](#installation)\n  - [Configuration](#configuration)\n    - [API Keys](#api-keys)\n    - [Commit Templates (Optional)](#commit-templates-optional)\n  - [Usage](#usage)\n    - [Basic Workflow](#basic-workflow)\n    - [Command-Line Options](#command-line-options)\n    - [Creating Repository Templates](#creating-repository-templates)\n  - [Examples](#examples)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n## Features\n\n*   🧠 **Intelligent Commit Generation**: Analyzes staged code differences (`git diff --staged`) using state-of-the-art AI models (Gemini, GPT, Claude) to create meaningful commit messages.\n*   📄 **Conventional Commits**: Automatically formats messages according to the Conventional Commits specification (e.g., `feat(auth): add JWT authentication`). This improves readability and enables automated changelog generation.\n*   📝 **Optional Explanations**: Provide a high-level description of your changes as input to guide the AI, or let it infer the context solely from the code diff.\n*   ✅ **Pre-commit Hook Integration**: Automatically runs your existing native Git pre-commit hook (`.git/hooks/pre-commit`) before generating the message, ensuring code quality and style checks pass.\n*   🔧 **Customizable Prompts via Templates**: Add custom instructions or context to the AI prompt using global environment variables or repository-specific template files.\n*   🤖 **Multiple AI Provider Support**: Choose your preferred AI model from OpenAI, Anthropic, Google or local AI models with Ollama.\n*   ⚙️ **Flexible Workflow**:\n    *   Stages all changes automatically (`-a` flag).\n    *   Reviews message in your default Git editor (default behavior).\n    *   Commits directly without editor review (`-c` flag).\n*   ✨ **Modern Tooling**: Built with `pyproject.toml` and formatted/linted with `ruff`.\n\n## Demo\n\n![CommitAi Demo](./assets/commitaai.gif)\n\n*(Demo shows generating a commit message using Claude 3 Opus without providing an explicit explanation)*\n\n## Installation\n\n**Requirement:** Python 3.10+ (macOS/Linux).\n\n### 📦 Production Install (PyPI)\n\nInstall globally or in your virtual environment:\n\n```bash\npip install commitai\n```\n\nEnsure the binary is in your PATH. Verify with:\n\n```bash\ncommitai --version\n# Should output: 3.1.0\n```\n\n### 🛠️ Development / Local Install\n\nIf you are developing or testing local changes (macOS/Linux only):\n\n```bash\n# Clone the repository\ngit clone https://github.com/lguibr/commitai.git\ncd commitai\n\n# Install in editable mode\npip install -e .\n```\n\n\u003e [!IMPORTANT]\n\u003e Ensure you run `commitai` from the ACTIVE Python environment where it was installed.\n\u003e System-level `pip` binaries might conflict. Use `which commitai` to verify you are using the correct shim/binary.\n\n## Configuration\n\n### API Keys\n\nCommitAi requires API keys for the AI provider you intend to use. Set these as environment variables:\n\n*   **OpenAI (GPT models):**\n    ```bash\n    export OPENAI_API_KEY=\"your_openai_api_key_here\"\n    ```\n\n*   **Anthropic (Claude models):**\n    ```bash\n    export ANTHROPIC_API_KEY=\"your_anthropic_api_key_here\"\n    ```\n\n*   **Google (Gemini models):**\n    Set **one** of the following (CommitAi checks in this priority order):\n    1.  `GOOGLE_API_KEY` (Recommended)\n    2.  `GEMINI_API_KEY`\n    3.  `GOOGLE_GENERATIVE_AI_API_KEY`\n\n    Example:\n    ```bash\n    export GOOGLE_API_KEY=\"your_google_api_key_here\"\n    ```\n\nYou only need to set the key for the provider corresponding to the model you select (or the default, Gemini 3 Flash with Google).\n\n### Ollama\n\nCommitAi can also work with Ollama models:\n```bash\nexport OLLAMA_HOST=\"your_ollama_base_url\"\n```\n\n\n### Commit Templates (Optional)\n\nYou can add custom instructions to the default system prompt used by the AI. This is useful for enforcing project-specific guidelines (e.g., mentioning ticket numbers).\n\n*   **Global Template:** Set an environment variable. This applies to all repositories unless overridden locally.\n    ```bash\n    # Example: Always ask the AI to reference a JIRA ticket format\n    export TEMPLATE_COMMIT=\"Ensure the commit footer includes a JIRA reference like 'Refs: PROJECT-123'.\"\n    ```\n\n*   **Repository-Specific Template:** Use the `commitai-create-template` command within your repository. This creates a `.git/commit_template.txt` file and overrides the global `TEMPLATE_COMMIT` variable for this repo only.\n    ```bash\n    # Example: Instruct the AI to focus on UI changes for this specific repo\n    commitai-create-template \"Focus the commit message body on user-facing UI changes.\"\n    ```\n\n**Note:** These templates *add* to the default system prompt, which already instructs the AI to follow Conventional Commits format. You are providing supplementary instructions.\n\n## Usage\n\n### Basic Workflow\n\n1.  **Make your code changes.**\n2.  **Stage the changes** you want to include in the commit:\n    ```bash\n    git add \u003cfile1\u003e \u003cfile2\u003e ...\n    # or stage all changes in tracked files\n    git add .\n    # or stage all changes including untracked files\n    git add --all\n    ```\n3.  **Run `commitai`:**\n    ```bash\n    # Option 1: Let CommitAi infer the message from the diff\n    commitai\n\n    # Option 2: Provide a high-level explanation to guide the AI\n    commitai \"Refactor user authentication to use JWT tokens\"\n    ```\n4.  **Review \u0026 Edit:** CommitAi runs pre-commit hooks, generates the message, and opens it in your default Git editor (e.g., Vim, Nano, VS Code). Review the message, make any necessary edits.\n5.  **Save \u0026 Close:** Save the file and close the editor. CommitAi will then create the commit with the final message. If you close without saving or clear the message, the commit will be aborted.\n\n### Command-Line Options\n\nThe `commitai` command (which is an alias for `commitai generate`) accepts the following options:\n\n*   `-a`, `--add`:\n    *   Automatically stages *all* unstaged changes (`git add --all`) before generating the commit message.\n    *   Useful for quickly committing everything in the working directory.\n    *   Example: `commitai -a \"Implement user profile page\"`\n\n*   `-c`, `--commit`:\n    *   Skips opening the Git editor for review. The generated message is used to create the commit directly.\n    *   **Use with caution!** Reviewing AI-generated messages is recommended.\n    *   Example: `commitai -c \"Fix typo in documentation\"` (for minor changes)\n    *   Can be combined with `-a`: `commitai -a -c \"Quick fix and commit all\"`\n\n*   `--review` / `--no-review`:\n    *   Toggle a preliminary AI review of the staged diff before generating the commit message. Default is `--review` (enabled).\n    *   When enabled, CommitAi prints a brief review and asks if you want to proceed.\n    *   Example: `commitai --no-review` to skip the review step.\n\n*   `-m \u003cmodel_name\u003e`, `--model \u003cmodel_name\u003e`:\n    *   Specifies which AI model to use.\n    *   Specifies which AI model to use.\n    *   Defaults to `gemini-3-flash-preview`.\n    *   Ensure the corresponding API key environment variable is set.\n    *   Examples:\n        *   `commitai -m gemini-3-pro-preview \"Use Google's Gemini 3 Pro\"`\n        *   `commitai -m gpt-4 \"Use OpenAI's GPT-4\"`\n        *   `commitai -m claude-3-opus \"Use Anthropic's Claude 3 Opus\"`\n\n### Creating Repository Templates\n\nThe `commitai-create-template` command sets a repository-specific template instruction.\n\n```bash\ncommitai-create-template \"Add a 'Co-authored-by:' line if applicable.\"\n```\n\nThis creates/overwrites the `.git/commit_template.txt` file in the current repository.\n\n## Examples\n\n**1. Simple commit, inferred message:**\n\n```bash\n# Stage changes\ngit add src/utils.py tests/test_utils.py\n\n# Run commitai - AI infers message from diff\ncommitai\n```\n*(Editor opens with a message like `feat(utils): add helper function for data validation`)*\n\n**2. Commit with explanation:**\n\n```bash\n# Stage changes\ngit add src/auth.py\n\n# Run commitai with explanation\ncommitai \"Implement password reset functionality using email tokens\"\n```\n*(Editor opens with a message like `feat(auth): implement password reset via email token`)*\n\n**3. Stage all and commit directly (no editor):**\n\n```bash\n# Stage all changes and commit immediately using GPT-4\ncommitai -a -c -m gpt-4 \"Minor refactoring and cleanup\"\n```\n*(Commit is created directly)*\n\n**4. Using a Template:**\n\n*   First, set a template:\n    ```bash\n    commitai-create-template \"Mention the related issue number from GitHub, e.g., Fixes #123.\"\n    ```\n*   Then, run commitai:\n    ```bash\n    git add src/parser.py\n    commitai \"Fix bug in CSV parsing logic\"\n    ```\n*(Editor opens with a message potentially like `fix(parser): correct handling of quoted commas\\n\\nFixes #123`)*\n\n## Contributing\n\nContributions are highly welcome! Please follow these steps:\n\n1.  Fork the repository on GitHub.\n2.  Clone your fork locally: `git clone \u003cyour-fork-url\u003e`\n3.  Navigate to the project directory: `cd commitai`\n4.  Create a virtual environment: `python -m venv .venv \u0026\u0026 source .venv/bin/activate` (or `.\\.venv\\Scripts\\activate` on Windows)\n5.  Install dependencies, including development tools: `pip install -e \".[test]\"`\n6.  **(Optional but Recommended)** Set up pre-commit hooks: `pre-commit install`\n7.  Create a new branch for your feature or bug fix: `git checkout -b my-feature-branch`\n8.  Make your changes.\n9.  Run checks locally before committing:\n    *   Format code: `ruff format .`\n    *   Lint code: `ruff check .`\n    *   Run type checks: `mypy commitai tests`\n    *   Run tests: `pytest`\n10. Commit your changes (you can use `commitai`!).\n11. Push your branch to your fork: `git push origin my-feature-branch`\n12. Open a pull request on the main `lguibr/commitai` repository.\n\nThe CI pipeline will automatically run all checks on your pull request.\n\n## License\n\n**CommitAi** is open-source software licensed under the MIT License. See the [LICENSE](https://github.com/lguibr/CommitAi/blob/main/LICENSE) file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flguibr%2Fcommitai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flguibr%2Fcommitai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flguibr%2Fcommitai/lists"}