ggc

A Go Git CLI.

<img src="./docs/icon.png" alt="ggc" title="ggc" width="100px">

This logo was created by gopherize.me.

Demo

| Branch Management | CLI Workflow | Interactive Overview | | --- | --- | --- | | <img src="docs/demos/generated/branch-management.gif" alt="Branch management demo" width="320"> | <img src="docs/demos/generated/cli-workflow.gif" alt="CLI workflow demo" width="320"> | <img src="docs/demos/generated/interactive-overview.gif" alt="Interactive overview demo" width="320"> |

Overview

ggc is a Git tool written in Go, offering both traditional CLI commands and an interactive interface with incremental search. You can either run subcommands like ggc add directly, or launch the interactive mode by simply typing ggc. Designed to be fast, user-friendly, and extensible.

Features

• Traditional command-line interface (CLI): Run ggc <command> [args] to execute specific operations directly.
• Interactive interface: Run ggc with no arguments to launch an incremental search UI for command selection.
• Workflow functionality: Build and execute multi-command workflows in interactive mode (e.g., add → commit → push)
• Simple commands for common Git operations (add, push, pull, branch, log, etc.)
• Composite commands that combine multiple Git operations
• Interactive UI for branch/file selection and message input
• Customizable keybindings with profile support (default, emacs, vi, readline)
• Unified, flagless command syntax for intuitive usage
• Shell completion for Bash, Zsh, and Fish
• Configurable via YAML configuration file
• Built with Go standard library and minimal dependencies

Supported Environments

Supported Platforms

• macOS (Apple Silicon/Intel): darwin_amd64, darwin_arm64 - Verified
• Linux (ARM64/x86_64): linux_amd64, linux_arm64 - Supported
• Windows (x86_64): windows_amd64 - Supported

Requirements

• Go version: 1.25 or later recommended
• git command must be installed

Installation

Pre-compiled Binaries (Recommended)

Pre-compiled binaries are available for multiple platforms and architectures. This is the fastest way to get started with ggc.

Download from Releases

1. Visit the Releases page to download the latest binary for your platform
2. Make the binary executable: chmod +x ggc
3. Move it to a directory in your PATH: sudo mv ggc /usr/local/bin/ (or another location in your PATH)
4. Verify installation: ggc version

Homebrew

Install via Homebrew:

brew install ggc
# Upgrade later:
# brew upgrade ggc
# Verify:
# ggc version

• Formula: https://formulae.brew.sh/formula/ggc
• Supported platforms via Homebrew: macOS (Apple Silicon/Intel), Linux (ARM64/x86_64)

Quick Install with Script

The easiest way to install ggc is using the provided installation script:

# Download and run the installation script
curl -sSL https://raw.githubusercontent.com/bmf-san/ggc/main/install.sh | bash

Or download and run it manually:

# Download the script
curl -O https://raw.githubusercontent.com/bmf-san/ggc/main/install.sh

# Make it executable
chmod +x install.sh

# Run the script
./install.sh

The script will:

• Detect your operating system and architecture
• Download the appropriate binary for your system
• Install using git, manual go install fallback
• Verify the installation

Build with make

# Clone the repository by SSH
git clone git@github.com:bmf-san/ggc.git
cd ggc

# Build the binary
make build

# Move the binary to a directory in your PATH
sudo mv ggc /usr/local/bin/

Development Setup

Prerequisites for development

• Go 1.25 or later
• Git

For development, you can use the Makefile to install required tools and dependencies:

# Install all dependencies and tools
make deps

# Run formatter
make fmt

# Run tests
make test

# Run linter
make lint

# Run tests with coverage
make cover

# Run tests and lint
make test-and-lint

# Build with go build
make build

# Build and run with version info
make run

The Makefile will automatically install required tools like golangci-lint using go install.

Global install with go install

# Requires Go 1.25+ installed
go install github.com/bmf-san/ggc/v8@latest

