Git Account Manager (gitman)

A beautiful cross-platform CLI tool to manage multiple GitHub accounts on the same machine. Switch between personal, work, and client accounts effortlessly with arrow key navigation, automatic SSH key management, smart remote URL updates, automatic backups, and global git config switching.

✨ Features

• 🎨 Beautiful TUI - Arrow key navigation, no typing needed
• ⚡ Fast Switching - Change accounts in seconds
• 🌍 Global & Local Switching - Switch globally (all repos) or locally (current repo)
• 🔐 Auto SSH Setup - Generates keys and configures everything
• 🔄 Smart URL Updates - Automatically fixes remote URLs
• 💾 Persistent Config - Remembers all your accounts
• 🎯 Repo Detection - Knows when you're in a git repository
• 🖥️ Cross-Platform - Works on Linux, macOS, and Windows
• 📦 Zero Dependencies - Single Python script, no pip install needed
• 🔄 Auto Backups - Config backed up before every change

📸 Screenshots

Quick Switch (Arrow Keys)

Select Account - LOCAL switch (current repo only):
────────────────────────────────────────────────────────────
→ ● personal       john@personal.com
    work           john@work.com  
    client1        john@client1.com
────────────────────────────────────────────────────────────

↑/↓ Navigate  Enter Select  q Cancel

Global Switch

Select Account - GLOBAL switch (affects all repos):
────────────────────────────────────────────────────────────
  ● personal       john@personal.com
    work           john@work.com  
    client1        john@client1.com
────────────────────────────────────────────────────────────

↑/↓ Navigate  Enter Select  q Cancel

Interactive TUI

╔════════════════════════════════════════════════════════╗
║           Git Account Manager v1.1                     ║
╚════════════════════════════════════════════════════════╝

✓ In git repository
  Account: personal
  Current: John Doe <john@personal.com>

Quick Actions:
  s. Switch account (arrow key selection)
  w. Show status (who am I?)

Account Management:
  l. List all accounts
  a. Add account
  e. Edit account
  r. Remove account

Backup:
  b. Show backup info
  R. Restore from backup

  q. Exit

🚀 Installation

Linux / macOS

Option 1: Quick Install (Recommended)

# Download and install
curl -o ~/bin/gitman https://raw.githubusercontent.com/oxzoid/gitman/main/gitman
chmod +x ~/bin/gitman

# Add ~/bin to PATH if not already there
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or for zsh
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Option 2: Manual Install

# Create bin directory
mkdir -p ~/bin

# Download the script (or copy-paste the code)
nano ~/bin/gitman
# Paste the gitman code, save with Ctrl+O, Enter, Ctrl+X

# Make executable
chmod +x ~/bin/gitman

# Add to PATH
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify Installation

gitman help

Windows

Option 1: Using Git Bash (Recommended)

# In Git Bash
mkdir -p ~/bin
curl -o ~/bin/gitman https://raw.githubusercontent.com/oxzoid/gitman/main/gitman
chmod +x ~/bin/gitman

# Add to PATH
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify
gitman help

Option 2: Using PowerShell

# Create directory
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\bin"

# Download the script
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/oxzoid/gitman/main/gitman" -OutFile "$env:USERPROFILE\bin\gitman.py"

# Create wrapper batch file
$batchContent = @"
@echo off
python "%USERPROFILE%\bin\gitman.py" %*
"@
Set-Content -Path "$env:USERPROFILE\bin\gitman.bat" -Value $batchContent

# Add to PATH (User level - no admin needed)
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($currentPath -notlike "*$env:USERPROFILE\bin*") {
    [Environment]::SetEnvironmentVariable("Path", "$currentPath;$env:USERPROFILE\bin", "User")
}

# Restart PowerShell, then verify
# Close and reopen PowerShell
gitman help

Option 3: Direct Python Execution

# Save the script anywhere
python C:\path\to\gitman.py help

# Or add an alias
doskey gitman=python C:\path\to\gitman.py $*

