Gitch is a Git identity management tool designed to simplify the handling of multiple email addresses, names, SSH keys, and GPG signing keys. It streamlines switching between identities, ensuring developers maintain consistency across projects.
Key Features:
Instantly switch between predefined identities with ease.
Automatically adjust identities based on repository rules or directory paths.
Manage SSH keys per identity for secure access to different platforms.
Support for GPG key management to ensure proper commit signing.
Integrate seamlessly with shell prompts for real-time identity visibility.
Audience & Benefit:
Ideal for developers juggling multiple projects across various organizations, Gitch prevents accidental commits with incorrect identities. This maintains the integrity of contribution graphs and preserves professional reputation.
Gitch can be installed via winget, offering a straightforward setup process. Its intuitive design and robust features make it an essential tool for managing Git identities efficiently.
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.
Git has includeIf for conditional configs. Tools like direnv exist. Why gitch?
Feature
gitch
git includeIf
direnv
Auto-switch by directory
✅
✅
✅
Auto-switch by remote URL
✅
❌
❌
SSH key management
✅
❌
❌
Auto-load SSH keys to agent
✅
❌
❌
GPG key management
✅
❌
❌
Pre-commit identity check
✅
❌
❌
Interactive TUI
✅
❌
❌
VS Code integration
✅
❌
❌
Shell prompt integration
✅
❌
✅
Commit history audit
✅
❌
❌
Zero config after setup
✅
⚠️
⚠️
✨ 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. Choose key type (Ed25519 or RSA) with smart defaults for Azure DevOps.
✍️ 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.
💻 VS Code Extension
See your current identity in the status bar. Click to switch identities instantly. Auto-switch when opening workspaces.
🔍 Commit History Audit
Scan your repo for commits made with the wrong identity. See which commits are local-only vs already pushed.
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
# For Azure DevOps, use RSA key type (auto-detected in repos)
gitch add --name "azure" --email "you@company.com" --generate-ssh --key-type rsa
# 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)
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_.
GPG keys are generated and imported into your system GPG keyring (~/.gnupg/).
