gitam

gitam is a small CLI for switching Git user.name and user.email between multiple identities. Use gam or gitam when you need separate Git identities for work, personal, client, or open-source repositories.

Why GAM

• Switch Git users without retyping git config user.name and git config user.email.
• Store work, personal, client, or open-source identities behind memorable flags.
• See whether an account is currently used by the local repository, global Git config, or both.
• Confirm before changing the global Git user, so a local switch does not accidentally become a machine-wide change.
• Add, edit, remove, and use accounts from either direct commands or interactive prompts.
• Configure Git includeIf rules from either direct commands or interactive prompts.
• Generate shell completion for faster account switching.

Installation

npm i -g gitam

Quick Start

Add an account:

gam add github bob [email protected]

Switch the current repository to that account:

gam use github

Switch the global Git user after confirmation:

gam use -g github

Check all commands:

gam -h

You can also use gitam anywhere gam is shown. gam is shorter and recommended, while gitam is useful if another program already owns the gam command on your machine.

AI Agents and Scripts

For automation, prefer explicit non-interactive commands and JSON output:

gam --json
gam list --json
gam __flags --json
gam add github bob [email protected]
gam add github bob [email protected] --force
gam use github
gam use -g github --yes
gam include github --gitdir ~/work/

Use local repository switches by default. Only run gam use -g <flag> --yes when the user explicitly wants to change the global Git identity.

Claude Code Skill

gitam includes a Claude Code project skill at .claude/skills/gitam/SKILL.md. When Claude Code starts in this repository, it can discover the /gitam skill automatically.

Install the same skill globally for your user:

mkdir -p ~/.claude/skills/gitam
cp docs/gitam-skill/SKILL.md ~/.claude/skills/gitam/SKILL.md

More agent setup notes are in docs/ai-agents.md.

Commands

Add an Account

Pass all account fields at once:

gam add github bob [email protected]

Or run gam add and follow the prompts for username, email, and flag:

gam add

When the flag already exists, GAM asks whether to overwrite it. In non-interactive environments, GAM will not overwrite automatically; choose a new flag or use gam edit.

Use --force to overwrite an existing flag in scripts:

gam add github bob [email protected] --force

Edit an Account

gam edit github --username bob
gam edit github --email [email protected]
gam edit github --flag github-work

At least one option is required. Input is trimmed and validated for flag, username, and email.

Use an Account

Change the current repository config:

gam use github

Change the global config:

gam use -g github

gam use <flag> writes to the current repository. gam use -g <flag> writes to the global Git config, shows the current and target global account, and asks for confirmation before writing.

Use --yes to confirm a global switch in a non-interactive script:

gam use -g github --yes

Run gam use without a flag to pick from saved accounts interactively.

Configure includeIf

Configure a global includeIf rule for an account:

gam include github --gitdir ~/work/
gam include github --gitdir-i ~/Work/
gam include github --onbranch main
gam include github --condition "gitdir:~/work/"

Run without arguments to pick an account and condition interactively:

gam include

gam include writes the account to a dedicated config file under ~/.gitam/includes/, then writes includeIf.<condition>.path to the global Git config.

List Accounts

gam list
gam list --json

The table includes a status column with local, global, or local,global for accounts currently in use.

Run gam --json to inspect the current local and global Git identities as JSON.

Remove an Account

Remove by flag:

gam remove github

Remove by list index:

gam remove 1

Run without arguments to show the account list and choose an index or flag interactively:

gam remove

Shell Completion

Generate completion for your current shell:

gam completion

gam completion detects your shell, writes the matching completion file, and prints the line to add to your shell rc file. Supported shells include zsh, bash, fish, and PowerShell.

Completion scripts complete command names and saved account flags for use, include, edit, and remove.

Examples

gam add github bob [email protected]
gam add
gam edit github --email [email protected]
gam add gitlab tom [email protected]
gam use
gam use -g
gam include github --gitdir ~/work/
gam completion