Windows Requirements

• Python 3.6+ (Download from python.org)
• Git for Windows (includes OpenSSH) - Download
• OpenSSH Client (Windows 10+ has it built-in, or comes with Git)

📖 Quick Start

First Time Setup

Run the setup wizard - it does everything for you:

gitman setup

This will:

1. ✅ Ask for your account details
2. ✅ Generate SSH keys automatically
3. ✅ Configure SSH hosts
4. ✅ Add keys to ssh-agent
5. ✅ Show you the public key to add to GitHub
6. ✅ Test the connection

Just follow the prompts and paste the public key to GitHub!

Adding More Accounts

gitman add
# Choose option 2 for auto-setup

Switch Accounts

Local Switch (Current Repo Only)

# In any git repository
gitman

# Use arrow keys to select account
# Press Enter to switch (affects current repo only)

Global Switch (All Repos)

# From anywhere (even outside a repo)
gitman switch --global

# Or use the short flag
gitman s -g

# Use arrow keys to select account
# Press Enter to switch (affects all repos globally)

Direct Switch

# Switch current repo to personal
gitman switch personal

# Switch globally to work account
gitman switch work --global

🎯 Usage

Commands

gitman setup             # Complete setup wizard (first time)
gitman                   # Quick switch (local if in repo, global if not)
gitman status            # Show current git identity
gitman switch            # Switch with arrow keys (context-aware)
gitman switch --global   # Switch globally with arrow keys
gitman switch <account>  # Switch to specific account (local)
gitman switch <account> --global  # Switch to specific account (global)
gitman list              # List all accounts
gitman add               # Add new account
gitman remove            # Remove account (arrow keys)
gitman remove <account>  # Remove specific account
gitman backup            # Show backup information
gitman restore           # Restore from backup
gitman help              # Show help
gitman edit              # Edit account (arrow keys)
gitman edit <account>    # Edit specific account
gitman clone             Show clone URLs for all accounts
gitman clone <account>   Show clone URL for specific account

Aliases

gitman who               # Same as 'status'
gitman s                 # Same as 'switch'
gitman s -g              # Same as 'switch --global'
gitman ls                # Same as 'list'
gitman l                 # Same as 'list'
gitman a                 # Same as 'add'
gitman rm <account>      # Same as 'remove'
gitman r                 # Same as 'remove'
gitman e                 # Same as 'edit'
gitman c                 #Same as 'clone

Interactive Mode Shortcuts

When in the TUI (run gitman without arguments outside a repo):

• s - Switch account
• w - Show status (who am I?)
• l - List all accounts
• a - Add account
• r - Remove account
• b - Show backup info
• R - Restore from backup (capital R)
• q - Quit
• e - Edit account

🌍 Global vs Local Switching

Local Switch (Repository-Level)

When: You're in a git repository and want to change the identity for that repo only.

cd ~/my-project
gitman switch personal  # Only affects this repo

Result:

• Sets git config user.name and user.email for current repo
• Updates remote URL to use correct SSH host
• Other repos remain unchanged

Global Switch (System-Wide)

When: You want to set your default identity for all new repos and repos without local config.

# From anywhere
gitman switch work --global

Result:

• Sets git config --global user.name and user.email
• Affects all future repos and repos without local settings
• Useful before cloning repos or starting new projects

Smart Context Detection

# Inside a repo: local switch
cd ~/my-repo
gitman          # → Shows "LOCAL switch (current repo only)"

# Outside a repo: global switch
cd ~
gitman          # → Shows "GLOBAL switch (affects all repos)"

🔄 Common Workflows

Workflow 1: Clone and Work on Different Accounts

# Set global to work account (for cloning work repos)
gitman switch work --global

# Clone work repo (uses work SSH key and identity)
git clone git@github.com-work:company/project.git
cd project

# Verify identity
gitman status
# ✓ Shows work account

# Switch to personal for a quick fix in personal repo
cd ~/personal-project
gitman switch personal  # Local switch, doesn't affect global

