GitSwitch

Stop juggling SSH keys and git configs. Switch profiles in one command.

Installation · Quick Start · Features · Architecture · Roadmap

The Problem

You have multiple Git accounts — personal, work, client projects. Every time you switch repos, you manually:

• Check which account you're using
• Update git config user.name and user.email
• Swap SSH keys in ~/.ssh/config
• Hope you didn't commit with the wrong identity

GitSwitch automates all of this.

Demo

# Create profiles for each identity
$ gsw add personal
? Git user name: John Doe
? Git email: [email protected]
? Protocol: SSH
? SSH key path: ~/.ssh/id_ed25519_personal
? Default host: github.com
? Repo patterns: github.com/johndoe/*
✓ Profile "personal" created (SSH).

$ gsw add work
? Git user name: John Doe
? Git email: [email protected]
? Protocol: SSH
? SSH key path: ~/.ssh/id_ed25519_work
? Default host: github.com
? Repo patterns: github.com/company-org/*
✓ Profile "work" created (SSH).

# Switch between profiles instantly
$ cd ~/projects/my-app
$ gsw switch personal
✓ Set user.name = "John Doe"
✓ Set user.email = "[email protected]"
✓ SSH key → ~/.ssh/id_ed25519_personal
✓ Profile "personal" active for this repo

$ cd ~/projects/work-app
$ gsw switch work
✓ Set user.name = "John Doe"
✓ Set user.email = "[email protected]"
✓ SSH key → ~/.ssh/id_ed25519_work
✓ Profile "work" active for this repo

# Or let the shell hook detect it automatically
$ cd ~/projects/work-app
? Repo matches profile "work". Switch? (Y/n) Y
✓ Switched to "work"

Installation

# Clone and build
git clone https://github.com/developzoneio/gitswitch.git
cd gitswitch
npm install
npm run build

# Link globally
npm link

# Verify
gsw --version

Quick Start

# 1. Create your first profile
gsw add personal

# 2. Switch to it in any git repo
cd /path/to/your/repo
gsw switch personal

# 3. Install shell hook for auto-detection
gsw init

Features

Protocol Selection

Each profile supports SSH or HTTPS. GitSwitch automatically converts remote URLs when switching profiles.

$ gsw add work
? Protocol: HTTPS  # No SSH key needed
✓ Profile "work" created (HTTPS).

$ gsw switch work
✓ Set user.name = "John Doe"
✓ Set user.email = [email protected]
✓ Remote URL → https://github.com/company/repo.git
✓ HTTPS mode — SSH key swap skipped.

SSH Key Management

GitSwitch manages a single, clean block in ~/.ssh/config:

# --- managed by gitswitch ---
Host github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_work
    IdentitiesOnly yes
# --- end gitswitch ---

No conflicts with your existing SSH config. Other entries remain untouched.

Shell Hook Auto-Detection

Install the shell hook and GitSwitch will detect which profile to use when you cd into a repo:

gsw init  # Supports Bash, Zsh, PowerShell, Fish

Repo Pattern Matching

Map repos to profiles using glob patterns:

{
  "repoPatterns": [
    "github.com/company-org/*",
    "gitlab.com/client-*"
  ]
}

Commands

| Command | Description | |---------|-------------| | gsw add | Create a new profile (interactive) | | gsw switch <name> | Switch to a profile | | gsw detect | Auto-detect profile for current repo | | gsw current | Show active profile | | gsw list | List all profiles | | gsw remove <name> | Delete a profile | | gsw link | Bind current repo to a profile | | gsw unlink | Remove repo binding | | gsw init | Install shell hook |

Note: If your profile name contains spaces, wrap it in quotes:

gsw switch "work ema region"
gsw remove "work ema region"

Architecture

┌─────────────────────────────────────────────────┐
│                   GitSwitch CLI                  │
├──────────────┬──────────────┬───────────────────┤
│  Commands    │  Shell Hook  │  Core Engine      │
│              │              │                   │
│  add         │  bash hook   │  ProfileManager   │
│  switch      │  zsh hook    │  SSHKeyManager    │
│  list        │  ps hook     │  GitConfigManager │
│  detect      │  fish hook   │  RepoDetector     │
│  current     │              │  URLConverter     │
│  link/unlink │              │                   │
│  init        │              │                   │
├──────────────┴──────────────┴───────────────────┤
│         ~/.gitswitch/config.json (metadata)      │
│         ~/.ssh/config (SSH key block)            │
└─────────────────────────────────────────────────┘

Design Decisions

| Decision | Rationale | |----------|-----------| | File-based config over DB | Simple, portable, version-controllable | | Single SSH config block | Minimal invasion, no conflicts with existing config | | Shell hook over git hook | Catches cd into repos, not just git operations | | Protocol-aware URL conversion | Seamless SSH ↔ HTTPS switching | | Pattern-based repo matching | Flexible without manual per-repo binding |

Tech Stack

• Runtime: Node.js 18+ (ESM)
• Language: TypeScript (strict mode)
• CLI Framework: Commander.js
• Prompts: @inquirer/prompts
• Testing: Vitest
• Build: tsup

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

# Type check
npm run lint

Project Structure

gitswitch/
├── src/
│   ├── commands/          # CLI command handlers
│   │   ├── add.ts         # Profile creation wizard
│   │   ├── switch.ts      # Profile switching + URL conversion
│   │   ├── detect.ts      # Auto-detection logic
│   │   ├── current.ts     # Show active profile
│   │   ├── list.ts        # List all profiles
│   │   ├── remove.ts      # Delete profile
│   │   ├── link.ts        # Bind repo to profile
│   │   ├── unlink.ts      # Remove repo binding
│   │   └── init.ts        # Shell hook installer
│   ├── core/              # Core logic (no CLI dependencies)
│   │   ├── config.ts      # Profile CRUD, config I/O
│   │   ├── git.ts         # Git operations, URL conversion
│   │   ├── ssh.ts         # SSH config management
│   │   └── detector.ts    # Pattern matching engine
│   ├── hooks/             # Shell hook templates
│   │   └── templates.ts   # Bash/Zsh/PowerShell/Fish hooks
│   └── index.ts           # CLI entry point
├── tests/                 # Test suite
│   ├── core/              # Core module tests
│   └── hooks/             # Hook template tests
└── docs/
    └── superpowers/       # Design specs and plans

Roadmap

v1.0 — CLI Foundation (Current)

• [x] Profile management (add, remove, list, switch)
• [x] SSH key swapping via ~/.ssh/config
• [x] Protocol selection (SSH / HTTPS)
• [x] Remote URL conversion (SSH ↔ HTTPS)
• [x] Shell hook auto-detection (Bash, Zsh, PowerShell, Fish)
• [x] Repo pattern matching

v1.1 — Enhanced CLI

• [ ] HTTPS token management (store & auto-fill credentials)
• [ ] Profile import/export (share configs across machines)
• [ ] gsw doctor — diagnose SSH keys, permissions, config issues
• [ ] Multi-remote support (origin + upstream)

v2.0 — Windows Tray App

• [ ] System tray application (WPF / WinUI 3)
• [ ] Quick switch profiles from tray menu
• [ ] Desktop notifications on profile switch
• [ ] Auto-start with Windows
• [ ] Tray icon shows active profile indicator
• [ ] Mini dashboard — view all profiles at a glance

v3.0 — Cross-Platform GUI

• [ ] macOS menu bar app
• [ ] Linux system tray support
• [ ] Electron / Tauri wrapper for unified codebase
• [ ] Visual profile editor
• [ ] Git repository browser with profile mapping

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (npm test)
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

MIT License - see LICENSE for details.

Built with TypeScript and a lot of git config frustration.

Report Bug · Request Feature