gh-switch - GitHub Account Switcher 🔄

A fast, reliable command-line tool for managing multiple GitHub accounts. Switch between personal, work, and other GitHub identities seamlessly without manual SSH or Git config editing.

✨ Features

• Instant Switching: Change GitHub accounts with a single command
• SSH Key Management: Automatically configures SSH hosts for each profile
• Git Config Integration: Updates user.name and user.email per repository
• Profile Storage: Securely stores multiple account profiles
• Auto-Detection: Automatically detects and switches profiles based on repository
• Remote URL Updates: Automatically updates git remote URLs when switching
• No Dependencies: Pure shell script - works everywhere
• Backup Safety: Automatically backs up SSH config before modifications

🚀 Quick Start

Installation

Method 1: Direct Installation (Recommended)

# Download and install
curl -sSL https://raw.githubusercontent.com/TheDevOpsBlueprint/gh-switch/main/bin/gh-switch-standalone -o /tmp/gh-switch
chmod +x /tmp/gh-switch
sudo mv /tmp/gh-switch /usr/local/bin/gh-switch

# Verify installation
gh-switch --version

Method 2: From Source

# Clone the repository
git clone https://github.com/TheDevOpsBlueprint/gh-switch.git
cd gh-switch

# Install
chmod +x bin/gh-switch-standalone
sudo cp bin/gh-switch-standalone /usr/local/bin/gh-switch

# Verify
gh-switch --version

Method 3: Using Make

# Clone and install
git clone https://github.com/TheDevOpsBlueprint/gh-switch.git
cd gh-switch
make install

Initial Setup

# Initialize gh-switch
gh-switch init

# Add your first profile (personal)
gh-switch add personal

# Add a work profile
gh-switch add work

📖 Usage Guide

Managing Profiles

Adding a Profile

# Add a new profile interactively
gh-switch add personal

# You'll be prompted for:
# - SSH key path: ~/.ssh/id_ed25519_personal
# - Git name: John Doe
# - Git email: john@personal.com
# - GitHub username: johndoe

Listing Profiles

# Show all profiles
gh-switch list

# Output:
# Available profiles:
# ==================
# * personal (active)
#     User: John Doe
#     Email: john@personal.com
#   
#   work
#     User: John Smith
#     Email: john.smith@company.com

Switching Profiles

# Switch profile for current repository
gh-switch use work

# Switch globally (all new repos)
gh-switch use personal --global

# Check current profile
gh-switch current

Working with Repositories

Cloning with Specific Profile

# Use personal profile for personal projects
gh-switch use personal
git clone git@github.com-personal:johndoe/my-project.git

# Use work profile for work projects
gh-switch use work
git clone git@github.com-work:company/work-project.git

Converting Existing Repository

# Go to existing repo
cd ~/projects/my-repo

# Switch to desired profile
gh-switch use personal

# The remote URL is automatically updated
git remote -v
# origin  git@github.com-personal:johndoe/my-repo.git

Auto-Detection

# Automatically detect profile from remote URL
cd ~/projects/some-repo
gh-switch auto
# Detects and switches to the appropriate profile

Advanced Usage

Profile Management

# Delete a profile
gh-switch delete old-profile

# Edit profile (delete and re-add)
gh-switch delete work
gh-switch add work

SSH Key Testing

# Test personal account SSH connection
ssh -T git@github.com-personal
# Hi johndoe! You've successfully authenticated...

# Test work account SSH connection
ssh -T git@github.com-work
# Hi john-work! You've successfully authenticated...

📁 Configuration

File Locations

~/.config/gh-switch/
├── config              # Main configuration
├── current             # Currently active profile
└── profiles/           # Profile storage
    ├── personal        # Personal profile config
    └── work           # Work profile config

SSH Config Structure

gh-switch adds entries to ~/.ssh/config:

# GitHub account: personal
Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
  IdentitiesOnly yes

# GitHub account: work
Host github.com-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

Profile Structure

Each profile stores:

• SSH key path
• Git user name
• Git email address
• GitHub username
• SSH host alias

🎨 Command Reference

Command	Description	Example
init	Initialize gh-switch	gh-switch init
add	Add a new profile	gh-switch add personal
use	Switch to a profile	gh-switch use work
current	Show active profile	gh-switch current
list	List all profiles	gh-switch list
delete	Remove a profile	gh-switch delete old
auto	Auto-detect profile	gh-switch auto
help	Show help message	gh-switch help

Command Options

• --global - Apply profile globally (with use command)
• --version / -v - Show version information

🔧 Shell Aliases

Add to your ~/.bashrc or ~/.zshrc for quicker access:

# Quick aliases
alias ghs='gh-switch'
alias ghsp='gh-switch use personal'
alias ghsw='gh-switch use work'
alias ghsl='gh-switch list'
alias ghsc='gh-switch current'

# Function to clone with profile
ghclone() {
  local profile=$1
  local repo=$2
  gh-switch use $profile
  git clone $repo
}

# Usage: ghclone personal git@github.com-personal:user/repo.git

📋 Prerequisites

• Git: Version 2.0 or higher
• OpenSSH: Standard SSH client
• Bash: Version 4.0+ (macOS/Linux)
• GitHub Account: With SSH keys configured

Setting Up SSH Keys

Before using gh-switch, ensure you have SSH keys for each GitHub account:

# Generate key for personal account
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_personal -C "personal@email.com"

# Generate key for work account
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_work -C "work@company.com"

# Add keys to SSH agent
ssh-add ~/.ssh/id_ed25519_personal
ssh-add ~/.ssh/id_ed25519_work

Then add each public key to the corresponding GitHub account's settings.

🧪 Typical Workflows

Daily Development

# Morning - work on company project
cd ~/work/company-api
gh-switch use work
git pull origin main
# ... do work, commits use work identity

# Afternoon - personal project
cd ~/personal/side-project
gh-switch use personal
git pull origin main
# ... commits use personal identity

# Check active profile anytime
gh-switch current

New Project Setup

# Personal project
gh-switch use personal
mkdir ~/projects/new-app
cd ~/projects/new-app
git init
git remote add origin git@github.com-personal:johndoe/new-app.git

# Work project
gh-switch use work
mkdir ~/work/new-service
cd ~/work/new-service
git init
git remote add origin git@github.com-work:company/new-service.git

Migrating Existing Repositories

# List current remotes
cd ~/projects/existing-repo
git remote -v
# origin git@github.com:johndoe/existing-repo.git

# Switch to profile
gh-switch use personal

# Remote is automatically updated
git remote -v
# origin git@github.com-personal:johndoe/existing-repo.git

🐛 Troubleshooting

Common Issues

Issue: "command not found"

# Check installation
which gh-switch

# Ensure /usr/local/bin is in PATH
echo $PATH

# Reinstall if needed
sudo cp bin/gh-switch-standalone /usr/local/bin/gh-switch

Issue: "Permission denied (publickey)"

# Check SSH key is loaded
ssh-add -l

# Add key to agent
ssh-add ~/.ssh/your_key

# Test connection
ssh -T git@github.com-personal

Issue: "Not in a git repository"

# For local repository changes
cd your-git-repo
gh-switch use profile-name

# For global changes
gh-switch use profile-name --global

Issue: SSH config already has entries

# Backup is created automatically
ls ~/.ssh/config.gh-switch.backup

# Manually restore if needed
cp ~/.ssh/config.gh-switch.backup ~/.ssh/config

Debug Commands

# Check profile details
cat ~/.config/gh-switch/profiles/personal

# View current profile
cat ~/.config/gh-switch/current

# Check SSH config entries
grep "github.com-" ~/.ssh/config

# Test SSH authentication
ssh -vT git@github.com-personal  # Verbose output

🤝 Contributing

We follow a small PR philosophy - each PR should be 40-80 lines max:

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Keep changes focused and minimal
4. Test thoroughly on macOS and Linux
5. Submit a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📄 Project Structure

gh-switch/
├── bin/
│   ├── gh-switch              # Main script (development)
│   └── gh-switch-standalone   # Standalone version
├── lib/
│   ├── common.sh              # Common utilities
│   ├── profile.sh             # Profile management
│   ├── ssh_parser.sh          # SSH config parsing
│   ├── ssh_writer.sh          # SSH config writing
│   ├── git_config.sh          # Git configuration
│   └── cmd_*.sh               # Command implementations
├── completions/
│   ├── gh-switch.bash         # Bash completion
│   └── gh-switch.zsh          # Zsh completion
├── tests/
│   └── test_basic.sh          # Test suite
├── install.sh                 # Installation script
├── Makefile                   # Make targets
└── README.md                  # This file

🚀 Uninstallation

# Remove the binary
sudo rm /usr/local/bin/gh-switch

# Remove configuration (optional - preserves profiles)
rm -rf ~/.config/gh-switch

# Remove SSH config entries (manual review recommended)
# Edit ~/.ssh/config and remove gh-switch sections

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with pure shell scripting for maximum compatibility and zero dependencies.

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Author: Valentin Todorov

---

Note: This tool modifies your SSH config and Git settings. Always review changes and maintain backups of important configurations.