• The ggc binary will be installed to $GOBIN (usually $HOME/go/bin).
• If $GOBIN is in your PATH, you can use ggc from anywhere.
• If not, add it to your PATH:

[!NOTE] When using go install, you may get limited version info due to ldflags not working with go install. It is recommended to build with make build or use the install script or binaries.

export PATH=$PATH:$(go env GOBIN)
# or
export PATH=$PATH:$HOME/go/bin

Usage

Interactive Command Selection (Fuzzy Search UI)

Just run:

ggc

Search Features:

• Fuzzy matching: Type any characters that appear in the command (e.g., "bd" matches "branch delete", "ca" matches "commit amend")
• Case-insensitive: Search works regardless of case
• Real-time filtering: Results update as you type

Navigation & Editing:

• Ctrl+n / Ctrl+p: Navigate up/down through results
• ← / →: Move cursor left/right
• Ctrl+← / Ctrl+→: Move by word
• Option+← / Option+→ (macOS): Move by word
• Ctrl+a / Ctrl+e: Move cursor to beginning/end of input
• Ctrl+u: Clear all input
• Ctrl+w: Delete word before cursor
• Option+Backspace (macOS): Delete word before cursor
• Ctrl+k: Delete from cursor to end of line
• Backspace: Delete character before cursor
• Enter: Execute selected command
• Ctrl+c: Exit interactive mode

Workflow Operations (Search Mode):

• Tab: Add selected command to the active workflow
• Ctrl+t: Switch to Workflow Mode

Workflow Mode Keys:

• n: Create a new workflow
• d / Ctrl+d: Delete the active workflow
• x: Execute the active workflow
• Ctrl+n/p: Navigate workflows
• Ctrl+t: Return to Search Mode
• Ctrl+c: Exit interactive mode

Command Execution:

• If a command requires arguments (e.g. <file>, <name>, <url>), you will be prompted for input
• After command execution, results are displayed and you can press Enter to continue
• After viewing results, you return to the command selection screen for continuous use
• Type "quit" or use Ctrl+c to exit interactive mode
• All UI and prompts are in English

Workflow Feature:

• Build multi-command workflows by adding commands with Tab
• Manage and execute workflows in a dedicated Workflow Mode
• Create, delete, and cycle through multiple workflows
• Commands are executed sequentially when you run the active workflow
• Placeholder arguments (e.g., <message>) are prompted during workflow execution
• Workflows persist after execution for reuse
• Common workflow examples: add → commit → push, fetch → rebase → push force

Examples of Fuzzy Search:

• "bd" → finds "branch delete"
• "ca" → finds "commit amend"
• "ai" → finds "add interactive"
• "ss" → finds "status short"
• "brdel" → finds "branch delete"

Available Commands

| Command | Description | |--------|-------------| | add . | Add all changes to the index | | add <file> | Add a specific file to the index | | add interactive | Add changes interactively | | add patch | Add changes interactively (patch mode) | | help | Show main help message | | help <command> | Show help for a specific command | | reset | Hard reset to origin/<branch> and clean working directory | | reset hard <commit> | Hard reset to specified commit | | reset soft <commit> | Soft reset: move HEAD but keep changes staged | | branch checkout | Switch to an existing branch | | branch checkout remote | Create and checkout a local branch from the remote | | branch contains <commit> | Show branches containing a commit | | branch create | Create and checkout a new branch | | branch current | Show current branch name | | branch delete | Delete local branch | | branch delete merged | Delete local merged branch | | branch info <branch> | Show detailed branch information | | branch list local | List local branches | | branch list remote | List remote branches | | branch list verbose | Show detailed branch listing | | branch move <branch> <commit> | Move branch to specified commit | | branch rename <old> <new> | Rename a branch | | branch set upstream <branch> <upstream> | Set upstream for a branch | | branch sort [date|name] | List branches sorted by date or name | | commit <message> | Create commit wi