gimi

README

   ██████╗ ██╗███╗   ███╗██╗
  ██╔════╝ ██║████╗ ████║██║
  ██║  ███╗██║██╔████╔██║██║
  ██║   ██║██║██║╚██╔╝██║██║
  ╚██████╔╝██║██║ ╚═╝ ██║██║
   ╚═════╝ ╚═╝╚═╝     ╚═╝╚═╝
  

AI-Powered Git Commit Message Generator

---

Gimi (Git + Commit) is a command-line tool that analyzes your staged Git changes and generates meaningful conventional commit messages using AI. It supports multiple AI backends — OpenAI, Google Gemini, and Ollama (local) — so you can choose the provider that fits your workflow.

Features

• AI-Powered Messages — Generate conventional commit messages from your staged diffs using OpenAI, Google Gemini, or Ollama
• One-Command Commit — Generate a message and commit in a single step with gimi commit
• Edit Before Commit — Review and modify the AI-generated message in your preferred editor before committing
• Commit Type Override — Force a specific conventional commit type (feat, fix, docs, etc.) regardless of AI suggestion
• Configuration Display — View your current setup at a glance without exposing sensitive API keys
• Multiple AI Backends — Switch between OpenAI, Google Gemini, and Ollama with a single command
• Local-First Option — Use Ollama for fully offline, private commit message generation
• Conventional Commits — All generated messages follow the <type>(scope): <message> format
• Fast & Lightweight — Single binary, no runtime dependencies

Table of Contents

• Installation
• Quick Start
• Usage
  • Initialize Configuration
  • Generate a Commit Message
  • Generate and Commit
  • Edit Before Commit
  • Override Commit Type
  • Browse Commit History
  • View Configuration
  • Reset Configuration
• AI Backend Setup
• Command Reference
• Configuration
• Troubleshooting
• Contributing
• License

Installation

Option 1: NPM (Recommended)

Installs a pre-compiled binary for your platform (macOS, Linux, Windows).

npm install -g gimi-cli

"Command not found" after install? Your NPM global bin directory may not be in your PATH. Run npm config get prefix to find it, then add its bin/ subdirectory to your PATH:

export PATH="$PATH:$(npm config get prefix)/bin"

Add the line above to your ~/.zshrc or ~/.bashrc to make it permanent.

Option 2: Go Install

Requires Go 1.22+:

go install github.com/shivgitcode/gimi@latest

Make sure $GOPATH/bin is in your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Option 3: Build from Source

git clone https://github.com/Shivgitcode/gimi.git
cd gimi
go build -o gimi .
sudo mv gimi /usr/local/bin/   # or anywhere in your PATH

Updating

# NPM
npm install -g gimi-cli@latest

# Go
go install github.com/shivgitcode/gimi@latest

Quick Start

# 1. Set up your AI provider (one-time)
gimi init

# 2. Make some code changes, then generate a commit message
gimi generate

# 3. Or generate AND commit in one step
gimi commit

# 4. Edit the message before committing
gimi commit --edit

Usage

Initialize Configuration

Run once to select your AI backend and provide credentials:

gimi init

You will be prompted to:

1. Choose a backend: OpenAI, Gemini, or Ollama
2. Enter your API key (not required for Ollama)
3. Choose a model name (defaults provided)

Configuration is saved to ~/.gimi/config.json.

Generate a Commit Message

Stage your changes and generate a message:

gimi generate

Gimi will:

1. Stage all changes (git add .)
2. Read the staged diff
3. Send it to your configured AI backend
4. Display the generated conventional commit message

Generate and Commit

Generate a message and commit in one step:

gimi generate -commit

Or use the shorthand:

gimi commit

You will be asked to confirm before the commit is executed.

Edit Before Commit

Review and modify the AI-generated message in your text editor:

gimi commit --edit
# or
gimi commit -e
# or
gimi generate -commit -edit

Gimi opens the message in your $EDITOR (falls back to vim, then nano). Save and exit to proceed with the edited message. Exit without saving or clear the file to cancel the commit.

Override Commit Type

Force a specific conventional commit type:

gimi commit --type feat
# or
gimi commit -t fix
# or
gimi generate -type docs

Valid types: feat, fix, docs, style, refactor, test, chore, perf