# Clone another work repo (still uses global work account)
cd ~
git clone git@github.com-work:company/another-project.git

Workflow 2: Freelancer with Multiple Clients

# Set default to personal
gitman switch personal --global

# Working on client A's project
cd ~/clients/clientA/project
gitman switch clientA  # Local switch

# Working on client B's project  
cd ~/clients/clientB/project
gitman switch clientB  # Local switch

# Back to personal projects (uses global)
cd ~/personal/my-app
gitman status
# ✓ Shows personal account (from global)

Workflow 3: Company Developer

# Set global to work (default for all work)
gitman switch work --global

# All work repos automatically use work account
git clone git@github.com-work:company/repo1.git
git clone git@github.com-work:company/repo2.git
git clone git@github.com-work:company/repo3.git

# Quick personal contribution (local override)
cd ~/open-source/some-library
gitman switch personal  # Just for this repo

# Back to work
cd ~/company/repo1
gitman status
# ✓ Uses work account (from global)

🔄 Backup System

gitman automatically backs up your config before every change (add/remove accounts). Only one backup version is kept.

Backup Commands

# Show what's in the backup
gitman backup

# Restore from backup (with preview and confirmation)
gitman restore

Backup Location

~/.gitmanager/
├── config.json           # Current config
└── backups/
    ├── config.backup.json    # Last backup
    └── config.temp.json      # Temporary safety backup

How It Works

1. Auto-backup: Before adding/removing accounts, current config is saved
2. Single version: Only the most recent backup is kept (no clutter)
3. Safe restore: Shows preview of both backup and current config before restoring
4. Safety net: Creates a temp backup of current config before restoring

📁 File Locations

Linux / macOS

~/.gitmanager/
├── config.json                 # Account configurations
└── backups/
    └── config.backup.json      # Backup

~/.ssh/
├── config                      # SSH host configurations
├── id_ed25519_personal         # Personal private key
├── id_ed25519_personal.pub     # Personal public key
├── id_ed25519_work             # Work private key
├── id_ed25519_work.pub         # Work public key
└── ...

~/bin/
└── gitman                      # The script

Windows

C:\Users\YourName\.gitmanager\
├── config.json                 # Account configurations
└── backups\
    └── config.backup.json      # Backup

C:\Users\YourName\.ssh\
├── config                      # SSH host configurations
├── id_ed25519_personal         # Personal private key
├── id_ed25519_personal.pub     # Personal public key
├── id_ed25519_work             # Work private key
├── id_ed25519_work.pub         # Work public key
└── ...

C:\Users\YourName\bin\
└── gitman.py                   # The script

🎓 Complete Workflow Example

Scenario: Developer with Personal and Work Accounts

# 1. Install gitman
curl -o ~/bin/gitman https://raw.githubusercontent.com/oxzoid/gitman/main/gitman
chmod +x ~/bin/gitman

# 2. Setup personal account
gitman setup
# Answer prompts:
# - Account name: personal
# - Display name: John Doe
# - Email: john@personal.com
# - GitHub username: johndoe
# Copy the SSH key to GitHub

# 3. Setup work account
gitman add
# Choose option 2 (auto-setup)
# - Account name: work
# - Display name: John Doe
# - Email: john@company.com
# - GitHub username: johndoe-work
# Copy the SSH key to GitHub

# 4. Set global default to work (for daily work)
gitman switch work --global

# 5. Clone a work project (automatically uses work account)
git clone git@github.com-work:company/project.git
cd project

# 6. Verify identity
gitman status
# Shows: work account

# 7. Quick personal project
cd ~/personal/my-app
gitman switch personal  # Local override

# 8. Verify
gitman status
# Shows: personal account

# 9. Commit and push
git add .
git commit -m "Update feature"
git push
# Uses personal account identity!

# 10. Back to work project
cd ~/work/company-project
gitman status
# Shows: work account (from global)

🔧 Manual SSH Setup (Advanced)

