katzu-git (kg)

katzu's Lazy git — A minimal, ergonomic CLI wrapper for everyday Git workflows.

Originally written as a shell script in katzu-git-cli, katzu-git is rewritten in TypeScript for Bun and Node.js.

Features

• Terminal UI (kg ui or kg): Interactive terminal dashboard for repository status, staging, committing, log inspection, and submodule management.
• Quick Add (kg a): Fast staging for single files or all changes.
• Conventional Commits (kg c): Formats commits automatically with type, scope, and subject.
• Push (kg p): Transparent pass-through for git push with flag forwarding.
• Status Helper (kg s): Formatted repository status dashboard with upstream tracking, change breakdown, and interactive staging.
• Log Helper (kg l): Pretty formatted commit timeline with conventional commit color coding, graph view, and interactive commit inspector.
• Submodule Manager (kg sm): Interactive and CLI management for adding, editing (URL, branch, path), deleting, and syncing submodules.
• Interactive Update (kg update): Inquirer-based prompt to update dependencies.
• Standalone Binaries: Cross-compile to single-file executables for Windows, Linux, and macOS with zero runtime dependencies.
• Modular Command Architecture: Clean TypeScript structure using yargs command modules and chalk styling.

Installation

Homebrew (macOS & Linux)

Install via the katzEco tap:

# Tap the repository
brew tap katzEco/repo

# Install katzu-git
brew install katzu-git

Or install directly in one step:

brew install katzEco/repo/katzu-git

Both kg and katzu-git commands will be available in your PATH.

From Source

Prerequisites

• Bun (recommended) or Node.js (v22+)
• Git

Clone & Install

git clone https://github.com/katzEco/katzu-git.git
cd katzu-git
bun install

Link CLI Locally

To use kg globally from your terminal:

bun link

(or with npm: npm link)

Usage

katzu's Lazy git (kg v2.0.0)

Usage:
  kg <command> [options]

Commands:
  a, add <files..>                  Stage files for commit (default: .)
  c, commit <type> <scope> <msg..>  Create a conventional commit
  p, push [remote] [branch]         Push commits to remote
  s, st, status [args..]            Show repository status and branch info
  l, log [args..]                   View commit history with pretty formatting
  sm, sub, submodule [action] [args..]  Manage git submodules (add, edit, delete)
  ui, tui, menu                     Launch interactive terminal UI dashboard
  update                            Update package dependencies
  h, help                           Show this help message

Examples:
  $ kg a .
  $ kg c feat auth add login flow
  $ kg c fix no resolve crash
  $ kg p origin main
  $ kg s
  $ kg s -i
  $ kg l
  $ kg l -n 5
  $ kg l -i
  $ kg sm
  $ kg sm add https://github.com/foo/bar.git libs/bar
  $ kg sm edit libs/bar
  $ kg sm delete libs/bar

1. Add Files

# Stage all files
kg a .

# Stage specific files
kg a src/index.ts package.json

2. Commit Changes

Format: kg c [type] [scope] [subject]

# Commit with scope: feat<auth>: add login endpoint
kg c feat auth add login endpoint

# Commit without scope (use 'no' or 'idk'): feat: initial commit
kg c feat no initial commit
kg c chore idk update dependencies

3. Push to Remote

# Default push
kg p

# Push with remote and branch
kg p origin main

# Flags pass directly through to git
kg p --force-with-lease

4. Status Helper

Aliases: kg s, kg st, kg status

Displays a clean, colored status dashboard showing branch upstream tracking, staged files, unstaged changes, and untracked files with helpful shortcuts.

# Default status dashboard
kg s

# Interactive file staging (select files to stage via checkbox)
kg s -i

# Standard git status pass-through (e.g. short, branch, ignored)
kg s -s
kg s -b
kg s --raw

5. Log Helper

Aliases: kg l, kg log

View commit history with semantic conventional commit highlighting, relative dates, and author information.

# Default log (recent 10 commits)
kg l

# Limit commit count
kg l -n 5

# Interactive commit explorer (inspect commits, diffs, checkout)
kg l -i

# ASCII history graph
kg l --graph
kg l -g

# View diffstat summary for each commit
kg l --stat

# Filter by author or commit message pattern
kg l --author="George"
kg l --grep="feat"

6. Submodule Manager

Aliases: kg sm, kg sub, kg submodule

Interactive Mode

Launch the interactive submodule manager by running:

kg sm

Offers a visual menu to:

• ➕ Add submodule: Prompts for repo URL, destination path, and optional tracking branch.
• ✏️ Edit submodule: Pick a submodule to change its URL, tracking branch, rename/move its path, or sync with remote.
• 🗑️ Delete submodule: Select a submodule to de-initialize and safely remove its tree and Git cache.
• 📋 List submodules: Display configured submodules with URLs, branches, commit hashes, and sync statuses.
• 🔄 Sync & update: Synchronize and update all submodules recursively.

Command-Line Operations

# Add a submodule
kg sm add https://github.com/org/repo.git libs/repo
kg sm add https://github.com/org/repo.git libs/repo -b main

# Edit a submodule (or omit flags for interactive edit menu)
kg sm edit libs/repo --url https://github.com/org/new-repo.git
kg sm edit libs/repo --branch develop
kg sm edit libs/repo

# Delete a submodule
kg sm delete libs/repo
kg sm delete libs/repo -y     # skip confirmation prompt

# List all submodules
kg sm list

# Sync and update submodules
kg sm sync
kg sm sync libs/repo

7. Update Package

kg update

Prompts for confirmation and updates via your package manager.

8. Terminal UI

Aliases: kg ui, kg tui, kg menu, or run kg directly without arguments in an interactive terminal.

# Launch interactive terminal UI
kg
# or
kg ui

Provides a unified interactive dashboard to:

• Inspect repository branch, upstream sync, and status breakdown.
• Stage specific files interactively or stage all files.
• Build and commit conventional commits interactively.
• Push commits to remote.
• Explore commit history and inspect diffs.
• Manage submodules.

Development

# Run with Bun in watch mode
bun run dev

# Run CLI directly
bun run start -- help

# Type-check
bunx tsc --noEmit

Building Executables

Compile standalone cross-platform binaries into dist/ with zero runtime dependencies:

# Interactive platform selection (all checked by default)
bun run build

# Build all targets without prompt (-a or --all)
bun run build --all
bun run build -a

# Show build script options
bun run build --help

Supported Targets

| Platform | Target ID | Output Binary | | :--- | :--- | :--- | | Windows x64 | win64 | dist/kg-v<version>-win64.exe | | Windows ARM64 | win-arm | dist/kg-v<version>-win-arm.exe | | Linux x64 | linux-x64 | dist/kg-v<version>-linux-x64 | | Linux ARM64 | linux-arm | dist/kg-v<version>-linux-arm | | macOS Apple Silicon | mac-arm | dist/kg-v<version>-mac-arm | | macOS Intel | mac-x64 | dist/kg-v<version>-mac-x64 |

[!NOTE] 32-bit Windows (win32) is unsupported by the Bun runtime compiler (only 64-bit and ARM64 platforms are supported).

Running Compiled Binaries

Once compiled, executables run standalone without Bun or Node installed:

# Run locally (replace with your version and platform)
./dist/kg-v1.0.7-linux-x64 --help

# Optional: Install to system PATH (Linux/macOS)
sudo cp dist/kg-v1.0.7-linux-x64 /usr/local/bin/kg

License

MIT