gitch

README

gitch

Never commit with the wrong git identity again.

A beautiful CLI for managing multiple git identities with SSH keys, GPG signing, auto-switching rules, and shell prompt integration.

Installation · Quick Start · Features · Commands · Contributing

---

The Problem

You work on multiple projects:

• Work — commits should use you@company.com
• Personal — commits should use you@gmail.com
• Open Source — commits should use you@users.noreply.github.com

You accidentally commit with the wrong email. Your work repo now has personal commits. Your contribution graph is broken. Sound familiar?

The Solution

gitch manages your git identities so you don't have to think about it.

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   $ gitch use                                               │
│                                                             │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  Select an identity                                 │   │
│   │                                                     │   │
│   │  > 🏢 work                                          │   │
│   │      you@company.com                                │   │
│   │                                                     │   │
│   │    🏠 personal                                      │   │
│   │      you@gmail.com                                  │   │
│   │                                                     │   │
│   │    🌐 opensource                                    │   │
│   │      you@users.noreply.github.com                   │   │
│   └─────────────────────────────────────────────────────┘   │
│                                                             │
│   ✓ Switched to "work" identity                             │
│   ✓ SSH key loaded into agent                               │
│   ✓ GPG signing configured                                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

✨ Features

🎭 Identity Management Create, switch, and manage multiple git identities. Each identity stores name, email, and optional SSH key. 🔐 SSH Key Integration Generate new SSH keys per identity or link existing ones. Keys auto-load into ssh-agent on switch. ✍️ GPG Commit Signing Generate GPG keys or link existing ones. Git commit signing auto-configures on identity switch. 🎨 Beautiful TUI Interactive setup wizard and identity selector built with Bubble Tea. Terminal UI that sparks joy.

