GitGenius

AI-Powered Commit Message Generator

GitGenius is a professional command-line tool that generates intelligent, context-aware commit messages using AI. Built for developers who value code quality and clear commit history.

Table of Contents

• Features
• Installation
• Configuration
• Usage
• Platform-Specific Setup
• Commands
• Troubleshooting
• Development
• Contributing

Features

• Intelligent Commit Messages: AI-generated commit messages based on staged changes
• Multiple AI Providers: OpenAI GPT and Google Gemini support
• Conventional Commits: Built-in support for conventional commit standards
• Interactive Editing: Edit generated messages before committing
• Branch Management: Interactive branch switching and management
• Git Statistics: Detailed commit analytics and insights
• Custom Templates: Create and manage commit message templates
• Cross-Platform: Full support for Windows, macOS, and Linux
• Clipboard Integration: Quick copy functionality
• Previous Message Retrieval: Access and amend previous commits

Installation

Prerequisites

• Node.js 16.0 or higher
• npm 7.0 or higher
• Git installed and configured

Global Installation

npm install -g @dharshansr/gitgenius

Verify Installation

gitgenius --version
# or
gg --version

Update to Latest Version

npm update -g @dharshansr/gitgenius

Configuration

Initial Setup

1. Set up your AI provider API key:

gitgenius config apiKey

2. Choose your AI provider:

gitgenius config provider

3. Select your preferred model:

gitgenius config model

API Key Configuration

OpenAI Setup

1. Visit OpenAI Platform
2. Create a new API key
3. Configure GitGenius:

   gitgenius config apiKey
   # Enter your OpenAI API key when prompted

Google Gemini Setup

1. Visit Google AI Studio
2. Create a new API key
3. Configure GitGenius:

   gitgenius config provider
   # Select "Google Gemini"
   gitgenius config apiKey
   # Enter your Gemini API key when prompted

Environment Variables

You can also configure GitGenius using environment variables:

export GITGENIUS_API_KEY="your_api_key_here"
export GITGENIUS_PROVIDER="openai"  # or "gemini"
export GITGENIUS_MODEL="gpt-3.5-turbo"  # or your preferred model

Platform-Specific Setup

Windows

PowerShell Configuration

Add to your PowerShell profile ($PROFILE):

$env:GITGENIUS_API_KEY = "your_api_key_here"

Command Prompt Configuration

Add to your system environment variables:

1. Press Win + R, type sysdm.cpl
2. Go to Advanced > Environment Variables
3. Add GITGENIUS_API_KEY with your API key value

Configuration File Location

%APPDATA%\gitgenius\config.json

macOS

Shell Configuration

Add to your shell profile (~/.zshrc or ~/.bash_profile):

export GITGENIUS_API_KEY="your_api_key_here"
export PATH="/usr/local/bin:$PATH"  # Ensure npm global packages are in PATH

Configuration File Location

~/Library/Preferences/gitgenius/config.json

Linux

Shell Configuration

Add to your shell profile (~/.bashrc or ~/.zshrc):

export GITGENIUS_API_KEY="your_api_key_here"
export PATH="$HOME/.npm-global/bin:$PATH"  # If using npm global prefix

Configuration File Location

~/.config/gitgenius/config.json

Ubuntu/Debian Additional Setup

# Ensure npm global packages work correctly
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

Usage

Basic Workflow

1. Stage your changes:

   git add .

2. Generate commit message:

   gitgenius

3. Apply directly:

   gitgenius --apply

Quick Commands

# Generate and apply commit
gitgenius -a

# Generate with specific type
gitgenius -t feat

# Copy to clipboard
gitgenius -c

# Preview without applying (dry run)
gitgenius --dry-run

# Combine options
gitgenius -t fix -a -c

Commands

Core Commands

Branch Management

Configuration Commands

Statistics and Analytics

Template Management

Supported Commit Types

GitGenius supports conventional commit standards:

• feat - New features
• fix - Bug fixes
• docs - Documentation changes
• style - Code style changes
• refactor - Code refactoring
• test - Test changes
• chore - Maintenance tasks
• perf - Performance improvements
• ci - CI/CD changes
• build - Build system changes

Troubleshooting

Common Issues

"Command not found: gitgenius"

• Ensure npm global packages are in your PATH
• Try reinstalling: npm uninstall -g @dharshansr/gitgenius && npm install -g @dharshansr/gitgenius

"Not in a git repository"

• Initialize git repository: git init
• Ensure you're in the correct directory

"No staged changes found"

• Stage your changes: git add <files>
• Check status: git status

"Invalid API key"

• Verify API key: gitgenius config apiKey
• Check environment variable: echo $GITGENIUS_API_KEY

"Network/API errors"

• Check internet connection
• Verify API key has sufficient credits
• Try different model: gitgenius config model

Debug Mode

Enable detailed logging:

Windows (PowerShell):

$env:DEBUG = "gitgenius*"; gitgenius

macOS/Linux:

DEBUG=gitgenius* gitgenius

Reset Configuration

If experiencing persistent issues:

gitgenius config --reset

Development

Local Development Setup

# Clone repository
git clone https://github.com/DharshanSR/gitgenius.git
cd gitgenius

# Install dependencies
npm install

# Build project
npm run build

# Link for testing
npm link

# Run tests
npm test

# Start development
npm run dev

Release Management

GitGenius includes automated version management:

