pushit – AI-powered Git commit message generator

pushit is a command-line tool that automatically generates meaningful, Conventional Commits‑style commit messages using AI. It integrates with Git's prepare-commit-msg hook to analyze your staged changes and produce a commit message that follows best practices.

Features

• 🤖 AI‑generated commit messages – Uses OpenAI‑compatible APIs (OpenAI, DeepSeek, Anthropic, etc.) to write commit messages based on your actual code changes.
• 🔌 Multiple provider support – Configure multiple LLM providers and switch between them easily.
• 🔧 Conventional Commits – Always follows the Conventional Commits specification (<type>: <subject>).
• ⚙️ Flexible configuration – Configure multiple AI providers with a designated default, custom base URLs, and fine‑tuned parameters (temperature, max tokens, etc.).
• 🪝 Seamless Git integration – Installs as a Git hook that runs automatically when you commit.
• 🧪 Built‑in testing – Verify your setup with pushit --test.
• 📝 Configurable behavior – Control whether to auto‑stage, require confirmation, limit diff size, and more.
• 🔍 Debug logging – Optional verbose logging to a file for troubleshooting.

Installation

1. Build from source

Clone the repository and build the binary:

git clone <repository-url>
cd pushit
go build -o pushit .

You can move the binary to a directory in your PATH for global access:

sudo mv pushit /usr/local/bin/

2. Install the Git hook

Inside any Git repository where you want to use pushit, run:

pushit --install

This creates a prepare-commit-msg hook in .git/hooks/ that will call pushit whenever you run git commit.

Configuration

pushit reads its configuration from ~/.pushitrc (JSON format). Environment variables override the file settings.

1. Create a configuration file

Create ~/.pushitrc with the following template:

{
  "default_provider": "openai",
  "providers": {
    "openai": {
      "api_key": "your-openai-api-key-here",
      "model": "gpt-3.5-turbo",
      "base_url": "https://api.openai.com/v1",
      "temperature": 0.7,
      "max_tokens": 200
    },
    "deepseek": {
      "api_key": "your-deepseek-api-key-here",
      "model": "deepseek-chat",
      "base_url": "https://api.deepseek.com/v1",
      "temperature": 0.7,
      "max_tokens": 200
    },
    "anthropic": {
      "api_key": "your-anthropic-api-key-here",
      "model": "claude-3-5-sonnet-20241022",
      "base_url": "https://api.anthropic.com/v1",
      "temperature": 0.7,
      "max_tokens": 200
    }
  },
  "git": {
    "enabled": true,
    "auto_stage": false,
    "require_confirmation": true,
    "max_diff_size": 16000,
    "exclude_patterns": "*.log,*.tmp,*.swp,node_modules/,.git/"
  },
  "debug": {
    "log_file": "~/.pushit_debug.log",
    "verbose": false
  }
}

2. Set your API keys and default provider

You can set API keys in the config file or via environment variables. Environment variables only affect the default provider.

• OpenAI: export OPENAI_API_KEY=sk-...
• DeepSeek: export DEEPSEEK_API_KEY=...
• Anthropic: export ANTHROPIC_API_KEY=...

Set default_provider to the provider you want to use (e.g., "openai", "deepseek", or "anthropic"). Only the environment variable for the default provider will be read.

For example, if default_provider is set to "anthropic", then only ANTHROPIC_API_KEY will be used from the environment, even if OPENAI_API_KEY or DEEPSEEK_API_KEY are set.

3. Adjust settings

• model: The AI model to use (e.g., gpt-3.5-turbo, deepseek-chat, gpt-4).
• base_url: The API endpoint. Change this if you use a different provider (e.g., local LLM).
• temperature: Controls randomness (0.0–1.0). Lower values produce more deterministic messages.
• max_tokens: Maximum length of the generated message.
• git.enabled: Turn the hook on/off globally.
• git.require_confirmation: If true, you’ll be prompted to review the generated message before committing.
• git.max_diff_size: Diffs larger than this (characters) will be truncated to stay within token limits.
• debug.verbose: Enable detailed logging to ~/.pushit_debug.log.