You can combine flags:

# Override type AND edit before committing
gimi commit -t refactor --edit

Browse Commit History

View recent commits and copy any commit command for reuse:

gimi history

Use -n to control how many commits to show:

gimi history -n 20

Gimi will:

1. Display your recent commits in an interactive list
2. Let you select one with arrow keys
3. Show the full git commit -m "..." command
4. Automatically copy it to your clipboard (macOS/Linux/Windows)

This is useful when you want to reuse a past commit message format or replicate a commit style.

View Configuration

Display your current settings without exposing API keys:

gimi config show

Example output:

┌─────────────────────────────────────┐
│        GIMI Configuration            │
├─────────────────────────────────────┤
  AI Backend:      Gemini
  Model:           gemini-2.5-flash
  API Key:         configured
└─────────────────────────────────────┘

Reset Configuration

Clear all settings and start fresh:

gimi reset

AI Backend Setup

OpenAI

1. Get an API key from platform.openai.com
2. Run gimi init, select openai
3. Enter your API key and model (default: gpt-4.1)

Google Gemini

1. Get an API key from Google AI Studio
2. Run gimi init, select gemini
3. Enter your API key and model (default: gemini-2.5-flash)

Ollama (Local / Offline)

1. Install Ollama from ollama.com
2. Pull a model: ollama pull qwen2.5
3. Run gimi init, select ollama
4. No API key needed — runs entirely on your machine

Command Reference

Command	Description
gimi init	Initialize configuration (select AI backend, set API key)
gimi generate	Generate a commit message from staged changes
gimi generate -commit	Generate and commit after confirmation
gimi commit	Shorthand for generate -commit
gimi commit --edit / -e	Edit the generated message in your editor before committing
gimi commit --type <type> / -t <type>	Override the commit type (feat, fix, docs, etc.)
gimi history	Browse recent commits and copy a commit command
gimi history -n 20	Show last 20 commits (default: 10)
gimi config show	Display current configuration
gimi reset	Reset configuration to defaults
gimi help / -h	Show available commands
gimi version / -v	Show version

Configuration

Configuration is stored in ~/.gimi/config.json:

{
  "backend": "gemini",
  "apiKey": "your-api-key-here",
  "model": "gemini-2.5-flash"
}

Field	Description	Required
backend	AI provider: openai, gemini, or ollama	Yes
apiKey	API key for the selected provider	Yes (except Ollama)
model	Model name to use for generation	Yes

Security Note: Your API key is stored locally in ~/.gimi/config.json. The gimi config show command never displays the actual key value.

Troubleshooting

"Command not found" after installation

Ensure the installation directory is in your PATH:

# For NPM installs
export PATH="$PATH:$(npm config get prefix)/bin"

# For Go installs
export PATH="$PATH:$(go env GOPATH)/bin"

"Either one of the config is missing"

Run gimi init to set up your configuration, or gimi config show to check what's missing.

"No staged changes found"

Gimi needs staged changes to generate a message. Make sure you have modified files:

git status          # Check for changes
git add .           # Stage changes
gimi generate       # Now generate

Ollama connection errors

Ensure Ollama is running:

ollama serve        # Start the Ollama server
ollama list         # Verify models are available

Editor doesn't open (--edit flag)

Set your preferred editor:

export EDITOR=nano  # or vim, code --wait, etc.

Add to ~/.zshrc or ~/.bashrc to make permanent.

Invalid commit type

The --type flag only accepts conventional commit types:

feat, fix, docs, style, refactor, test, chore, perf

Development

Running from Source

# Run directly (does NOT use the installed binary)
go run . generate
go run . commit --edit

# Install your local changes as the global `gimi` command
go install .

Release Process

# Cross-compile and update version
./build.sh 1.0.0

# Publish to NPM
cd npm && npm publish

# Tag and push
git tag v1.0.0
git push origin v1.0.0

See CONTRIBUTING.md for development guidelines.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on:

• Reporting bugs and requesting features
• Setting up the development environment
• Submitting pull requests
• Code style and conventions

License

This project is licensed under the MIT License. See LICENSE for details.

---

Copyright © 2025 [Your Name]. All rights reserved.
Made with care for developers who write better code than commit messages.