🐥 Gitty

"That commit? mid. Let Gitty fix it."

🐥 Gitty says: "Let's make that message not suck."

Gitty is your snarky, AI-powered CLI bestie that helps you write commit messages that don't make your team cringe. Highly tested, cross-platform, and full of personality — it's the helpful pal Git never had. Because one does not simply "update code".

🤖 Choose Your AI Vibe:

• OpenAI (GPT-4o-mini, GPT-4o, GPT-3.5-turbo)
• Google Gemini (Gemini 2.5 Flash, Gemini 1.5 Flash, Gemini 1.5 Pro, Gemini 3.0 Pro)

✨ Why Gitty?

🐥 Gitty says: "Let me tell you why we're gonna be besties!"

Ever stared at your Git diff wondering how to explain your 3 AM coding spree? That's where I come in! I'm not just another Git tool – I'm your commit message hype person, powered by AI but with actual personality.

What Makes Me Special?

🎯 Smart Commits That Don't Suck
I turn your chaotic diffs into poetry. No more "updated stuff" commits – we're better than that! I analyze your changes and craft messages that actually make sense.

🎨 Your Style, Your Rules
Like your commits short and sweet? Or detailed enough to write a novel? I adapt to your style. Keep your commit game as unique as your playlist, just... you know, readable.

🚀 Zero Hassle Setup
Because life's complicated enough already. Quick install, easy config, and you're ready to commit like a pro. Works everywhere – macOS, Linux, Windows, your grandma's computer (probably).

📋 Different Vibes for Different Projects
Work mode? Personal project? Each needs its own flavor. My presets let you switch between professional and fun faster than you can say "git commit".

🤖 AI Provider? Your Choice!
Switch between OpenAI and Gemini like a DJ switching tracks. Use what works best for you, when you want it. No commitment issues here!

🧪 Rock-Solid Reliability
More test coverage than your code (probably). I take my job seriously, even if I don't take myself seriously.

🧸 Making Git Fun Again
Because Git doesn't have to be boring. I bring personality to your terminal, one commit at a time.

🔧 Tech Stack

| Layer | The Good Stuff | | --------------------- | --------------------------------------- | | Language | TypeScript (Node.js) | | CLI Framework | commander | | Prompting | inquirer | | AI Providers | OpenAI API, Google Generative AI | | Git Integration | simple-git | | Config Management | Custom config in ~/.gitty/config.json | | Packaging | npm install -g | | Cross-Platform | Runs everywhere (like your anxiety) |

📦 Installation

🐥 Gitty says: "Let's get you set up, bestie!"

Requirements

• Node.js 22+ (Current LTS - v22.16.0)
• Git installed and ready to party
• API key for at least one AI provider (OpenAI or Gemini)

Windows Users

🐥 Gitty says: "Windows users, I gotchu!"

• Git for Windows (includes Git Bash): https://git-scm.com/download/win
• Or use Windows Subsystem for Linux (WSL)
• Works in Command Prompt, PowerShell, and Git Bash

Install via NPM (Recommended)

npm install -g @kljuicy/gitty  # Let's gooo! 🚀

🔑 AI Provider Setup

🐥 Gitty says: "Pick your AI bestie (or use both, I don't judge)"

Gitty supports both OpenAI and Google Gemini. You can use either or both providers.

Option 1: OpenAI Setup

1. Sign up or log in to OpenAI
2. Add a payment method (Billing Settings)
3. Create an API key (starts with sk-)
4. Set up your key in Gitty:

   gitty --set-key --provider openai
   # or
   export OPENAI_API_KEY="sk-proj-your-key-here"

Option 2: Google Gemini Setup

1. Go to Google AI Studio
2. Click "Create API key"
3. Copy your API key
4. Set up your key in Gitty:

   gitty --set-key --provider gemini
   # or
   export GEMINI_API_KEY="your-gemini-key-here"

Set Default Provider

gitty --set-provider  # Choose your vibe

Security Best Practices:

🐥 Gitty says: "Keep those keys safe, fam!"

• Never share your API keys (treat them like passwords)
• Keys are stored locally in ~/.gitty/config.json (never in Git repos)
• Set spending limits in provider dashboards
• Monitor usage in provider dashboards
• No telemetry, no tracking, keys only sent to chosen provider