Usage

Basic workflow

1. Stage your changes:

   git add .
   

2. Commit as usual:

   git commit
   

   The hook will run, generate a commit message, and open your editor for confirmation (if configured).

3. Save and close the editor to complete the commit.

Command‑line options

# Install the Git hook in the current repository
pushit --install

# Show the current configuration (with masked API key)
pushit --config

# Test the AI integration with a sample diff
pushit --test

# Enable debug mode for the test
pushit --debug

# Run as a hook (this is called automatically by Git)
pushit <commit_msg_file> [<commit_source>]

Examples

Generated commit messages look like:

feat: add user authentication middleware
fix: resolve null pointer exception in data parser
docs: update API usage examples
chore: update dependencies to latest versions
refactor: simplify error‑handling logic

How it works

1. When you run git commit, Git executes the prepare-commit-msg hook.
2. pushit captures the staged diff (git diff --cached).
3. The diff is sent to the configured AI API with a system prompt that enforces Conventional Commits.
4. The AI returns a commit message, which is cleaned and formatted.
5. The message is written to the commit message file, and your editor opens (if confirmation is required).
6. You can edit the message or simply save to proceed with the commit.

Troubleshooting

Hook doesn’t run

• Ensure the hook is executable: chmod +x .git/hooks/prepare-commit-msg
• Check that git config core.hooksPath isn’t overriding the local hooks directory.
• Verify the hook is installed in the correct repository.

AI generation fails

• Run pushit --test to see detailed error messages.
• Check your API key and network connectivity.
• Look at the debug log: tail -f ~/.pushit_debug.log (if debug.verbose is true).
• Ensure the base URL matches your provider (e.g., DeepSeek uses https://api.deepseek.com/v1).

Message quality issues

• Adjust the temperature setting (lower for more consistent results).
• Increase max_tokens if messages are being cut off.
• The system prompt is designed to follow Conventional Commits; you can modify it in aigenerator.go if needed.

Development

Project structure

• pushit.go – Main entry point, CLI flag parsing.
• config.go – Configuration loading and management.
• aigenerator.go – AI client and message generation logic.
• gitdiff.go – Git diff retrieval and filtering.
• hook.go – Git hook implementation and installation.
• debug.go – Debug logging utilities.

Dependencies

• openai-go/v3 – OpenAI‑compatible API client.
• Standard Go libraries.

Building and testing

# Build
go build -o pushit .

# Run tests (requires valid API key)
pushit --test

# Install locally
go install

Code Quality and Pre-commit

The project uses pre-commit hooks to enforce code quality standards. To set up:

1. Install pre-commit:

   pip install pre-commit
   

2. Install the hooks:

   make pre-commit-install
   # or manually:
   # pre-commit install
   # pre-commit install --hook-type commit-msg
   

3. Run hooks on all files:

   make pre-commit
   # or
   # pre-commit run --all-files
   

Hooks include:

• Go formatting (gofmt, goimports)
• Go linting (golangci-lint, staticcheck, vet)
• Conventional Commits validation for commit messages
• Markdown linting
• YAML/JSON validation
• Trailing whitespace and end-of-file fixes

See .pre-commit-config.yaml for full configuration.

Use make for common development tasks:

make fmt        # Format code
make lint       # Run linters
make test       # Run tests
make all        # Format, lint, test, and build
make help       # Show all targets

Continuous Integration

The project includes a GitHub Actions workflow (.github/workflows/ci.yml) that runs on every push and pull request. It performs:

• Pre-commit hooks (formatting, linting, validation)
• Go build (ensures code compiles)
• Go test (runs unit tests)
• Go lint (runs golangci-lint)

To enable CI on your own repository, ensure the workflow file is present and adjust the on section as needed.

License

MIT – feel free to use, modify, and distribute.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

---

Enjoy more descriptive commit messages with zero effort!