Git & SSH Multi-Identity Setup

A comprehensive POSIX-compliant shell script for managing multiple Git/GitHub identities with separate SSH keys, conditional configurations, and commit signing.

Quick Start

# Interactive setup wizard
./git-setup.sh --wizard

# View help
./git-setup.sh --help

# Check status
./git-setup.sh --status

Features

🔐 Multiple SSH Keys: Separate key pair for each GitHub identity
⚙️ Conditional Git Configs: Auto-switch identity based on directory
✍️ SSH Commit Signing: Sign commits with SSH keys (more secure than GPG)
🔄 Automatic Backup: All changes backed up automatically
🚀 GitHub Integration: Optional automatic key upload via API
🛠️ Diagnostic Tools: Comprehensive diagnostics and verification
📦 Zero Dependencies: Pure POSIX shell with optional enhancements

Files

Main Scripts

git-setup.sh - Modular version (8.3KB)
- Sources compiled libraries from lib/
- Best for development and customization
- Easy to modify and extend
git-setup.standalone.sh - Standalone version
- All library functions embedded
- Zero external dependencies
- Perfect for distribution and sharing
- Single file to copy anywhere

Library System

lib/ - Modular library system (17 libraries, 150+ functions)
- lib/git-lib.compiled.sh - Readable combined library
- lib/git-lib.compiled.min.sh - Minified library (~37% smaller)
- See lib/README.md for library details

Usage

Setup Wizard

Interactive mode walks through complete setup:

./git-setup.sh --wizard

Common Operations

# List configured identities
./git-setup.sh --list

# Test all GitHub connections
./git-setup.sh --test

# Add another identity
./git-setup.sh --add

# Remove an identity
./git-setup.sh --remove

# Rotate (regenerate) a key
./git-setup.sh --rotate

# Edit name, folder, or email for an identity
./git-setup.sh --edit

# Run diagnostics
./git-setup.sh --diagnose

# Show status dashboard
./git-setup.sh --status

Maintenance

# Restore from backup
./git-setup.sh --restore

# Fix SSH permissions
./git-setup.sh --fix-permissions

# Clean up orphaned includes
./git-setup.sh --cleanup

# Export configuration
./git-setup.sh --export

# Import configuration
./git-setup.sh --import backup-file.json

Utilities

# Copy public key to clipboard
./git-setup.sh --copy-key

# Check which identity applies here
./git-setup.sh --which

# Install dependencies (git, ssh, curl)
./git-setup.sh --install

# Check network connectivity
./git-setup.sh --check-network

How It Works

Identity Switching

The script creates conditional git configs that automatically switch based on directory:

# ~/.gitconfig
[includeIf "gitdir:~/code/work/"]
    path = ~/.gitconfig-work

[includeIf "gitdir:~/code/personal/"]
    path = ~/.gitconfig-personal

SSH Host Aliases

For non-default identities, SSH host aliases are created:

# ~/.ssh/config
Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/github_work_ed25519
    IdentitiesOnly yes

Then clone using the alias:

git clone git@github-work:company/repo.git

Commit Signing

Each identity can sign commits with its SSH key:

# ~/.gitconfig-work
[user]
    name = Your Name
    email = work@company.com
    signingkey = ~/.ssh/github_work_ed25519.pub

[gpg]
    format = ssh

[commit]
    gpgsign = true

Configuration Files

The script manages these files:

~/.ssh/config - SSH host configurations
~/.ssh/allowed_signers - For verifying commit signatures
~/.ssh/.backups/ - Automatic backups (timestamped)
~/.ssh/.git-ssh-identities.json - Identity state tracking
~/.gitconfig - Global git config with conditional includes
~/.gitconfig-<context> - Per-identity git configurations
~/.config/git-ssh-identities/.env - GitHub PAT tokens (optional)

Environment Variables

DEBUG=1 - Enable debug output
GIT_IDENTITIES_CONFIG_DIR - Override config directory for .env file
XDG_CONFIG_HOME - Standard XDG config directory

Development

Rebuilding Libraries

After modifying library source files:

cd _build
./compile-all.sh

This regenerates:

lib/git-lib.compiled.sh (readable)
lib/git-lib.compiled.min.sh (minified)
git-setup.standalone.sh (standalone)

The rebuild.sh script compiles libraries by default:

cd _build
./rebuild.sh              # Compile (same as compile mode)
./rebuild.sh compile      # Explicit compile (readable)
./rebuild.sh minify       # Compile minified libraries
./rebuild.sh test         # Compile and test

See lib/README.md for detailed library documentation.

Library Structure

Functions are organized into 17 specialized libraries:

core/ - Identity state management
env/ - Environment variables
file/ - File operations
git/ - Git configuration
github/ - GitHub API integration
input/ - User prompts
install/ - Dependency management
list/ - List operations
log/ - Logging functions
modes/ - Command handlers
platform/ - OS detection
sed/ - Portable sed operations
ssh/ - SSH key management
string/ - String utilities
ui/ - UI components
wizard/ - Setup wizard