💰 Cost & Model Vibes

🐥 Gitty says: "Let me help you pick the perfect AI bestie for your wallet!"

✨ Pick Your Perfect Match

| Vibe Check | AI Bestie | Why Though? | | ----------------- | ---------------------------- | ---------------------------------------------- | | 💼 Daily Grind | gpt-4o-mini | Fast & cheap, like your favorite instant ramen | | 🚨 Critical Stuff | gpt-4o or gemini-3.0-pro | When you need that pixel-perfect commit | | 🆓 Free Spirit | gemini-2.5-flash | No cost, just vibes (default for Gemini) |

💸 The Money Talk

🐥 Gitty says: "Cheaper than your coffee addiction, I promise!"

🍜 Daily Commits (gpt-4o-mini)

Perfect for: "Just ship it" energy

• Input: $0.15 per 1M tokens
• Output: $0.60 per 1M tokens
• Per Commit*: ~$0.0003 (that's like, nothing)

🎯 Critical Commits

When you need that extra chef's kiss

OpenAI (gpt-4o)

• Input: $2.50 per 1M tokens
• Output: $10.00 per 1M tokens
• Per Commit*: ~$0.004

Gemini 1.5 Pro

• Input: $1.25 per 1M tokens
• Output: $5.00 per 1M tokens
• Per Commit*: ~$0.002

Gemini 3.0 Pro (Latest & Most Powerful)

• Input: $2.00-$4.00 per 1M tokens
• Output: $12.00-$18.00 per 1M tokens
• Per Commit*: ~$0.004-$0.009
• ⚠️ More expensive, but most capable

🆓 Budget Bestie (gemini-2.5-flash) (Default for Gemini)

For the "I'm not paying for commits" crowd

• Input: $0.075 per 1M tokens
• Output: $0.30 per 1M tokens
• Per Commit*: ~$0.0001 (basically free)
• ✅ Latest stable Flash model - fast & affordable

*Based on average diff of 1000 tokens + 500 token response

🎯 Pro Tips for the Penny-Pinchers

🐥 Gitty says: "Let me help you save those coins!"

• 💡 Use gpt-4o-mini for your daily commits
• 🚀 Save the fancy models for the big feature releases
• 🌟 Try Gemini Flash when you're feeling frugal
• 📝 Lower maxTokens if you like it short and sweet
• 🎨 Use presets to auto-pick the right model for each project
• 🌡️ Lower temperature for shorter messages: gitty -t 0.3

Remember: You can switch models on the fly with -m flag:

# Everyday commits
gitty -m gpt-4o-mini

# That big refactor you're proud of
gitty -m gpt-4o

# Latest & greatest (but more expensive)
gitty -m gemini-3.0-pro --provider gemini

# When the budget is tight (default for Gemini)
gitty -m gemini-2.5-flash --provider gemini

🚀 Getting Started

🐥 Gitty says: "Let's get this party started!"

1. Install and set up your preferred AI provider:

   # Quick setup with OpenAI
   gitty --set-key --provider openai
   
   # Or use Gemini (free tier available)
   gitty --set-key --provider gemini
   gitty --set-provider  # Set as default

2. Try it out in your git repo:

   cd your-git-repo
   gitty
   # Generates 3 commit message options from your current git diff

3. (Optional) Set up project presets:

   gitty -P work --add-repo
   # Links this repo to the 'work' preset for automatic detection

See the CLI Reference below for all available flags and options.

⚙️ Configuration & Presets

🐥 Gitty says: "Make me work how you work"

Gitty uses a layered configuration system:

1. CLI flags (highest priority)
2. Local repo config: .git/gittyrc.json (per-repo overrides)
3. Global presets: ~/.gitty/config.json (named presets)
4. Global defaults

Example global config (~/.gitty/config.json):

{
  "defaultProvider": "openai",
  "providers": {
    "openai": {
      "apiKey": "sk-personal-key",
      "model": "gpt-4o-mini",
      "temperature": 0.7,
      "maxTokens": 500
    },
    "gemini": {
      "apiKey": "personal-gemini-key",
      "model": "gemini-2.5-flash",
      "temperature": 0.7,
      "maxTokens": 2048
    }
  },
  "default": {
    "prepend": "",
    "style": "concise",
    "language": "en"
  },
  "presets": {
    "work": {
      "prepend": "DEV-",
      "style": "detailed",
      "language": "en",
      "defaultProvider": "gemini",
      "providers": {
        "openai": {
          "apiKey": "sk-work-billing-key",
          "temperature": 0.5,
          "model": "gpt-4o-mini"
        },
        "gemini": {
          "apiKey": "work-gemini-key",
          "temperature": 0.5,
          "model": "gemini-2.5-flash"
        }
      }
    }
  }
}

Example local config (.git/gittyrc.json in your project's root folder):

{
  "preset": "work",
  // Local overrides:
  "style": "funny",
  "defaultProvider": "openai",
  "providers": {
    "openai": {
      "apiKey": "sk-project-specific-key",
      "model": "gpt-4o"
    }
  }
}

• If preset is set, local config inherits from the named global preset.
• Any field in local config overrides the preset/global value.
• You can also use a fully local config with no preset reference.

Config resolution order: CLI flags > local config > preset > global defaults.

🏷️ Prepend Behavior

Prepend text appears before your AI-generated commit message. Gitty supports two prepend modes:

Append Mode (Default)

• CLI prepend adds to the resolved prepend from config hierarchy
• Useful for adding ticket numbers or short tags

# Preset has: prepend: "PROJ-"
gitty -P work -p "123"        # Result: "PROJ-123 <AI message>"
gitty -P work -p "URGENT-"    # Result: "PROJ-URGENT- <AI message>"

Force Mode

• CLI prepend replaces the entire resolved prepend
• Useful for hotfixes, special commits, or temporary overrides

# Preset has: prepend: "PROJ-"
gitty -P work -p "HOTFIX-" -f # Result: "HOTFIX- <AI message>"
gitty -P work -p "" -f        # Result: "<AI message>" (no prepend)

Examples:

# Normal workflow: append ticket numbers
gitty -P work -p "456"        # "PROJ-456 fix: update user validation"

# Emergency situation: completely override
gitty -P work -p "URGENT-" -f # "URGENT- fix: critical security issue"

# One-off commit: remove prepend entirely
gitty -P work -p "" -f        # "refactor: clean up helper functions"

✨ API Key Override Hierarchy

API keys are resolved in this priority order:

1. Local config → .git/gittyrc.json provider API key (highest priority)
2. Preset config → Global preset provider API key
3. Global config → Global provider API key
4. Environment variables → OPENAI_API_KEY, GEMINI_API_KEY (fallback)

Example scenarios:

• Personal projects: Use personal API keys from global config
• Work projects: Override with company billing keys in work preset
• Specific project: Override with project-specific key in local config
• Team collaboration: Each developer has their own local API key override

⚡ Usage Examples

🐥 Gitty says: "Watch and learn, bestie!"

# Basic usage - let's keep it simple
gitty

# Switch up the AI vibe
gitty --provider gemini  # Try Gemini's fresh takes
gitty --provider openai  # Classic OpenAI energy

# Link to your work preset (because profesh)
gitty -P work --add-repo

# Add your ticket number (management loves this)
gitty -P work -p "123"

# URGENT? I got you
gitty -P work -p "HOTFIX-" -f

# Feeling fancy? Try different models
gitty -m gpt-4o-mini -t 0.3
gitty -m gemini-3.0-pro --provider gemini  # Latest & powerful
gitty -m gemini-1.5-pro --provider gemini  # Good balance
gitty -m gemini-2.5-flash --provider gemini # Budget-friendly (default)

# Mamma mia! Generate in Italian 🤌
gitty -l it

# Mix and match like a pro
gitty --provider gemini -m gemini-2.5-flash
gitty --provider openai -m gpt-4o

🧰 Core Features

🐥 Gitty says: "Everything you need, nothing you don't"

• AI commit message generation from your Git diff
• Multiple AI providers (OpenAI and Google Gemini)
• Multiple message options with interactive selection
• Customizable style, language, and prepend
• Project presets for different workflows
• Secure API key storage
• Provider-specific optimizations
• Comprehensive test coverage with excellent branch coverage
• No telemetry, no tracking

📋 CLI Reference

🐥 Gitty says: "All the commands you'll ever need (and then some)"

Commands (One-Time Setup)

| Command | Description | | ----------------------------- | ----------------------------------------- | | --set-key --provider <name> | Save API key for provider (openai/gemini) | | --set-provider | Choose your default AI provider | | --add-repo -P <preset> | Link current repo to a preset |

Generation Options (Daily Usage)

| Flag | Short | Description | | ------------------- | ----- | -------------------------------------------------- | | --preset <name> | -P | Use a specific preset configuration | | --provider <name> | | Override provider (openai/gemini) | | --prepend <str> | -p | Add prefix to commit message | | --force-prepend | -f | Replace entire prefix instead of appending | | --style <type> | -s | Set style: concise, detailed, funny | | --language <code> | -l | Language for commit message (2-letter code) | | --model <model> | -m | Override AI model (provider-specific) | | --temperature <t> | -t | AI creativity (0-2, default: 0.7) | | --max-tokens <n> | | Response length limit (default varies by provider) |

Execution Options

| Flag | Short | Description | | ----------- | ----- | ----------------------------------- | | --preview | -v | Show suggestions without committing |

🔗 Flag Dependencies & Combinations

Some flags require others to work properly:

| Primary Flag | Required Dependency | Example | | ----------------- | ------------------- | ----------------------------------- | | --set-key | --provider | gitty --set-key --provider openai | | --force-prepend | --prepend | gitty -p "HOTFIX-" -f | | --add-repo | --preset | gitty --add-repo -P work |

📝 Common Usage Patterns

# Setup commands (one-time)
gitty --set-key --provider openai          # Configure OpenAI API key
gitty --set-key --provider gemini          # Configure Gemini API key
gitty --set-provider                       # Set default provider interactively
gitty --add-repo -P work                   # Link current repo to 'work' preset

# Daily usage (generation)
gitty                                      # Generate commit with defaults
gitty -P work                              # Use work preset
gitty -p "PROJ-123"                        # Add prefix (appends to preset)
gitty -p "HOTFIX-" -f                      # Force replace entire prepend
gitty --provider gemini -m gemini-3.0-pro # Override provider & model (latest)
gitty -l it -s detailed                   # Italian detailed commits
gitty -t 0.3 --max-tokens 200              # Lower creativity, shorter messages

# Execution control
gitty -v                                   # Preview only, don't commit
gitty -P work -p "123" -v                  # Preview with work preset + ticket

Provider-specific models:

• OpenAI: gpt-4o-mini (default), gpt-4o, gpt-3.5-turbo
• Gemini: gemini-2.5-flash (default), gemini-1.5-flash, gemini-1.5-pro, gemini-3.0-pro

💡 Note: These are commonly used models. Gitty supports any model your provider offers - just specify it with -m <model-name>. Check your provider's documentation for the latest available models.

🧸 User Experience

🐥 Gitty says: "Making Git fun since... well, just now!"

When you run gitty, here's what happens:

1. Diff Preview - Gitty shows you a summary of your staged changes
2. AI Generation - Three commit message options are generated based on your changes
3. Interactive Menu - Choose from the options, edit one, regenerate, or quit
4. Confirmation - Review your selected message and confirm to create the commit

All with a clean, interactive terminal interface. Because commit messages should spark joy. ✨

License

🐥 Gitty says: "Free as in freedom (and beer)!"

This project is licensed under the MIT License - see the LICENSE file for details.

🦊 Real Talk: GitLab is Home

🐥 Gitty says: "Let me spill some tea about where the magic happens!"

The Truth: All the real development, CI/CD pipelines, issues, and actual work happens on GitLab. That's where I live, breathe, and get my commits together.

GitHub? Oh, that's just our cool kid mirror so we can hang with the popular crowd. You know how it is – gotta be where the people are! 😎

Want to contribute? Head over to GitLab where the real party is. Issues, MRs, discussions – it's all there. GitHub is just for the gram, baby! 📸

Cute commits. Clean history.

Report Bug • Request Feature • Documentation

Vibecoded with ❤️ for devs who care about clean commit history