Guide

Getting Started

Gitbun is an open-source AI CLI tool that streamlines your git workflow by generating intelligent commit messages instantly.

Introduction

Gitbun generates intelligent commit messages from staged diffs using AI or heuristics. It analyzes your code changes to understand the intent and scope, ensuring your commit history remains clean, professional, and descriptive without the manual effort.

Installation

Install Gitbun globally using your favorite package manager to access it from any repository.

GLOBAL INSTALL

# install via npm
npm install -g gitbun

Quick Start

Stage changes

Add files to your git staging area.

git add .

Run Gitbun

Generate a message based on staged diff.

gitbun

Commit

Apply the generated message.

git commit -m "..."

Basic Commands

Gitbun provides a simple set of commands to manage your commit workflow.

gitbun # Generate message for current staged diff
gitbun --amend # Regenerate and replace last commit message
gitbun --config # Interactive configuration menu
gitbun --version # Show current version

CLI Flags

Flag	Description
--ai	Force use of AI models (Default)
--no-ai	Use local heuristic summarizers (Offline)
--interactive, -i	Choose from multiple generated suggestions
--prompt	Provide custom instructions for the AI
--help, -h	Show help information

Configuration

Configure Gitbun globally via ~/.gitbunrc or per-project via .gitbunrc.

{
  "useAI": true,
  "backend": "local",
  "model": "llama3",
  "conventional": true
}

Environment Variables

# For remote backends (OpenAI)
export OPENAI_API_KEY="sk-..."

AI Backends

terminalLocal (Ollama)

Ideal for privacy. Run Llama 3 or Mistral on your personal hardware with zero latency and cost.

cloudRemote APIs

Connect to GPT-4o or Claude for complex diff reasoning and higher quality suggestions.

Core Features

psychology

AI Generation

Summarize thousands of lines of code changes into concise, accurate commit headers and bodies.

offline_bolt

Heuristic Mode

No internet? No problem. Rule-based local summarizers work instantly without APIs.

history

Amend Helper

Forgot a detail? Regenerate your last commit message instantly with --amend.

format_list_bulleted

Conventional Commits

Automatic categorization into 'feat', 'fix', 'refactor', and more based on code intent.

Contributing

We welcome contributions! Gitbun is built with Node.js and TypeScript. Follow our standard workflow to get started:

Fork the repo: Create your own copy of the repository.
Branch: Create a feature branch (feat/my-feature).
Code: Implement your changes and ensure they follow our linting rules.
PR: Submit a pull request with a detailed summary of changes.

Testing

Gitbun uses Vitest for unit and integration testing. Always run tests before submitting a PR.

# Run all tests
npm test
# Run in watch mode
npm run test:watch

CI/CD Workflow

GitHub Actions

Automated test suites runner on every push and PR across multiple environments.

Semantic Release

Automated versioning and npm package publishing based on commit messages.

Husky

Pre-commit hooks to ensure code is linted and tested before it leaves your machine.

CLI Reference

Detailed reference for individual CLI command behaviors.

gitbun [options]

Analyzes the output of git diff --cached to generate a commit message. If no changes are staged, it will prompt you to stage them.

Exit Codes

Operation successful.

General CLI error or crash.

API failure (Network or Auth).

130

Process cancelled by user (Ctrl+C).