git-acct

A command-line tool for managing multiple Git accounts. Support for distinguishing work and personal accounts, and using different accounts for different repositories.

中文文档

Note: This tool modifies local Git configuration. Make sure to backup important projects before using.

Installation

pnpm install -g git-acct

Usage

Command Overview

gam <command> [options]

Account Management

Command	Description
gam add	Interactively add a new account
gam list / gam ls	List all accounts
gam remove <alias>	Remove an account
gam default [alias]	View or set default account
gam switch <alias>	Switch global Git account

Repository Management

Command	Description
gam bind <alias>	Bind current repository to an account
gam unbind	Unbind current repository
gam repos	List all bound repositories
gam status	View current repository account status
gam auto	Auto apply repository configuration
gam use <alias>	Use specified account in current repo (local only)

Options

Option	Description
-h, --help	Show help information
-v, --version	Show version
--work	Filter work accounts
--personal	Filter personal accounts

Quick Start

First Time Use

The tool automatically detects and imports existing Git user configuration:

gam list

If ~/.gitconfig already has a [user] section, it will automatically create an account named default.

1. Add Account

gam add

Follow the prompts to enter:

• Account alias (recommended to use work/personal to distinguish work and personal)
• Git username
• Git email
• SSH key path (optional)

Account type is auto-detected from alias:

• Contains work, 公司, 工作 → work account
• Contains personal, 个人, 私有 → personal account
• Others → other type

2. View Account List

gam list

Example output:

Git Account List (Git账号列表)

● ★ work (work)
      John Doe <john@company.com>

  personal (personal)
      John Doe <john@personal.com>

Legend (图例):
  ● Current (当前使用)
  ★ Default account (默认账号)

3. Switch Global Account

gam switch work

4. Bind Repository to Account

Run in project directory:

gam bind work

After binding, the repository will use the specified account configuration.

5. View Repository Status

gam status

Example output:

Current Repository Status (当前仓库状态)

Repository path (仓库路径): /Users/xxx/projects/my-project
Repository name (仓库名称): my-project

Global config (全局配置):
  John Doe <john@personal.com>

Local config (本地配置):
  John Doe <john@company.com>

Bound account (绑定账号):
  work (work)
  John Doe <john@company.com>

Sync status (同步状态): ✓ Synced (已同步)

SSH Key Configuration

Important: gam currently only stores SSH key paths and does not automatically configure SSH. For multi-account scenarios with different SSH keys, manual configuration is required.

Single Account - No Configuration Needed

If you only have one Git account or multiple accounts using the same SSH key:

# Default SSH key location: ~/.ssh/id_ed25519
# Git will use it automatically

gam add
# SSH key path: leave empty to skip

Multiple Accounts with Different Keys - Manual Configuration Required

If you have multiple Git accounts, each using a different SSH key:

Step 1: Generate SSH Keys

# Generate key for work account
ssh-keygen -t ed25519 -C "work@example.com" -f ~/.ssh/id_ed25519_work

# Generate key for personal account
ssh-keygen -t ed25519 -C "personal@example.com" -f ~/.ssh/id_ed25519_personal

Step 2: Add Public Keys to Git Providers

# View public key
cat ~/.ssh/id_ed25519_work.pub

Add to:

• GitHub: Settings → SSH and GPG keys → New SSH key
• GitLab: Preferences → SSH Keys
• Gitee: Settings → SSH Public Keys

Step 3: Configure SSH Config

Edit ~/.ssh/config file:

# Work account - GitHub
Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work

# Personal account - GitHub
Host github-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal

Step 4: Add Accounts with gam

gam add
# Alias: work
# Username: Work User
# Email: work@company.com
# SSH key path: ~/.ssh/id_ed25519_work

gam add
# Alias: personal
# Username: Personal User
# Email: personal@gmail.com
# SSH key path: ~/.ssh/id_ed25519_personal

Step 5: Clone Repositories Using Host Alias

# Clone using work account
git clone git@github-work:company/project.git

# Clone using personal account
git clone git@github-personal:personal/project.git

SSH Key Storage in gam

Scenario	SSH Config	gam SSH Path
Single account	Not needed	Can be empty
Multiple accounts, same key	Not needed	Can be empty
Multiple accounts, different keys	Required	Recommended (for reference)

Use Cases

Case 1: Separate Work and Personal Projects

# Add work account
gam add
# Alias: work, Username: WorkName, Email: work@company.com

# Add personal account
gam add
# Alias: personal, Username: PersonalName, Email: personal@gmail.com

# Bind work account in work project
cd /path/to/work-project
gam bind work

# Bind personal account in personal project
cd /path/to/personal-project
gam bind personal

Case 2: Auto-sync Repository Configuration

When you clone a previously bound repository, use auto command:

cd /path/to/bound-repo
gam auto

Configuration File

Configuration is stored in ~/.gitconfig using custom sections:

[user]
    name = Current User
    email = current@example.com

[gam "work"]
    name = John Doe
    email = john@company.com
    type = work
    sshKeyPath = ~/.ssh/id_ed25519_work
    createdAt = 2024-01-01T00:00:00.000Z
    updatedAt = 2024-01-01T00:00:00.000Z

[gam "personal"]
    name = John Doe
    email = john@personal.com
    type = personal
    createdAt = 2024-01-01T00:00:00.000Z
    updatedAt = 2024-01-01T00:00:00.000Z

[gam-default]
    account = work

[gam-repo "/Users/xxx/projects/my-project"]
    accountAlias = work
    createdAt = 2024-01-01T00:00:00.000Z

Cross-platform Support: macOS, Windows, and Linux

• macOS/Linux: ~/.gitconfig
• Windows: %USERPROFILE%\.gitconfig

API Usage

Besides CLI, can also be used as a Node.js module:

import {
  listAccounts,
  addAccount,
  switchAccount,
  bindRepoToAccount,
  checkRepoConfig,
} from 'git-acct';

// List all accounts
const accounts = listAccounts();

// Add account
addAccount('John Doe', 'john@example.com', 'personal', 'personal');

// Switch account
switchAccount('personal', 'global');

// Bind repository
bindRepoToAccount('/path/to/repo', 'personal');

// Check repository configuration
const status = checkRepoConfig('/path/to/repo');

License

MIT