smart-git-ai 0.1.6

AI-powered git commit message generator and git utility toolkit

smartgit

AI-powered git commit message generator and intelligent git utility toolkit

Package: smart-git-ai | Command: smartgit

Never write commit messages manually again. Let Claude AI understand your changes and generate meaningful, conventional commit messages.

Features • Installation • Quick Start • Documentation • Contributing

---

Table of Contents

• Why smartgit?
• Features
• Installation
• Quick Start
• Usage
  • Generate Commit Messages
  • Git Hooks Integration
  • Git Utilities
  • Configuration
• Configuration Files
• Commit Message Format
• Examples
• Requirements
• Development
• Documentation
• Contributing
• License

---

Why smartgit?

Writing good commit messages is hard and time-consuming. smartgit solves this by:

• Understanding your code changes using Claude AI to analyze diffs
• Following best practices automatically with Conventional Commits format
• Saving time by generating messages in seconds
• Maintaining consistency across your entire team
• Providing helpful utilities to manage your git workflow

---

Features

🤖 AI-Powered Commit Messages

• Intelligent Analysis: Claude AI reads your staged changes and understands context
• Conventional Commits: Automatically formatted with proper type, scope, and description
• Multiple Providers: Support for Anthropic Claude and OpenAI models
• Customizable: Add context, configure styles, and adjust behavior

🔗 Seamless Git Integration

• Git Hooks: Install prepare-commit-msg hook for automatic message generation
• Native Workflow: Works with standard git commit commands
• Editor Support: Opens your default git editor for review and editing
• Safe and Reversible: Easy to install/uninstall hooks with backups

🛠️ Powerful Git Utilities

When you need more than commits, smartgit provides helpful utilities:

Utility	Description
undo	Safely undo last commit (keep or discard changes)
cleanup	Remove local branches that have been merged
stale	Find branches not updated in N days
large-files	Locate files above size threshold
suggest-gitignore	Auto-suggest .gitignore entries for untracked files
force-push-safe	Force push with lease to prevent overwriting
fixup	Create fixup commits for autosquashing
worktree	Manage git worktrees for parallel development

---

Installation

From PyPI (Recommended)

pip install smart-git-ai

From Source

git clone https://github.com/SifatIbna/smart-git-ai.git
cd smart-git-ai
pip install -e .

Verify Installation

smartgit --version

---

Quick Start

1️⃣ Set up your API key

Get your API key from Anthropic Console:

Option 1: Export environment variable (recommended)

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export ANTHROPIC_API_KEY="your_api_key_here"

Option 2: Use .smartgit.yml config file

# Create config file in your project
echo "api_key: your_api_key_here" > .smartgit.yml

Option 3: Use .env with SMARTGIT_API_KEY

# Works for both Anthropic and OpenAI
echo "SMARTGIT_API_KEY=your_api_key_here" > .env

2️⃣ Generate your first AI commit

# Stage your changes
git add .

# Generate and commit with AI
smartgit generate

# Or preview without committing
smartgit generate --dry-run

3️⃣ Install git hooks (optional but recommended)

# Install prepare-commit-msg hook
smartgit install

# Now regular git commit will use AI automatically
git commit

That's it! 🎉 You're now using AI-powered commit messages.

---

Usage

Generate Commit Messages

# Generate AI commit message for staged changes
smartgit generate

# Add context to help the AI understand your changes
smartgit generate --context "Refactored authentication to use JWT"

# Preview without committing
smartgit generate --dry-run

# Skip editor confirmation and commit immediately
smartgit generate --no-edit

Git Hooks Integration

# Install hooks
smartgit install

# Install with force (overwrite existing hooks)
smartgit install --force

# Check installation status
smartgit status

# Uninstall hooks
smartgit uninstall

# Uninstall and restore previous backup
smartgit uninstall --restore

Git Utilities

# Undo last commit (keep changes staged)
smartgit utils undo

# Undo last commit and discard changes
smartgit utils undo --hard

# Clean up merged branches
smartgit utils cleanup

# Find stale branches (not updated in 30 days)
smartgit utils stale
smartgit utils stale --days 60

# Find large files (>10MB)
smartgit utils large-files
smartgit utils large-files --size 5.0

# Suggest .gitignore entries for untracked files
smartgit utils suggest-gitignore

# Safe force push (force-with-lease)
smartgit utils force-push-safe

# Create fixup commit
smartgit utils fixup <commit-hash>

# Get help for any utility
smartgit utils --help

Configuration

# View current configuration
smartgit config show

# Set configuration values
smartgit config set provider anthropic
smartgit config set model claude-3-5-sonnet-20241022
smartgit config set commit_style conventional

# Set global configuration (applies to all repos)
smartgit config set provider anthropic --global

# Reset configuration to defaults
smartgit config reset

---

Configuration Files

smartgit supports hierarchical configuration (in order of priority):

1. Repository Config (highest priority): .smartgit.yml in your repo root
2. User Config: ~/.config/smartgit/config.yml
3. Environment Variables: Shell exports or .env file

Example Configuration

Create a .smartgit.yml file in your repository:

# AI Provider Configuration
provider: anthropic  # or openai
api_key: your_api_key_here  # optional, can use env var instead
model: claude-3-5-sonnet-20241022

# Commit Message Settings
commit_style: conventional  # or simple
max_subject_length: 72
context_lines: 3

# Behavior Settings
auto_add: false
hook_enabled: true
max_diff_size: 10000

Environment Variables

Recommended: Provider-specific API keys (export only)

# For Anthropic (default provider)
export ANTHROPIC_API_KEY=your_anthropic_api_key

# For OpenAI (if using OpenAI provider)
export OPENAI_API_KEY=your_openai_key
export SMARTGIT_PROVIDER=openai

