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
• 🆕 Robust Git Integration: Advanced Git state detection and error handling
  • Detached HEAD detection and warnings
  • Merge conflict detection with resolution hints
  • Dirty workspace validation before operations
  • Git worktrees and submodules support
  • CI/CD-friendly error codes and messages

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

Quick Start with Templates

Get started quickly with pre-configured templates:

# Apply a template for quick setup
gitgenius config --template default      # OpenAI GPT-3.5 (recommended)
gitgenius config --template gemini       # Google Gemini Pro
gitgenius config --template openai-gpt4  # OpenAI GPT-4 (detailed)
gitgenius config --template concise      # Short, concise messages
gitgenius config --template detailed     # Long, detailed messages

# Then set your API key
gitgenius config apiKey

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

Advanced Configuration Management

GitGenius provides powerful configuration management features:

Validation

gitgenius config --validate    # Check configuration for errors

Backup & Restore

gitgenius config --backup                    # Create backup
gitgenius config --restore backup-file.json  # Restore from backup

Import & Export

gitgenius config --export my-config.json   # Export to share
gitgenius config --import team-config.json # Import team settings

Migration

gitgenius config --migrate    # Manually migrate to latest version

Configuration Inheritance

GitGenius uses a three-level configuration system:

1. Global - System-wide settings (lowest priority)

   • Location: ~/.config/gitgenius/ (Linux/macOS) or %APPDATA%/gitgenius/ (Windows)
   • Use for default settings across all projects

2. User - User-specific settings (medium priority)

   • Same location as global, but can override specific values
   • Use for personal preferences

3. Project - Project-specific settings (highest priority)

   • Location: .gitgenius/config.json in your git repository
   • Use for team or project-specific requirements
   • Overrides both user and global settings

Example use case: Set OpenAI as your global provider, but use Gemini for a specific project by creating a project config in that repository.

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

| Command | Description | Example | |---------|-------------|---------| | gitgenius | Generate commit message | gitgenius | | gitgenius -a, --apply | Generate and commit | gitgenius -a | | gitgenius -c, --copy | Copy to clipboard | gitgenius -c | | gitgenius -t, --type <type> | Specify commit type | gitgenius -t feat | | gitgenius --dry-run | Preview commit message | gitgenius --dry-run |

Branch Management

| Command | Description | Example | |---------|-------------|---------| | gitgenius branch | List branches | gitgenius branch | | gitgenius branch -r | Include remote branches | gitgenius branch -r | | gitgenius branch -c | Copy branch name | gitgenius branch -c | | gitgenius checkout | Interactive checkout | gitgenius checkout |

Configuration Commands

| Command | Description | Example | |---------|-------------|---------| | gitgenius config | Show configuration | gitgenius config | | gitgenius config provider | Set AI provider | gitgenius config provider | | gitgenius config model | Set AI model | gitgenius config model | | gitgenius config --reset | Reset configuration | gitgenius config --reset | | gitgenius config --validate | Validate configuration | gitgenius config --validate | | gitgenius config --backup | Backup configuration | gitgenius config --backup | | gitgenius config --restore <file> | Restore from backup | gitgenius config --restore backup.json | | gitgenius config --template <name> | Apply template | gitgenius config --template gemini | | gitgenius config --export <file> | Export configuration | gitgenius config --export config.json | | gitgenius config --import <file> | Import configuration | gitgenius config --import config.json |

Configuration Templates:

• default - Default OpenAI GPT-3.5 configuration
• openai-gpt4 - GPT-4 for detailed messages
• gemini - Google Gemini Pro configuration
• concise - Concise messages with lower token limit
• detailed - Detailed messages with higher token limit
• conventional - Strict conventional commits format

Statistics and Analytics

| Command | Description | Example | |---------|-------------|---------| | gitgenius stats | Show commit statistics | gitgenius stats | | gitgenius stats --days 7 | Stats for 7 days | gitgenius stats --days 7 | | gitgenius stats --author "name" | Author-specific stats | gitgenius stats --author "John" |

