GitFlow Toolkit

GitFlow Toolkit is a CLI tool written in Go for standardizing git commit messages following the Conventional Commits 1.0.0 specification. It provides an interactive TUI for creating commits, branches, and managing git operations.

demo.webm

Features

• Interactive TUI for commit message creation (Conventional Commits 1.0.0)
• AI-powered commit message generation (OpenRouter, Groq, OpenAI, Ollama)
• Git subcommand integration (git ci, git ps, git feat, etc.)
• Lucky commit hash prefix support
• Adaptive terminal UI with light/dark theme

Requirements

• Git
• macOS or Linux (Windows is not fully tested)

Installation

Homebrew (macOS/Linux)

brew install mritd/gitflow-toolkit/gitflow-toolkit

Manual

Download the latest binary from the Release page and run the install command:

# Download the latest release (replace PLATFORM with: linux-amd64, darwin-arm64, etc.)
curl -fsSL https://github.com/mritd/gitflow-toolkit/releases/latest/download/gitflow-toolkit-PLATFORM -o gitflow-toolkit
chmod +x gitflow-toolkit

# Install (creates symlinks for git subcommands)
sudo ./gitflow-toolkit install

Go

go install github.com/mritd/gitflow-toolkit/v3@latest

Note: When installing via go install, you need to manually run gitflow-toolkit install to create git subcommand symlinks.

Usage

After installation, you can use the following git subcommands:

Commit

git ci

This opens an interactive TUI to create a commit message with:

• Type selection (feat, fix, docs, build, etc.)
• Scope input (optional)
• Subject line (required)
• Optional body (supports external editor with Ctrl+E)
• Optional footer
• Optional breaking change description (auto adds ! marker)

Push

git ps

Push the current branch to origin with a progress indicator.

Create Branch

git feat my-feature    # Creates feat/my-feature
git fix bug-123        # Creates fix/bug-123
git docs readme        # Creates docs/readme

Commands

Commit Message Format

The tool follows the Conventional Commits 1.0.0 specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Supported types: feat, fix, docs, style, refactor, test, chore, perf, hotfix, build

Configuration

All settings are configured via ~/.gitconfig under the [gitflow] section.

[gitflow]
    # LLM API key (required for cloud providers)
    llm-api-key = sk-or-v1-xxxxx
    
    # LLM settings
    llm-api-host = https://openrouter.ai
    llm-api-path = /api/v1/chat/completions
    llm-model = mistralai/devstral-2512:free
    llm-temperature = 0.3
    llm-diff-context = 5
    llm-max-diff-lines = 500
    llm-request-timeout = 2m
    llm-max-retries = 0
    llm-output-lang = en
    llm-max-concurrency = 3
    llm-api-debug = false

    # Custom prompts (optional, language-specific)
    llm-file-analysis-prompt = "Summarize this diff briefly."
    llm-commit-prompt-en = "Your custom English commit prompt."
    llm-commit-prompt-zh = "Your custom Chinese commit prompt."
    llm-commit-prompt-bilingual = "Your custom bilingual commit prompt."
    
    # Lucky commit prefix (hex characters, max 12)
    lucky-commit-prefix = abc
    
    # SSH strict host key checking (default: false)
    ssh-strict-host-key = false
    
    # Auto-detect commit type from branch name (default: false)
    branch-auto-detect = true

    # Require optional fields (default: false)
    require-scope = false
    require-body = false
    require-footer = false

Configuration Reference

Auto Generate (AI)

Generate commit messages automatically using LLM:

1. Run git ci and press Tab to switch to the Auto Generate button (or press a)
2. Wait for AI to generate the commit message
3. Review the generated message, then choose:
   • Commit: Use the message as-is
   • Edit: Open in $EDITOR for modifications
   • Retry: Regenerate the message

Provider Selection:

Custom API Path:

If your provider uses a non-standard path, set it explicitly:

git config --global gitflow.llm-api-path "/custom/v1/chat/completions"

Quick Start with OpenRouter (recommended):

git config --global gitflow.llm-api-key "sk-or-v1-xxxxx"
git ci  # Press 'a' or Tab to Auto Generate

Quick Start with Local Ollama:

ollama pull deepseek-coder-v2:16b
git ci

Language Options:

• en - English only (default)
• zh - Chinese subject and body (type/scope remain English)
• bilingual - Bilingual subject english (中文) with Chinese body

Lucky Commit

Generate commit hashes with a specific prefix using lucky_commit:

# Install lucky_commit first
cargo install lucky_commit

# Set the desired prefix (hex characters, max 12)
git config --global gitflow.lucky-commit-prefix abc

# Commit as usual - hash will start with "abc"
git ci

• Prefix must be valid hex characters (0-9, a-f)
• Maximum prefix length is 12 characters
• Press Ctrl+C during search to skip and keep original commit

Branch Auto-Detection

Automatically pre-select the commit type based on your current branch name:

# Enable the feature
git config --global gitflow.branch-auto-detect true

# Now when you're on a branch like "feat/login" or "feature-new-ui"
git ci  # Cursor will auto-select "feat" type

Supported branch prefixes:

Supports separators: /, -, _ (e.g., feat/login, fix-bug-123, docs_readme)

Uninstall

Homebrew

brew uninstall gitflow-toolkit
brew untap mritd/gitflow-toolkit

Manual

sudo gitflow-toolkit uninstall

License

MIT