If you prefer to set up SSH manually instead of using auto-setup:

1. Generate SSH Keys

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

# Work account
ssh-keygen -t ed25519 -C "work@email.com" -f ~/.ssh/id_ed25519_work

2. Configure SSH (~/.ssh/config)

nano ~/.ssh/config

Add:

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

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

3. Add Keys to GitHub

# Copy personal key
cat ~/.ssh/id_ed25519_personal.pub

# Copy work key
cat ~/.ssh/id_ed25519_work.pub

Go to GitHub → Settings → SSH and GPG keys → New SSH key

4. Add to gitman

gitman add
# Choose option 1 (manual setup)

5. Test Connections

ssh -T git@github.com-personal
ssh -T git@github.com-work

Expected: Hi username! You've successfully authenticated...

🎨 How It Works

SSH Host Aliases

Each account uses a unique SSH host alias:

• github.com-personal → Uses personal SSH key
• github.com-work → Uses work SSH key
• github.com-client1 → Uses client1 SSH key

Smart Git Config Management

gitman intelligently manages git config based on context:

Local Switch (in a repo):

cd ~/my-repo
gitman switch personal

# Sets (repository-level):
# git config user.name "John Doe"
# git config user.email "john@personal.com"

Global Switch (anywhere):

gitman switch work --global

# Sets (system-wide):
# git config --global user.name "John Doe"
# git config --global user.email "john@company.com"

Automatic Remote URL Updates

When switching accounts in a repo, gitman automatically updates remote URLs:

# Before: git@github.com-work:user/repo.git
gitman switch personal
# After:  git@github.com-personal:user/repo.git

This ensures pushes use the correct SSH key!

🆚 Comparison

vs Traditional Methods

Feature	gitman	Manual	Git Config	Other Tools
Visual UI	✅ Arrow keys	❌ CLI only	❌ CLI only	⚠️ Varies
Global switching	✅ Yes	✅ Yes	✅ Yes	⚠️ Some
Local switching	✅ Yes	✅ Yes	✅ Yes	⚠️ Some
Auto SSH setup	✅ Yes	❌ Manual	❌ Manual	⚠️ Some
Remote URL fix	✅ Automatic	❌ Manual	❌ Manual	⚠️ Some
Auto backups	✅ Yes	❌ No	❌ No	⚠️ Some
Cross-platform	✅ Win/Mac/Linux	✅ Yes	✅ Yes	⚠️ Limited
Zero dependencies	✅ Just Python	✅ Just Git	✅ Just Git	❌ Need packages
Account storage	✅ Persistent	❌ Remember	❌ Scripts	⚠️ Varies
Context awareness	✅ Smart detection	❌ Manual	❌ Manual	⚠️ Some

🐛 Troubleshooting

"Not in a git repository" when trying local switch

Solution: Navigate to a git repository or use global switch.

# Either:
cd ~/your-project
gitman switch personal

# Or:
gitman switch personal --global

"Account not found"

Solution: List and add accounts.

gitman list          # See available accounts
gitman add           # Add new account

Which config am I using? (Global vs Local)

Check local (current repo):

git config user.email

Check global (system-wide):

git config --global user.email

Check effective (what will be used):

git config --show-origin user.email

Remote URL Not Updating

Problem: Remote URL stays the same after switching. Solution: Check SSH config has the correct host.

cat ~/.ssh/config
# Should have entries like:
# Host github.com-personal
#     HostName github.com
#     ...

SSH Connection Failed

Problem: ssh -T git@github.com-personal fails Solutions:

1. Check SSH key is added to GitHub
2. Verify SSH config syntax
3. Ensure ssh-agent is running
4. Check key permissions (should be 600)

# Start ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_personal

# Fix permissions
chmod 600 ~/.ssh/id_ed25519_personal
chmod 644 ~/.ssh/id_ed25519_personal.pub
chmod 600 ~/.ssh/config

"ssh-keygen: command not found" (Windows)

Solution: Install Git for Windows or OpenSSH.