Template Management

| Command | Description | Example | |---------|-------------|---------| | gitgenius template --list | List templates | gitgenius template --list | | gitgenius template --add <name> | Create template | gitgenius template --add feat | | gitgenius template --use <name> | Use template | gitgenius template --use feat |

Git State & Diagnostics

| Command | Description | Example | |---------|-------------|---------| | gitgenius state | Show repository state | gitgenius state | | gitgenius state --validate | Validate Git environment | gitgenius state --validate | | gitgenius state --worktrees | Show worktree details | gitgenius state --worktrees | | gitgenius state --submodules | Show submodule details | gitgenius state --submodules |

State Information Shown:

• Current branch or detached HEAD status
• Uncommitted changes detection
• Staged changes status
• Untracked files presence
• Merge/rebase in progress warnings
• Merge conflict detection
• Worktree information
• Submodule status
• Git environment validation

📖 Learn more about Git Integration

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

"Detached HEAD state"

• Create a branch: git checkout -b my-branch
• Return to a branch: git checkout main
• Check state: gitgenius state

"Merge conflicts detected"

• View conflicts: gitgenius state
• Resolve conflicts in files
• Stage resolved files: git add <file>
• Complete merge: git commit

"Cannot proceed: uncommitted changes"

• Commit changes: git commit -am "message"
• Stash changes: git stash
• Check state: gitgenius state

Debug Mode

Enable detailed logging:

Windows (PowerShell):

$env:DEBUG = "gitgenius*"; gitgenius
# or
$env:LOG_LEVEL = "debug"; gitgenius

macOS/Linux:

DEBUG=gitgenius* gitgenius
# or
LOG_LEVEL=debug gitgenius

Using CLI:

# Enable debug mode
gitgenius debug --enable

# Disable debug mode
gitgenius debug --disable

# Check debug status
gitgenius debug --status

# View performance metrics
gitgenius debug --performance

Logging and Monitoring

GitGenius includes comprehensive logging and debugging infrastructure:

View Logs:

# Show recent logs (last 50 entries)
gitgenius logs

# Show specific number of lines
gitgenius logs --lines 100

# Show log statistics
gitgenius logs --stats

# Export logs to file
gitgenius logs --export logs.json

# Set log level
gitgenius logs --level debug  # trace, debug, info, warn, error

# Clear all logs
gitgenius logs --clear

Error Tracking:

# List unresolved errors
gitgenius errors

# Show error statistics
gitgenius errors --stats

# Include resolved errors
gitgenius errors --resolved

# Filter by category
gitgenius errors --category git

# Export errors to file
gitgenius errors --export errors.json

# Clear resolved errors
gitgenius errors --clear --resolved

# Clear all errors
gitgenius errors --clear

Log Files Location:

• Logs: ~/.gitgenius/logs/gitgenius.log
• Errors: ~/.gitgenius/errors/errors.json

Features:

• Structured logging with multiple levels
• Automatic log rotation (10MB per file, max 5 files)
• Performance metrics tracking
• Error tracking with occurrence counting
• Debug mode with verbose output
• Console and file logging

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
gitgenius config --validate         # Validate configuration
gitgenius config --backup           # Backup configuration
gitgenius config --restore file.json # Restore from backup
gitgenius config --template gemini  # Apply Gemini template
gitgenius config --export file.json # Export configuration

Configuration Inheritance: GitGenius uses a three-level configuration system:

• Global: System-wide settings (lowest priority)
• User: User-specific settings (medium priority)
• Project: Project-specific settings in .gitgenius/ (highest priority)

Configuration Templates: Quick setup with pre-configured templates:

• default - OpenAI GPT-3.5 (balanced)
• openai-gpt4 - GPT-4 (detailed)
• gemini - Google Gemini Pro
• concise - Short messages
• detailed - Long messages
• conventional - Strict format

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!