GitSSH

╔═══════════════════════════════════════════════════════════════╗
║ ║
║ ██████╗ ███████╗███████╗██╗ ██╗ ║
║ ██╔════╝ ██╗ ██╗ ██╔════╝██╔════╝██║ ██║ ║
║ ██║ ███╗══╝████║███████╗███████╗███████║ ║
║ ██║ ██║██║ ██║ ╚════██║╚════██║██╔══██║ ║
║ ██████╔╝██║ ██║ ███████║███████║██║ ██║ ║
║ ╚═════╝ ╚═╝ ╚═╝ ╚══════╝╚══════╝╚═╝ ╚═╝v0.1.0-Oz ║
║ <-POSIX Compliant-> ║
║ ║
╚═══════════════════════════════════════════════════════════════╝
Manage Multiple SSH Git and GitHub Account Sessions With Ease!
USAGE:
gitssh <command> [subcommand] [options]
SETUP & INITIALIZATION:
init Initialize GitSSH configuration
onboard|setup-wizard Interactive first-time setup wizard
validate|check|doctor Validate gitssh system configuration
ENHANCED GIT OPERATIONS:
clone <url> Enhanced git clone with auto-setup
status|st Enhanced git status with user info
commit|ci [opts] Enhanced git commit with user verification
push [opts] Enhanced git push with verification
fetch [opts] Enhanced git fetch with SSH verification
pull [opts] Enhanced git pull with SSH verification
info Show detailed repository information and SSH connection
USER MANAGEMENT:
switch|sw <user> Switch to user locally
switch|sw -g <user> Switch to user globally
user|users See user accounts and ssh accounts status
user add [opts] Add new user account
user remove|rm|delete <user> Remove user account
user list List all configured users
user switch <user> Switch to user locally
user switch -g <user> Switch to user globally
user status Show current user status
SESSION MANAGEMENT:
session|sess Show current repository and user session information
session set Set user for current repository
session status [options]Show current repository and user session information
session show [options] Show current repository and user session information
session clear Clear session data
session forget|remove Remove persistent config for repo
session list List all session repositories
session export <path> Export session data to file
session import <path> Import session data from file
session cleanup Cleanup stale session data
SSH MANAGEMENT:
ssh status|info Show SSH configuration status
ssh doctor Diagnose SSH connection issues
ssh repair Fix common SSH problems
ssh test <host> Test SSH connection
ssh backup Backup SSH configuration
ssh restore <path> Restore SSH configuration from backup
ssh learn Guide to adding new SSH hosts
SETUP WIZARDS:
setup github Setup GitHub SSH authentication
setup gitlab Setup GitLab SSH authentication
REMOTE MANAGEMENT:
remote|remotes Show git repository remotes
remote convert Convert HTTPS remote to SSH
remote add <name> <url> Add remote with SSH conversion
remote check Check remote configuration
remote list List all remotes with details
remote recommendations Show remote configuration recommendations
CONFIGURATION:
config show Show current configuration
config reset Reset configuration to defaults
config backup Backup configuration files
config restore <path> Restore from backup
config migrate Migrate from old configuration format
INSTALLATION/UNINSTALLATION/UPDATE MANAGEMENT:
gitssh reinstall Reinstall GitSSH system
gitssh uninstall|remove Completely remove GitSSH
gitssh update|upgrade Update to latest version
gitssh verify|test-install Verify installation integrity
gitssh diagnose|doctor-install Run installation diagnostics
INFORMATION:
help [command] Show help (general or command-specific)
version Show version information
EXAMPLES:
gitssh onboard # First-time setup
gitssh user add # Add new user
gitssh user switch work # Switch to work identity
gitssh session set # Configure current repo
gitssh clone git@github.com:user/repo.git
gitssh remote convert # Convert HTTPS to SSH
gitssh ssh status # Check SSH setup

A small tool to manage multiple Git accounts (GitHub, GitLab etc.) with SSH — without losing your mind.

---

Why GitSSH?

If you’ve ever had to juggle a personal GitHub, a work GitHub, maybe a client’s GitLab, and even a random Bitbucket repo — you already know the pain:

• SSH keys get mixed up → wrong key, wrong account, failed authentication.
• Git configs change constantly → user.name and user.email never stay correct.
• HTTPS is annoying → constantly typing passwords or PATs.
• Identity confusion → commits end up under the wrong user.
• Manual SSH config edits → one mistake, and nothing works.

GitSSH makes all of that simpler.

---

What It Does

Instead of constantly adding/removing keys, tweaking configs, and hoping for the best, GitSSH automates it.

The old way (annoying):

ssh-add ~/.ssh/id_rsa_work
git config user.name "Work Name"
git config user.email "work@company.com"
git clone git@github.com-work:company/project.git

With GitSSH (cleaner):

gitssh switch work
gitssh clone https://github.com/company/project.git
cd project
gitssh commit -m "fix"

GitSSH keeps track of which account is active, sets the right SSH key, updates your Git config, and makes sure you’re committing/pushing as the correct user.

---

Highlights

• No more SSH key guessing — GitSSH manages them for you.
• Correct identity every time — no accidental commits under the wrong email.
• Works with GitHub, GitLab, Bitbucket, and custom servers.
• Remembers settings across sessions and projects.
• Switch accounts with a single command.
• Converts HTTPS clone URLs to SSH automatically.