• Git for Windows: https://git-scm.com/download/win
• Or enable OpenSSH in Windows Features

Arrow Keys Don't Work

On Windows CMD/PowerShell: Use Git Bash or Windows Terminal instead. On Linux: Check if terminal supports ANSI escape sequences.

Colors Don't Show (Windows)

Solution: Use Windows Terminal or Git Bash instead of old CMD.

# Install Windows Terminal (recommended)
winget install Microsoft.WindowsTerminal

Python Version Issues

Problem: python3: command not found Solution: Use python instead, or install Python 3.6+

# Check version
python --version
python3 --version

# If needed, download from python.org

Lost Config After Mistake

Solution: Restore from automatic backup

# Check what's in the backup
gitman backup

# Restore with confirmation
gitman restore

💡 Tips & Best Practices

Naming Conventions

Use descriptive account names:

• ✅ personal, work, freelance, client-acme
• ❌ acc1, test, temp

Set a Sensible Global Default

Choose your most-used account as global default:

# If you mostly work on company projects
gitman switch work --global

# If you mostly work on personal projects
gitman switch personal --global

Clone with Correct Host

Always clone using the appropriate SSH host:

# Personal projects
git clone git@github.com-personal:username/repo.git

# Work projects
git clone git@github.com-work:username/repo.git

Check Before Committing

Get in the habit of checking your identity:

cd ~/project
gitman status        # Quick check
git commit -m "..."  # Now commit safely

Use Local Overrides When Needed

If your global is set to work, but you need to contribute to an open-source project:

cd ~/open-source/some-library
gitman switch personal  # Local override, doesn't affect other repos

Multiple Clients

For freelancers with many clients:

gitman add  # client-acme
gitman add  # client-techcorp
gitman add  # client-startup
# Each gets its own SSH key and config

# Set a default for new projects
gitman switch freelance --global

Backup Your Keys

# Backup SSH keys
cp -r ~/.ssh ~/backup-ssh-$(date +%Y%m%d)

# Backup gitman config
cp ~/.gitmanager/config.json ~/backup-gitman-$(date +%Y%m%d).json

Note: gitman automatically backs up config before changes, but manual backups of SSH keys are still recommended.

🤝 Contributing

Contributions welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests
• Improve documentation

📄 License

MIT License - feel free to use and modify

🙏 Credits

Created by oxzoid for developers managing multiple GitHub accounts efficiently.

📚 Additional Resources

• GitHub SSH Documentation
• Git Config Documentation
• Multiple SSH Keys Guide
• Windows OpenSSH

❓ FAQ

Does this work with existing repos?

Yes! Run gitman switch <account> in any repo to update its identity and remote URL.

Can I have more than 2 accounts?

Absolutely! Add as many as you need - personal, work, clients, open source, etc.

Will this mess up my global git config?

Only when you explicitly use --global flag. Local switches only affect the current repository.

What's the difference between local and global switch?

• Local: Changes identity for current repo only (git config user.name)
• Global: Changes identity for all repos system-wide (git config --global user.name)

When should I use global vs local switch?

• Global: Set your default identity for most projects (e.g., work account for a company developer)
• Local: Override for specific repos (e.g., personal contribution to open-source while at work)

Can I switch globally while in a repo?

Yes! Use gitman switch --global or gitman switch <account> --global.

What if I already have SSH keys?

The setup wizard will detect them and offer to use existing keys or generate new ones.

Can I use HTTPS instead of SSH?

gitman is designed for SSH key management. For HTTPS, you'd need to use Git credential managers instead.

What if I accidentally delete an account?

Use gitman restore to recover from the automatic backup created before the deletion.

How do I know which config is active?

Use gitman status to see current identity, or:

# Check local
git config user.email

# Check global  
git config --global user.email

# Check effective (what will be used)
git config --show-origin user.email

---

Made with ❤️ for developers juggling multiple GitHub accounts

If this tool helped you, give it a ⭐ on GitHub!