https://github.com/mritd/gitflow-toolkit
A simple toolkit for GitFlow.
https://github.com/mritd/gitflow-toolkit
gitflow gitflow-toolkit toolkit
Last synced: about 1 month ago
JSON representation
A simple toolkit for GitFlow.
- Host: GitHub
- URL: https://github.com/mritd/gitflow-toolkit
- Owner: mritd
- License: mit
- Created: 2018-03-05T08:45:08.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2026-01-24T00:58:43.000Z (3 months ago)
- Last Synced: 2026-01-24T05:36:32.988Z (3 months ago)
- Topics: gitflow, gitflow-toolkit, toolkit
- Language: Go
- Homepage:
- Size: 9.06 MB
- Stars: 231
- Watchers: 3
- Forks: 19
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- charm-in-the-wild - gitflow-toolkit - A GitFlow submission tool. (_built with Bubble Tea_) (Applications / Development Tools)
README
# GitFlow Toolkit
GitFlow Toolkit is a CLI tool written in Go for standardizing git commit messages following the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification. It provides an interactive TUI for creating commits, branches, and managing git operations.
[demo.webm](https://github.com/user-attachments/assets/f50ea867-3be3-46c0-905c-e0a092f9d6a0)
## 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)
```bash
brew install mritd/gitflow-toolkit/gitflow-toolkit
```
### Manual
Download the latest binary from the [Release page](https://github.com/mritd/gitflow-toolkit/releases) and run the install command:
```bash
# 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
```bash
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
```bash
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
```bash
git ps
```
Push the current branch to origin with a progress indicator.
### Create Branch
```bash
git feat my-feature # Creates feat/my-feature
git fix bug-123 # Creates fix/bug-123
git docs readme # Creates docs/readme
```
## Commands
| Command | Description |
|---------------------|------------------------------------------------|
| `git ci` | Interactive commit message creation |
| `git ps` | Push current branch to remote |
| `git feat NAME` | Create branch `feat/NAME` |
| `git fix NAME` | Create branch `fix/NAME` |
| `git hotfix NAME` | Create branch `hotfix/NAME` |
| `git docs NAME` | Create branch `docs/NAME` |
| `git style NAME` | Create branch `style/NAME` |
| `git refactor NAME` | Create branch `refactor/NAME` |
| `git chore NAME` | Create branch `chore/NAME` |
| `git perf NAME` | Create branch `perf/NAME` |
| `git test NAME` | Create branch `test/NAME` |
| `git build NAME` | Create branch `build/NAME` |
## Commit Message Format
The tool follows the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification:
```
[optional scope]:
[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.
```ini
[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
| Key | Description | Default |
|-----|-------------|---------|
| `llm-api-key` | API key for cloud LLM providers | - |
| `llm-api-host` | LLM API endpoint | see below |
| `llm-api-path` | API path (auto-detected for known providers) | see below |
| `llm-model` | LLM model name | see below |
| `llm-temperature` | Model temperature | `0.3` |
| `llm-diff-context` | Diff context lines | `5` |
| `llm-request-timeout` | Request timeout (Go duration, e.g., `2m`, `30s`) | `2m` |
| `llm-max-retries` | Max retry count on failure | `0` |
| `llm-output-lang` | Output language (`en`, `zh`, `bilingual`) | `en` |
| `llm-max-concurrency` | Max parallel file analysis | `3` |
| `llm-max-diff-lines` | Max diff lines to analyze | `500` |
| `llm-api-debug` | Enable debug logging to temp file | `false` |
| `llm-file-analysis-prompt` | Custom file analysis prompt | - |
| `llm-commit-prompt-en` | Custom English commit prompt | - |
| `llm-commit-prompt-zh` | Custom Chinese commit prompt | - |
| `llm-commit-prompt-bilingual` | Custom bilingual commit prompt | - |
| `lucky-commit-prefix` | Lucky commit hex prefix (max 12 chars) | - |
| `ssh-strict-host-key` | SSH strict host key checking | `false` |
| `branch-auto-detect` | Auto-detect commit type from branch name | `false` |
| `require-scope` | Require scope field | `false` |
| `require-body` | Require body field | `false` |
| `require-footer` | Require footer field | `false` |
### 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:**
| Provider | When | Default Path | Default Model |
|----------|------|--------------|---------------|
| OpenRouter | API key set, no custom host | `/api/v1/chat/completions` | `mistralai/devstral-2512:free` |
| Groq | Host contains `groq.com` | `/openai/v1/chat/completions` | - |
| Ollama | No API key | `/api/chat` | `deepseek-coder-v2:16b` |
| OpenAI-compatible | Other hosts (openai.com, deepseek.com, mistral.ai, etc.) | `/v1/chat/completions` | - |
**Custom API Path:**
If your provider uses a non-standard path, set it explicitly:
```bash
git config --global gitflow.llm-api-path "/custom/v1/chat/completions"
```
**Quick Start with OpenRouter (recommended):**
```bash
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:**
```bash
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](https://github.com/not-an-aardvark/lucky-commit):
```bash
# 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:
```bash
# 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:**
| Branch Prefix | Commit Type |
|---------------|-------------|
| `feat`, `feature` | feat |
| `fix`, `bugfix`, `bug` | fix |
| `docs`, `doc`, `document` | docs |
| `style` | style |
| `refactor`, `refact` | refactor |
| `test`, `testing` | test |
| `chore` | chore |
| `perf`, `performance` | perf |
| `hotfix` | hotfix |
| `build` | build |
Supports separators: `/`, `-`, `_` (e.g., `feat/login`, `fix-bug-123`, `docs_readme`)
## Uninstall
### Homebrew
```bash
brew uninstall gitflow-toolkit
brew untap mritd/gitflow-toolkit
```
### Manual
```bash
sudo gitflow-toolkit uninstall
```
## License
MIT