Documentation

Install

npm install -g giman

Requires Node.js 18+.

Quick start

1. Initialize (creates ~/.giman/config.json, detects existing config):

gid init

2. Map directories to identities so Git uses the right identity per folder:

gid dir add ~/dev/personal --identity personal
gid dir add ~/dev/work --identity work

3. Check current identity in the current directory:

gid status

Commands reference

Note: gid id was previously named gid identity. The old name still works as an alias, so existing scripts keep running, but gid id is the documented form.

Command details

gid init#

One-time interactive setup. If you don't have config yet, it walks you through creating your first identity (ID, name, email, SSH key path, SSH host alias). It then creates ~/.giman/config.json, writes per-identity Git configs, updates ~/.gitconfig with includeIf rules, and optionally updates ~/.ssh/config with Host blocks.

If config already exists: It detects your existing identities and asks whether to apply them now (write to ~/.ssh/config and ~/.gitconfig). Use this after cloning your config to a new machine or to re-apply after manual edits.

First time setup, or after moving to a new machine. Run once before using other commands.

gid init

gid status#

Shows which identity is active for your current working directory. It looks up your CWD in the directory mappings and prints the matching identity (id, name, email), or tells you no identity is mapped and suggests gid dir add . --identity <id>.

To confirm which account Git will use for commits and SSH in the current folder.

cd ~/dev/work/project
gid status
# Identity: work — John Doe <john@company.com>

gid apply#

Writes the current state of ~/.giman/config.json out to the system: updates ~/.ssh/config (Host blocks for each identity), writes identity gitconfigs under ~/.giman/gitconfigs, and refreshes ~/.gitconfig includeIf rules. It will prompt before modifying ~/.ssh/config.

After you've added/edited identities or directory mappings (e.g. via gid id add, gid dir add, or by editing the JSON) and want those changes to take effect. Also useful if you manually changed ~/.ssh/config or ~/.gitconfig and want to re-sync from GiMan.

gid apply

gid clone <repo-url> [directory]#

Clones a repository using an SSH URL (e.g. git@github.com:user/repo.git). Prompts you to select an identity (profile) from your configured identities; then rewrites the URL to use that identity's SSH host alias and runs git clone. Optional second argument is the target directory (same as git clone <url> [directory]).

When you want to clone a repo and have GiMan prompt you to pick which account/identity to use, without remembering or typing the SSH host alias.

gid clone git@github.com:someone/repo.git
# Prompts: Select identity (profile) for this clone: personal / work / ...

gid clone git@github.com:someone/repo.git ./my-repo
# Same, but clones into ./my-repo

gid id list#

Lists every identity in your config. For each identity it shows: id, name, email, SSH key path (tilde form), SSH host alias, and which directories are mapped to it.

To see all identities and their mappings at a glance.

gid id list

gid id add#

Interactive flow to add a new identity. Prompts for: identity ID (e.g. personal, work), display name, email, and SSH key (path or generate new). Saves to config and optionally updates ~/.ssh/config. The new identity has no directories until you run gid dir add.

When you need a second (or third) GitHub account or Git identity on the same machine.

gid id add

gid id edit <id>#

Edits an existing identity by id. Prompts for name, email, and SSH host alias (existing values pre-filled). Updates only those fields in config; it does not change the SSH key path. After editing, run gid apply if you want SSH/gitconfig rewritten immediately.

You changed your name/email or want to rename the SSH host alias (e.g. github-work → github-company).

gid id edit work

gid id remove <id>#

Removes the identity with the given id from config and removes all directory mappings that pointed to it. Then rewrites ~/.ssh/config so that Host block is gone.

You no longer use that account or identity on this machine.

gid id remove work

gid id show <id>#

Prints full details for one identity: name, email, SSH key path, SSH host alias, and the list of directories mapped to it. Exits with an error if the id doesn't exist.

To double-check one identity's settings and which paths use it.

gid id show personal

gid dir add <path> --identity <id>#

Maps a directory path to an identity. Any repo inside that path (including subdirectories) will use that identity's user.name, user.email, and SSH key. Path can be absolute or use ~; . means current directory. The identity must already exist (from gid init or gid id add).

Options: -i, --identity <id> (required) — the identity id to attach the path to.

When you want "everything under this folder" to use a specific account (e.g. ~/dev/personal → personal, ~/dev/work → work).

gid dir add ~/dev/personal --identity personal
gid dir add . --identity work

gid dir remove <path>#

Removes the directory mapping for the given path. The path is resolved the same way as for dir add (e.g. ~ expanded). Repos under that path will no longer auto-use an identity from GiMan until you add a mapping again.

You moved a project or no longer want that folder to use a specific identity.

gid dir remove ~/dev/work

gid dir list#

Lists all directory-to-identity mappings. For each identity that has directories, it prints the identity id and the paths mapped to it.

To see which folders are tied to which identity.

gid dir list

Examples

Add and use two identities

# One-time setup
gid init
# Create "personal" (name, email, SSH key path)

# Create "work" (name, email, SSH key path)
gid dir add ~/dev/personal --identity personal
gid dir add ~/dev/work --identity work
gid apply

Clone with the right identity

Option 1 — use gid clone (prompts for profile):

gid clone git@github.com:username/my-repo.git
# Prompts you to select an identity (personal, work, …), then clones with that identity

Option 2 — use the SSH host alias directly:

cd ~/dev/personal
git clone git@github-personal:username/my-repo.git

cd ~/dev/work
git clone git@github-work:company/project.git

Commits and push (automatic in mapped dirs)

Inside a mapped directory, user.name and user.email are set automatically; SSH uses the right key for push.

cd ~/dev/work/project

git config user.email
# john@company.com

git commit -m "feat: add feature"
# Committed as: John Doe <john@company.com>

git push origin main
# Uses the correct SSH key

Fix existing repo to use an identity

Point the remote at the identity's SSH host alias:

cd ~/dev/personal/existing-repo

git remote set-url origin git@github-personal:username/existing-repo.git

git remote -v
# origin git@github-personal:username/existing-repo.git (fetch)
# origin git@github-personal:username/existing-repo.git (push)

List and inspect

gid id list

gid id show personal

gid dir list

gid status

Config location

• GiMan config: ~/.giman/config.json (identities, SSH key paths, directory mappings).
• Git: ~/.gitconfig gets includeIf directives when you run gid init, gid id add, gid dir add, or gid apply.
• SSH: ~/.ssh/config gets Host blocks for each identity (e.g. github-personal, github-work) when you run those commands (with your permission).

License

MIT.