git-auto-switch 0.2.0

Manage multiple GitHub accounts with automatic identity switching based on workspace folders

A CLI tool for managing multiple GitHub accounts with automatic identity switching based on workspace folders.

Features

• Manage multiple GitHub accounts with separate SSH keys
• Multiple workspaces per account - map several folders to the same identity
• Automatic Git identity switching based on workspace folders
• Pre-commit hook to prevent wrong-email commits
• SSH key validation and GitHub authentication check during setup
• Audit repositories and auto-fix identity issues
• Automatic remote URL rewriting (HTTPS to SSH)
• Show current active account for any directory

Requirements

• Bash 3.2+
• Git 2.13+ (for conditional includes)
• jq (JSON processor)

Installation

Quick Install (curl)

curl -fsSL https://raw.githubusercontent.com/luongnv89/git-auto-switch/main/install-curl.sh | bash

To uninstall:

curl -fsSL https://raw.githubusercontent.com/luongnv89/git-auto-switch/main/install-curl.sh | bash -s uninstall

pip / uv

pip install git-auto-switch
# or
uv pip install git-auto-switch

npm

npm install -g git-auto-switch

From Source

git clone https://github.com/luongnv89/git-auto-switch.git
cd git-auto-switch

# Install dependencies
brew install jq  # macOS
# or: sudo apt install jq  # Ubuntu/Debian

# Install CLI globally
make install

Quick Start

# Initialize with your first account
git-auto-switch init
# or use the short alias:
gas init

# Add more accounts
gas add

# Show current active account
gas current
# or:
gas whoami

# List all configured accounts
gas list

# Validate configuration
gas validate

# Audit repositories for identity issues
gas audit

# Audit and auto-fix issues
gas audit --fix

# Apply configuration after manual changes
gas apply

Commands

Command	Description
init	Initialize configuration (first-time setup)
add	Add a new account interactively
remove [id]	Remove an account
list	List all configured accounts
apply [id]	Apply configuration to system, or a single account (id or ssh_alias) to the current repository
validate	Validate configuration and check for issues
audit [--fix]	Audit repositories for identity mismatches (--fix to auto-fix)
current	Show current active account for this directory (alias: whoami)
help	Show help message
version	Show version

How It Works

1. SSH Keys: Uses separate SSH keys for each account (generates ed25519 keys if needed)
2. SSH Config: Adds host aliases (e.g., gh-work, gh-personal) to ~/.ssh/config
3. Git Config: Uses includeIf.gitdir: to auto-switch identity based on workspace
4. Pre-commit Hook: Validates email before each commit to prevent mistakes
5. Remote Rewriting: Converts [e-mail] to git@gh-alias for proper SSH key usage

Workflow

Adding a New Account

When you run gas add, the tool will:

1. Prompt for account details (name, workspaces, SSH key, Git identity)
2. Validate SSH key exists and test GitHub authentication
3. Automatically proceed if validation passes (no manual confirmation needed)
4. Apply configuration immediately
5. Ask if you want to add another account

Checking Current Account

$ gas current

========================================
  Current Account: work
========================================

  Account ID:  work
  Git Name:    John Doe
  Git Email:   [e-mail]
  SSH Alias:   gh-work

  Directory:   /home/user/workspace/work/project

  Workspaces:
    - ~/workspace/work
    - ~/projects/company

Applying an Account to the Current Repository

Configure a single repository to use a specific account, regardless of where the repository lives on disk. Useful for one-off repos that sit outside any configured workspace, or when you want to override the workspace default.

$ cd ~/some/repo
$ gas apply gh-work       # by SSH alias
# or
$ gas apply work          # by account ID

This sets the repository's local user.name and user.email, ensures the SSH host alias is present in ~/.ssh/config, and rewrites the origin remote to use the alias (e.g. [e-mail]:user/repo.git → git@gh-work:user/repo.git).

Local Git config takes precedence over the global includeIf rules, so this works for repos inside and outside configured workspaces.

Fixing Issues

The audit --fix command automatically fixes:

• Email mismatches: Removes local user.email so global includeIf takes over
• Wrong remotes: Rewrites [e-mail] to use the correct SSH alias

$ gas audit --fix

Issues in: /home/user/workspace/work/repo1
  Email:
    Expected: [e-mail]
    Actual:   [e-mail]
  Fixed: Removed local user.email (will use global includeIf)

Configuration

Configuration is stored in ~/.git-auto-switch/config.json:

{
  "version": "1.0.0",
  "accounts": [
    {
      "id": "work",
      "name": "Work Account",
      "ssh_alias": "gh-work",
      "ssh_key_path": "~/workspace/work/.ssh/id_ed25519",
      "workspaces": [
        "~/workspace/work",
        "~/projects/company"
      ],
      "git_name": "John Doe",
      "git_email": "[e-mail]"
    }
  ]
}

Multiple Workspaces

Each account can have multiple workspace folders. All repositories within any of these folders will use the same Git identity and SSH key.

Use cases:

• Separate folders for different projects under the same account
• Client work spread across multiple directories
• Open source contributions in a dedicated folder

Adding workspaces during setup:

Workspace folder [~/workspace/work]: ~/workspace/work
Add another workspace? (leave empty to continue): ~/projects/company
Add another workspace? (leave empty to continue):

Managing workspaces in the edit menu:

Options:
  [2]   Manage workspaces (add/remove)

Workspace action: a
New workspace folder: ~/freelance/client-a

Example output from gas list:

[work] Work Account
  Git:    John Doe <[e-mail]>
  SSH:    gh-work
  Workspaces:
    - ~/workspace/work
    - ~/projects/company
    - ~/freelance/client-a

Cloning Repositories

Always use the SSH alias when cloning:

# For work account
git clone git@gh-work:org/repo.git

# For personal account
git clone git@gh-personal:user/repo.git

Existing repositories with [e-mail] remotes will be automatically rewritten when you run gas apply or gas audit --fix.

Rollback

Backups are created automatically before any changes and stored in ~/.git-auto-switch/backup/<timestamp>/:

# List backups
ls ~/.git-auto-switch/backup/

# Restore SSH config
cp ~/.git-auto-switch/backup/<timestamp>/ssh_config ~/.ssh/config

# Restore Git config
cp ~/.git-auto-switch/backup/<timestamp>/gitconfig ~/.gitconfig

Development

See CONTRIBUTING.md for development setup and guidelines.

# Install development dependencies
brew install shellcheck bats-core jq

# Run linter
make lint

# Run tests (59 tests)
make test

# Run both
make all

License

MIT