Alternative: Generic SMARTGIT_ variables (works in .env files)*

# In .env file or export
SMARTGIT_API_KEY=your_api_key_here
SMARTGIT_PROVIDER=anthropic  # or openai
SMARTGIT_MODEL=claude-3-5-sonnet-20241022
SMARTGIT_COMMIT_STYLE=conventional

Note: Provider-specific keys (ANTHROPIC_API_KEY, OPENAI_API_KEY) work best when exported as environment variables. Use SMARTGIT_API_KEY if you prefer .env files.

---

Commit Message Format

smartgit generates commit messages following the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Commit Types

Type	Description	Example
feat	New feature	feat(auth): add JWT authentication
fix	Bug fix	fix(api): handle null response from endpoint
docs	Documentation changes	docs(readme): add installation instructions
style	Code style changes	style(components): format with prettier
refactor	Code refactoring	refactor(db): optimize query performance
perf	Performance improvements	perf(api): cache frequent database queries
test	Adding or updating tests	test(auth): add unit tests for login flow
build	Build system changes	build(deps): upgrade to webpack 5
ci	CI configuration changes	ci(github): add automated release workflow
chore	Maintenance tasks	chore(deps): update dependencies

---

Examples

Example 1: Feature Addition

$ git add src/auth.py
$ smartgit generate

✨ Analyzing staged changes...

Generated Commit Message:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ feat(auth): add JWT token authentication         ┃
┃                                                   ┃
┃ Implement JWT-based authentication system with   ┃
┃ token generation and validation.                  ┃
┃                                                   ┃
┃ - Add token generation utility                   ┃
┃ - Add token validation middleware                ┃
┃ - Add refresh token support                      ┃
┃ - Configure token expiration settings            ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Create commit with this message? (y/n): y
✓ Commit created successfully!

Example 2: Using Utilities

$ smartgit utils stale --days 30

🔍 Finding stale branches...

Branches not updated in 30 days:
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Branch                ┃ Last Updated  ┃ Days Ago  ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ feature/old-api       │ 2024-11-15    │ 45        │
│ bugfix/temp-fix       │ 2024-11-20    │ 40        │
│ experiment/new-design │ 2024-10-10    │ 80        │
└───────────────────────┴───────────────┴───────────┘

💡 Tip: Use 'git branch -D <branch>' to delete local branches

Example 3: Status Check

$ smartgit status

📊 Git AI Status Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Repository: smartgit
Branch: main
Status: Clean ✓

Git Hooks:
  ✓ prepare-commit-msg installed
  Location: .git/hooks/prepare-commit-msg

AI Configuration:
  Provider: anthropic
  Model: claude-3-5-sonnet-20241022
  Commit Style: conventional

API Key: ✓ Found

---

Requirements

• Python: 3.8 or higher
• Git: 2.0 or higher
• API Key: Anthropic API key (or OpenAI if using that provider)

---

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/SifatIbna/smart-git-ai.git
cd smart-git-ai

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=smartgit --cov-report=html --cov-report=term-missing

# Run specific test file
pytest tests/unit/test_repository.py

Code Quality

# Format code
python -m ruff format src tests

# Lint code
python -m ruff check src tests

# Type check
python -m mypy src

# Run all checks (what CI runs)
python -m ruff check --fix src tests && \
python -m ruff format src tests && \
python -m mypy src && \
pytest --cov=smartgit

Pre-commit Hooks

# Install pre-commit hooks
pre-commit install

# Run manually
pre-commit run --all-files

---

Documentation

• QUICKSTART.md - Detailed getting started guide
• CONTRIBUTING.md - Contribution guidelines
• RELEASING.md - Release process

---

Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (pytest && ruff check .)
5. Commit your changes (use smartgit generate 😉)
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Please read CONTRIBUTING.md for detailed guidelines.

Development Philosophy

• Quality over Speed: We prioritize well-tested, maintainable code
• User First: Features should solve real problems for real developers
• Keep It Simple: Prefer simple solutions over complex abstractions
• Document Everything: Code should be self-documenting, but docs help

---

Troubleshooting

"Not a git repository" error

Make sure you're inside a git repository:

git init  # Initialize a new repository if needed

"API key not found" error

Ensure your API key is properly set:

# Check if it's set
echo $ANTHROPIC_API_KEY

# Option 1: Export as environment variable (recommended)
export ANTHROPIC_API_KEY="your_key_here"

# Option 2: Add to .smartgit.yml
echo "api_key: your_key_here" > .smartgit.yml

# Option 3: Use SMARTGIT_API_KEY in .env
echo "SMARTGIT_API_KEY=your_key_here" > .env

Hook not working

Reinstall hooks with force flag:

smartgit uninstall
smartgit install --force

"Large diff" warning

If your changes are too large:

# Commit in smaller chunks
git add specific-file.py
smartgit generate

# Or increase the limit
smartgit config set max_diff_size 20000

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

---

Roadmap

• Support for more AI providers (Google Gemini, local models)
• Interactive mode for commit message editing
• Commit message templates and customization
• Integration with GitHub CLI for PR descriptions
• VS Code extension
• Commit message translation to different languages
• Team collaboration features (shared configs, style guides)

---

License

MIT License - see LICENSE for details.

---

Acknowledgments

• Powered by Anthropic's Claude - State-of-the-art AI for understanding code
• Inspired by Conventional Commits - A specification for meaningful commit messages
• Built with:
  • Click - Beautiful command line interfaces
  • Rich - Rich text and formatting in terminal
  • GitPython - Git interface library
  • Anthropic SDK - Official Anthropic API client

---

Made with ❤️ by Master Shifu, for developers

If you find this project helpful, please consider giving it a ⭐️ on GitHub!

⬆ Back to Top