# Patch release (1.0.0 → 1.0.1)
npm run release:patch

# Minor release (1.0.1 → 1.1.0)  
npm run release:minor

# Major release (1.1.0 → 2.0.0)
npm run release:major

Each release command automatically:

• Runs tests and builds
• Updates version numbers
• Creates git commit and tag
• Pushes to GitHub
• Publishes to npm

Contributing

We welcome contributions! Please read our Contributing Guide for details.

Development Guidelines

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Ensure all tests pass
5. Submit a pull request

Code Standards

• TypeScript for all source code
• ESLint for code quality
• Jest for testing
• Conventional commits for commit messages

License

MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• npm Package: npm Page

GitGenius - Intelligent commit messages for professional development workflows.

Usage

Basic Commands

Generate a commit message:

gitgenius

Apply the generated commit message directly:

gitgenius --apply  # or -a

Copy the generated message to clipboard:

gitgenius --copy   # or -c

Specify commit type:

gitgenius --type feat  # or -t feat

Combine options:

gitgenius -t fix -a -c  # Generate fix-type commit, apply and copy

Advanced Features

Previous Commit Management

gitgenius prev                    # Show previous message
gitgenius prev --apply            # Apply previous message
gitgenius prev --edit --amend     # Edit and amend previous commit

Branch Management

gitgenius branch                  # List branches
gitgenius branch --remote         # Include remote branches
gitgenius branch --copy           # Select and copy branch name
gitgenius branch --delete         # Delete branches
gitgenius checkout                # Interactive branch checkout

Configuration

gitgenius config                  # Show all config
gitgenius config provider         # Set AI provider
gitgenius config model            # Set AI model
gitgenius config --reset          # Reset configuration

Templates

gitgenius template --list         # List templates
gitgenius template --add "feat"   # Add new template
gitgenius template --use "feat"   # Use template

Statistics

gitgenius stats                   # Show commit stats (30 days)
gitgenius stats --days 7          # Stats for last 7 days
gitgenius stats --author "John"   # Stats for specific author

Configuration

API Providers

OpenAI (default)

gitgenius config provider
# Select: OpenAI
gitgenius config model
# Choose: gpt-3.5-turbo, gpt-4, or gpt-4-turbo-preview

Google Gemini

gitgenius config provider
# Select: Google Gemini
gitgenius config model
# Choose: gemini-pro or gemini-pro-vision

Environment Variables

• GITGENIUS_API_KEY: Your AI provider API key
• Supported providers:
  • OpenAI: Get key from OpenAI Dashboard
  • Gemini: Get key from Google AI Studio

Configuration File

GitGenius stores configuration in your system's config directory:

• Linux: ~/.config/gitgenius/config.json
• macOS: ~/Library/Preferences/gitgenius/config.json
• Windows: %APPDATA%/gitgenius/config.json

Commit Types

GitGenius supports conventional commit types:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test additions/modifications
• chore: Maintenance tasks
• perf: Performance improvements
• ci: CI/CD changes
• build: Build system changes

Examples

Basic Usage

# Stage changes
git add src/components/Button.tsx

# Generate and apply commit
gitgenius -t feat -a
# Output: "feat: add new Button component with hover effects"

Branch Management

# Interactive branch switching
gitgenius checkout

# List and copy branch name
gitgenius branch -c

# Delete unused branches
gitgenius branch --delete

Templates

# Create a template
gitgenius template --add "hotfix"
# Pattern: "hotfix: {description}"

# Use the template
gitgenius template --use "hotfix"

Troubleshooting

Common Issues

1. "Not in a git repository"

   • Ensure you're in a git repository: git init

2. "No staged changes found"

   • Stage your changes first: git add <files>

3. "Invalid API key"

   • Verify your API key: gitgenius config apiKey
   • Check environment variable: echo $GITGENIUS_API_KEY

4. Module resolution errors

   • Update Node.js to version 16 or higher
   • Clear npm cache: npm cache clean --force

Debug Mode

Enable verbose logging:

DEBUG=gitgenius* gitgenius

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/DharshanSR/gitgenius.git

# Install dependencies
cd gitgenius
npm install

# Build the project
npm run build

# Link for local development
npm link

# Run tests
npm test

Automated Release Management

GitGenius includes automated version management - no need to manually update version numbers!

Release Commands

# For bug fixes (1.0.0 → 1.0.1)
npm run release:patch

# For new features (1.0.1 → 1.1.0)
npm run release:minor

# For breaking changes (1.1.0 → 2.0.0)
npm run release:major

What Happens Automatically

Each release command automatically:

• ✅ Runs all tests and builds the project
• ✅ Updates version in package.json and package-lock.json
• ✅ Creates a git commit with the version bump
• ✅ Creates a git tag (e.g., v1.0.1)
• ✅ Pushes changes and tags to GitHub
• ✅ Publishes the new version to npm

Example Workflow

# Make your changes
git add .
git commit -m "feat: add new AI provider support"

# Release new minor version automatically
npm run release:minor
# ✨ Version bumped to 1.1.0, tagged, pushed, and published!

No manual version management required! 🚀

License

MIT License - see LICENSE file for details.

Changelog

See CHANGELOG.md for version history.

Support

• 🐛 Report Issues
• 💬 Discussions
• 📖 Documentation

GitGenius - Making commit messages intelligent, one commit at a time! ⭐

If you find this tool helpful, please consider giving it a star on GitHub!