Requirements

Minimum (POSIX shell)

sh - POSIX shell
git - Version control
ssh-keygen - Key generation
curl - GitHub API (optional)

Optional Enhancements

wl-copy / xclip / pbcopy - Clipboard support
GitHub Personal Access Token - Automatic key upload

Platform support

./git-setup.sh --install uses the platform’s package manager to install git, SSH client, and curl. Each row below has implemented support in lib/install/ and lib/platform/ (package manager detection, package names, install/update commands).

Platform	Package manager	Implemented in code
Debian	apt	✓ `get_package_manager`, `get_*_package`, `get_install_cmd`
Ubuntu	apt	✓ same as Debian
Fedora	dnf	✓
RHEL / CentOS	dnf, yum	✓ Rocky, AlmaLinux
Alpine	apk	✓
Arch	pacman	✓ Manjaro, EndeavourOS
SUSE	zypper	✓ openSUSE
macOS	Homebrew	✓ SSH/curl built-in; brew for git
FreeBSD	pkg	✓
Windows	winget, choco	✓ Git Bash / MSYS2 / Cygwin; winget preferred, choco fallback; curl built-in

Security Notes

SSH keys are Ed25519 (modern, secure)
Private keys never leave your machine
GitHub PAT tokens stored in ~/.config/git-ssh-identities/.env (0600 permissions)
SSH signing more secure than GPG (simpler, fewer attack vectors)
All backups include timestamps for rollback

Troubleshooting

Common Issues

"Command not found" errors

./git-setup.sh --install  # Install dependencies

Permission denied on SSH

./git-setup.sh --fix-permissions  # Fix SSH permissions

Wrong identity being used

./git-setup.sh --which  # Check which identity applies
./git-setup.sh --diagnose  # Run full diagnostics

Need to revert changes

./git-setup.sh --restore  # Restore from latest backup

Debug Mode

Enable debug output for troubleshooting:

DEBUG=1 ./git-setup.sh --diagnose

Examples

Complete Setup for Two Identities

# Run wizard
./git-setup.sh --wizard

# Configure work identity
Context name: work
GitHub username: johndoe
Email: john@company.com
Directory: ~/code/work
GitHub PAT: ghp_xxxxx (optional)

# Configure personal identity
Context name: personal
GitHub username: johndoe-personal
Email: john@personal.com
Directory: ~/code/personal
GitHub PAT: ghp_yyyyy (optional)

# Test connections
./git-setup.sh --test

# Check status
./git-setup.sh --status

Clone With Different Identities

# Default identity (first configured)
git clone git@github.com:company/repo.git

# Work identity (using SSH alias)
git clone git@github-work:company/repo.git

# Personal identity
git clone git@github-personal:johndoe-personal/repo.git

Verify Setup

cd ~/code/work/repo
git config user.email          # → john@company.com
git config user.signingkey     # → ~/.ssh/github_work_ed25519.pub

cd ~/code/personal/repo
git config user.email          # → john@personal.com
git config user.signingkey     # → ~/.ssh/github_personal_ed25519.pub

Contributing

The codebase is modular and well-organized:

Add functions: Create files in appropriate lib/*/ directory
Update manifest: Add function to lib/*/_manifest.txt
Rebuild: Run cd _build && ./compile-all.sh
Test: Run ./git-setup.sh --diagnose

License

MIT License - See project root for details

Support

For issues or questions:

Run diagnostics: ./git-setup.sh --diagnose
Check status: ./git-setup.sh --status
Review logs: ~/logs/git-ssh-identities/git-setup.log
Enable debug mode: DEBUG=1 ./git-setup.sh [command]

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.snapshots		.snapshots
.vscode		.vscode
_build		_build
lib		lib
tests		tests
.cspell-confirmed.toml		.cspell-confirmed.toml
.cspell.json		.cspell.json
.gitignore		.gitignore
.shellcheckrc		.shellcheckrc
README.md		README.md
STANDALONE_REPO.md		STANDALONE_REPO.md
git-setup.sh		git-setup.sh
git-setup.standalone.sh		git-setup.standalone.sh

Folders and files

Latest commit

History

Repository files navigation

Git & SSH Multi-Identity Setup

Quick Start

Features

Files

Main Scripts

Library System

Usage

Setup Wizard

Common Operations

Maintenance

Utilities

How It Works

Identity Switching

SSH Host Aliases

Commit Signing

Configuration Files

Environment Variables

Development

Rebuilding Libraries

Library Structure

Requirements

Minimum (POSIX shell)

Optional Enhancements

Platform support

Security Notes

Troubleshooting

Common Issues

Debug Mode

Examples

Complete Setup for Two Identities

Clone With Different Identities

Verify Setup

Contributing

License

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages