Modern way to manage multiple cloud repositories from one machine

🎯 Introduction: What We're Solving

When working with multiple Git accounts (personal, work, client), you need:

1. Different SSH keys for authentication
2. Different Git identities (name/email) for commits
3. A clean way to switch between them automatically

This guide covers two approaches:

• Approach 1: Per-project configuration (simple, explicit)
• Approach 2: Directory-based configuration (automatic, organized)

---

🔐 Part 1: SSH Key Fundamentals

What Happens When You Generate SSH Keys?

When you run ssh-keygen, two files are created:

Private Key (id_personal):

• File: ~/.ssh/id_personal (no extension)
• Content: Encrypted private key data (starts with -----BEGIN OPENSSH PRIVATE KEY-----)
• Purpose: Your secret key - NEVER share this!
• Permissions: 600 (only you can read/write)

Public Key (id_personal.pub):

• File: ~/.ssh/id_personal.pub (.pub extension)
• Content: Single line like ssh-ed25519 AAA... personal@email.com
• Purpose: Public key you add to GitHub/GitLab
• Permissions: 644 (readable by others)

Generating Multiple Keys

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

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

# After each command:
# 1. You choose save location (or accept default)
# 2. Enter passphrase (recommended for security)
# 3. Confirm passphrase
# 4. Two files are created in ~/.ssh/

Files Generated:

~/.ssh/id_personal     # Private key (secret)
~/.ssh/id_personal.pub # Public key (share this)
~/.ssh/id_work         # Private key for work
~/.ssh/id_work.pub     # Public key for work

---

🤖 Part 2: SSH Agent - Your Key Manager

What SSH Agent Does

SSH Agent stores your private keys in memory after you unlock them with your passphrase. This means:

• You enter passphrase once per session
• Git can use your keys without prompting
• Keys are removed from memory when you close the terminal

Platform-Specific Commands

macOS:

# Start agent
eval "$(ssh-agent -s)"

# Add key with macOS keychain integration (passphrase saved)
ssh-add --apple-use-keychain ~/.ssh/id_personal

# Alternative (older but works)
ssh-add -K ~/.ssh/id_personal

# List loaded keys
ssh-add -l

Windows (Git Bash):

# Agent usually starts automatically
# Add keys
ssh-add ~/.ssh/id_personal

# If agent isn't running
eval "$(ssh-agent -s)"

Windows (PowerShell):

# Ensure agent service is running
Get-Service ssh-agent | Start-Service

# Add key (use Windows path)
ssh-add C:\Users\YourName\.ssh\id_personal

Linux/WSL:

# Start agent
eval "$(ssh-agent -s)"

# Add keys
ssh-add ~/.ssh/id_personal

# Add to shell config to start automatically
echo 'eval "$(ssh-agent -s)"' >> ~/.bashrc

---

🌐 Part 3: Adding Keys to Git Services

Process for Each Service

1. Get your public key:

   # Display key to copy
   cat ~/.ssh/id_personal.pub
   
   # Platform-specific copy commands:
   # macOS: pbcopy < ~/.ssh/id_personal.pub
   # Windows Git Bash: clip < ~/.ssh/id_personal.pub
   # Linux: xclip -sel clip < ~/.ssh/id_personal.pub

2. Add to service:

   • GitHub: Settings → SSH and GPG keys → New SSH key
   • GitLab: Preferences → SSH Keys
   • Bitbucket: Personal settings → SSH keys

3. Test connection:

   # Test GitHub
   ssh -T git@github.com
   # Success: "Hi username! You've successfully authenticated..."
   
   # Test with specific key
   ssh -i ~/.ssh/id_personal -T git@github.com

---

⚙️ Approach 1: Per-Project Configuration

How It Works

Each Git repository has its own .git/config file. We configure SSH key and identity per repository.

Setup Steps

# 1. Navigate to your project
cd ~/projects/my-project

# 2. Set Git identity for this project only
git config user.name "Your Name"
git config user.email "your@email.com"

# 3. Set SSH key for this project
git config core.sshCommand "ssh -i ~/.ssh/id_personal"

# Platform-specific path examples:
# Windows: git config core.sshCommand "ssh -i C:/Users/Name/.ssh/id_personal"
# or: git config core.sshCommand "ssh -i C:\\Users\\Name\\.ssh\\id_personal"

What Gets Configured

Check .git/config:

[core]
    sshCommand = ssh -i ~/.ssh/id_personal
[user]
    name = Your Name
    email = your@email.com

Verification:

git config --list --local
# Shows project-specific settings only

Testing:

# Make a commit to verify identity
git commit -m "Test"
git log --oneline -1
# Should show your configured name/email

# Test SSH connection
ssh -i ~/.ssh/id_personal -T git@github.com

---

🗂️ Approach 2: Directory-Based Configuration

How It Works

Use Git's includeIf feature to automatically apply configurations based on where your project is located.

Setup Steps

Step 1: Create organized directories

mkdir -p ~/projects/personal
mkdir -p ~/projects/work

Step 2: Create profile config files

~/.gitconfig-personal:

[user]
    name = Personal Name
    email = personal@email.com
[core]
    sshCommand = ssh -i ~/.ssh/id_personal

~/.gitconfig-work:

[user]
    name = Work Name
    email = work@company.com
[core]
    sshCommand = ssh -i ~/.ssh/id_work

Step 3: Configure global Git config

Edit ~/.gitconfig:

# Default fallback
[user]
    name = Fallback Name
    email = fallback@email.com

# Personal projects
[includeIf "gitdir:~/projects/personal/"]
    path = ~/.gitconfig-personal

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

# Windows path example:
[includeIf "gitdir:C:/Users/Name/projects/personal/"]
    path = C:/Users/Name/.gitconfig-personal

What Happens

1. When you cd ~/projects/personal/my-repo
2. Git automatically loads ~/.gitconfig-personal
3. All Git operations use the personal SSH key and identity
4. No manual configuration needed!

Verification:

cd ~/projects/personal/my-repo
git config --list --show-origin
# Shows config loaded from ~/.gitconfig-personal

---

🔍 Verification & Troubleshooting

Diagnostic Commands

# Check active configuration
git config --list --show-origin

# Check where a specific setting comes from
git config --show-origin user.email
git config --show-origin core.sshCommand

# Test SSH connection
ssh -T git@github.com
ssh -i ~/.ssh/id_personal -T git@github.com

# Debug SSH (verbose mode)
ssh -vT git@github.com

Common Issues & Fixes

Permission Issues:

# Fix SSH key permissions
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/*.pub
chmod 700 ~/.ssh

SSH Agent Issues (macOS):

# Reset keychain integration
ssh-add -A
# Or explicitly add with keychain
ssh-add --apple-use-keychain ~/.ssh/id_personal

SSH Agent Issues (Windows):

# Restart SSH agent service
Stop-Service ssh-agent
Start-Service ssh-agent

includeIf Not Working:

# Check Git version (needs 2.13+)
git --version

# Ensure trailing slash in paths
[includeIf "gitdir:~/projects/personal/"]  # ✓ Correct
[includeIf "gitdir:~/projects/personal"]   # ✗ May not work

# Check file permissions
ls -la ~/.gitconfig-personal

---

📊 Quick Comparison

Aspect	Per-Project	Directory-Based
Setup	Configure each repo manually	One-time setup
Flexibility	Each repo independent	Automatic based on location
Best For	Mixed projects, freelancers	Organized workflows
Maintenance	Manual per repo	Centralized configs
Windows/macOS	Works on both	Works on both

---

✅ Quick Start Checklist

For Both Approaches:

1. Generate SSH keys: ssh-keygen -t ed25519 -C "email" -f ~/.ssh/id_name
2. Add public keys to GitHub/GitLab/Bitbucket
3. Add keys to SSH agent: ssh-add ~/.ssh/id_name
   • macOS: Use --apple-use-keychain flag
4. Test connection: ssh -T git@github.com

For Per-Project (Approach 1):

1. In each project: git config user.name "Name" and git config user.email "email"
2. Set SSH key: git config core.sshCommand "ssh -i ~/.ssh/id_name"
3. Verify: git config --list --local

For Directory-Based (Approach 2):

1. Create directories: ~/projects/personal/, ~/projects/work/
2. Create profile config files: ~/.gitconfig-personal, ~/.gitconfig-work
3. Add includeIf rules to ~/.gitconfig
4. Clone projects into correct directories
5. Verify: git config --list --show-origin

---

🚀 Recommended Workflow

For beginners: Start with Approach 1 - simple and explicit.

For organized work: Use Approach 2 - automatic and scalable.

For mixed environments: Use Approach 2 for organized projects and Approach 1 for exceptions.

Both methods work perfectly on Windows, macOS, and Linux, requiring no SSH alias complexity. The system ensures you always use the correct SSH key and Git identity automatically.

🔄 Alternative Approaches

SSH Configuration Method

For a more traditional SSH-focused approach using host aliases and config files, see our detailed guide:

Learn How to configure multiple Cloud Repositories account in one machine
Covers:

• SSH host aliases and ~/.ssh/config
• Team SSH setup and permissions
• Detailed SSH troubleshooting