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)

---

Both of these 2 approached requires SSH keys we will see how can we generate them and what are commands to generate them.

Must Read: How to configure SSH

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!

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

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

Let's see how can we add keys to SSH Agent

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

These folders are just containers for your Git repositories. Later: [] Personal repos → ~/projects/personal/* [] Work repos → ~/projects/work/*

Git checks the repo’s path, not the repo name.

Step 2: Create profile config files

touch ~/.gitconfig-personal
touch ~/.gitconfig-work

Then add the below content in each file (replace with the exact values)

Type nano ~/.gitconfig-personal and paste the below content:

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

Type nano ~/.gitconfig-work and paste the below content:

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

They live in your home directory, next to .gitconfig. To view all the file you can use below command

ls -la ~ | grep gitconfig

Step 3: Configure global Git config

Typenano ~/.gitconfig and paste the below content:

# 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