⚡ Auto-Switching Rules Define directory or remote-based rules. Enter ~/work/** → automatically switch to work identity. 🛡️ Pre-Commit Protection Install hooks that prevent wrong-identity commits. Configure per-identity: warn, block, or allow. 🐚 Shell Prompt Integration See your current identity in your prompt. Ultra-fast (<5ms) cache-based updates for Bash, Zsh, and Fish.

🐚 Shell Completions First-class tab completion for Bash, Zsh, and Fish. Never type a full command again.

🔒 Secure by Default SSH keys stored in ~/.ssh/ with proper permissions. GPG keys in system keyring. No credentials in plain text.

📦 Installation

Homebrew (macOS)

brew install orzazade/tap/gitch

Using Go

go install github.com/orzazade/gitch@latest

From Source

git clone https://github.com/orzazade/gitch.git
cd gitch
make build

🚀 Quick Start

Option 1: Interactive Setup (Recommended)

gitch setup

This launches a beautiful wizard that guides you through creating your first identity.

Option 2: Manual Setup

# Create your first identity with a new SSH key
gitch add --name "work" --email "you@company.com" --generate-ssh

# Create another with an existing SSH key
gitch add --name "personal" --email "you@gmail.com" --ssh-key ~/.ssh/id_personal

# Create identity with GPG signing enabled
gitch add --name "opensource" --email "you@github.com" --generate-gpg

# Or use an existing GPG key
gitch add --name "secure" --email "you@secure.com" --gpg-key ABCD1234EFGH5678

# Switch between them
gitch use work

# Or use the interactive selector
gitch use

📖 Commands

Core Commands

Command	Description
gitch setup	🧙 Interactive setup wizard
gitch add	➕ Create a new identity (with --generate-ssh, --generate-gpg options)
gitch list	📋 List all identities
gitch status	👁️ Show current active identity (-v for rule details)
gitch use [name]	🔀 Switch to an identity (interactive if no name)
gitch delete <name>	🗑️ Delete an identity

Auto-Switching & Hooks

Command	Description
gitch rule add <pattern> --use <identity>	📍 Add directory rule (e.g., ~/work/**)
gitch rule add --remote <pattern> --use <identity>	🌐 Add remote rule (e.g., github.com/company/*)
gitch rule list	📋 List all switching rules
gitch rule remove <pattern>	🗑️ Remove a rule
gitch hook install	🛡️ Install pre-commit hook globally
gitch hook uninstall	❌ Remove pre-commit hook
gitch config hook-mode <identity> <mode>	⚙️ Set hook behavior (warn/block/allow)

Shell Integration

Command	Description
gitch init <shell>	🐚 Output shell prompt integration code (bash/zsh/fish)
gitch completion <shell>	📝 Generate shell completions

📍 Auto-Switching Rules

Set up rules to automatically switch identities based on directory or remote:

# Switch to "work" when in any subdirectory of ~/work
gitch rule add ~/work/** --use work

# Switch to "opensource" for any github.com/orzazade/* repo
gitch rule add --remote "github.com/orzazade/*" --use opensource

# View all rules
gitch rule list

# Remove a rule
gitch rule remove ~/work/**

🛡️ Pre-Commit Hooks

Prevent accidental commits with the wrong identity:

# Install the pre-commit hook globally
gitch hook install

# When you commit with wrong identity, you'll see:
#   ⚠ Identity mismatch: expected "work", but current is "personal"
#   [S]witch to work / [C]ontinue anyway / [A]bort

# Configure per-identity behavior
gitch config hook-mode work block    # Always block wrong identity
gitch config hook-mode personal warn # Just warn (default)
gitch config hook-mode oss allow     # No checks for this identity

# Bypass when needed
GITCH_BYPASS=1 git commit -m "emergency fix"

🐚 Shell Prompt Integration

See your current git identity right in your prompt:

# Add to your shell config:
eval "$(gitch init zsh)"   # For Zsh (~/.zshrc)
eval "$(gitch init bash)"  # For Bash (~/.bashrc)
source (gitch init fish)   # For Fish (~/.config/fish/config.fish)

# Your prompt will show:
# [work] ~/projects/company $

📝 Shell Completions

Enable tab completion for your shell:

Bash

# Add to ~/.bashrc
source <(gitch completion bash)

Zsh

# Add to ~/.zshrc (before compinit)
source <(gitch completion zsh)

Fish

gitch completion fish > ~/.config/fish/completions/gitch.fish

⚙️ Configuration

gitch stores configuration in the XDG config directory:

Platform	Location
Linux/macOS	~/.config/gitch/config.yaml
Windows	%APPDATA%\gitch\config.yaml

SSH keys are stored in ~/.ssh/ with the naming convention gitch_<identity-name>.

GPG keys are generated and imported into your system GPG keyring (~/.gnupg/).

🗺️ Roadmap

v1.x - Core Features (Complete)

Phase	Features
✅ Foundation	Core identity management (add, list, status, use, delete)
✅ SSH Integration	SSH key generation and ssh-agent integration
✅ TUI Experience	Interactive setup wizard, identity selector, shell completions
✅ Auto-Switching	Directory/remote rules, pre-commit hooks, bypass support
✅ Shell Prompt	Fast prompt integration for Bash, Zsh, and Fish
✅ Distribution	Homebrew tap for easy macOS installation
✅ GPG Signing	GPG key generation, linking, and auto-configure on switch

v2.0 - Security & Distribution (In Progress)

Phase	Features
🚧 Import/Export	YAML export/import for identity backup and migration
🚧 SSH Config	Auto-generate SSH config Host aliases per identity
🚧 Encrypted Backup	Age-encrypted SSH key export/import
🚧 Cross-Platform	Windows (Scoop, Chocolatey, winget) and Linux (APT)

🤝 Contributing

Contributions are welcome! Whether it's bug reports, feature requests, or pull requests.

• 🐛 Report bugs
• 💡 Request features
• 🔧 Submit PRs

Please read CONTRIBUTING.md for guidelines.

🏗️ Built With

📄 License

MIT License - see LICENSE for details.

---

Stop context-switching. Start committing with confidence.

Made with ❤️ by Orkhan Rzazade

⭐ Star this repo · 🐛 Report Bug · 💡 Request Feature