---

Installation

Quick Install

curl -fsSL https://raw.githubusercontent.com/gitssh-cli/gitssh/refs/heads/main/install-gitssh | sh

Manual

git clone https://github.com/gitssh-cli/gitssh.git
cd gitssh
chmod +x install
./install

The installer supports:

./install install # Install (default)
./install update # Update GitSSH
./install uninstall # Remove everything
./install verify # Check installation
./install diagnose # Run diagnostics

---

Basic Usage

First-time setup

gitssh onboard

or

gitssh init
gitssh user add

Switching accounts

gitssh switch github-work
gitssh clone https://github.com/company/project.git

Repo-specific identity

cd personal-project
gitssh session set github-personal

---

Commands You’ll Actually Use

• gitssh switch <user> → switch global account
• gitssh user add → add a new user (GitHub/GitLab/etc.)
• gitssh session set <user> → set account just for current repo
• gitssh remote convert → change HTTPS remotes to SSH
• gitssh ssh doctor → debug SSH issues
• gitssh commit / gitssh push → safer versions of Git commands

Essential Commands

Account management:

gitssh user add # Add new account
gitssh user list # Show all accounts
gitssh switch <user># Switch globally
gitssh session set# Set for current repo only

Working with repos:

gitssh clone <url># Enhanced clone with auto-setup
gitssh remote convert # Convert HTTPS remotes to SSH
gitssh status # Git status + user info
gitssh commit # Commit with identity verification

Troubleshooting:

gitssh ssh doctor # Diagnose SSH problems
gitssh ssh status # Check SSH setup
gitssh validate # Verify installation

There's more (gitssh help shows everything), but these cover most daily use.

---

Configuration

GitSSH uses simple JSON files you can read and edit:

• ~/.gitssh-users.json - your accounts and SSH keys
• ~/.gitssh-sessions.json - per-repo user mappings

Example user config:

{
"users": {
"github-personal": {
"name": "John Doe",
"email": "john@example.com",
"ssh_key": "~/.ssh/github_personal_id_ed25519",
"host": "github.com"
},
"github-work": {
"name": "John Doe", "email": "john.doe@company.com",
"ssh_key": "~/.ssh/github_work_id_ed25519",
"host": "github.com"
}
},
"default_user": "github-personal"
}

Common Workflows

Multiple GitHub accounts

# Add accounts
gitssh user add # Follow prompts for 'github-personal'
gitssh user add # Follow prompts for 'github-work'# Switch contexts
gitssh switch github-work
gitssh clone git@github.com:company/project.git
gitssh switch github-personal gitssh clone git@github.com:myuser/personal-project.git

Per-repository identity

# Set specific user for this repocd work-project
gitssh session set github-work
cd personal-project gitssh session set github-personal
# GitSSH remembers these settings

Fix existing repositories

# Convert HTTPS to SSHcd existing-repo
gitssh remote convert
# Check what's configured
gitssh info
gitssh ssh status

Architecture

GitSSH installs as a modular system:

~/.local/bin/gitssh-libs/ # Main installation
├── gitssh # CLI dispatcher
├── install # Installer
└── modules/ # Core functionality
├── gitssh-utils.sh # Utilities
├── gitssh-users.sh # User management
├── gitssh-sessions.sh # Session handling
├── gitssh-remotes.sh # Remote management
├── gitssh-commands.sh # Git command wrappers
├── gitssh-init.sh # Initialization
└── gitssh-setup.sh # Setup wizards
~/.local/bin/gitssh # Symlink for easy access

Requirements

You need these installed:

• git - obviously
• ssh - OpenSSH or compatible
• jq - for JSON config handling

Install with your package manager:

# Ubuntu/Debian
sudo apt install git openssh-client jq
# macOS 
brew install git openssh jq
# Others: yum, dnf, pacman, etc.

Troubleshooting

Command not found:

# Check installation
./install verify
source~/.bashrc # Reload shell

SSH problems:

gitssh ssh doctor # Auto-diagnose issues
gitssh ssh test github.com # Test specific host

Identity issues:

gitssh user status # Check current user
gitssh session show # Check repo mappings
gitssh session clear # Reset if confused

Nuclear option:

./install uninstall
./install install # Fresh start

Advanced Features

Interactive setup wizards:

gitssh setup github # GitHub-specific setup
gitssh setup gitlab # GitLab-specific setup

Configuration management:

gitssh config backup # Backup settings
gitssh config restore # Restore from backup
gitssh config migrate # Upgrade config format

Batch operations:

# Check SSH for all configured hosts
gitssh ssh status
# Get recommendations for current repo
gitssh remote recommendations

Development

The codebase is modular and POSIX-compatible. Each module handles a specific area (users, sessions, SSH, etc.) with comprehensive error handling.

To contribute:

1. Fork the repo
2. Follow POSIX shell conventions
3. Add proper error handling
4. Test with ./install verify (Might not work as intended, through testing is necessary for verification of working features)
5. Submit a pull request

License

MIT - use it however you want.

Links

• Issues:Report problems
• Discussions:Get help
• Wiki:Detailed docs

---