Quick Start

This page covers adding your first profiles and switching between them.

1. First run

gitswitch

On first launch with no existing profiles, gitswitch reads your current git config --global user.name and git config --global user.email and saves them as a profile named default. Then it opens the TUI.

2. Add profiles

Via CLI

# Git identity only
gitswitch add personal "Alice Smith" alice@gmail.com

# With SSH key
gitswitch add work "Alice Smith" alice@company.com \
  --ssh-key ~/.ssh/id_work

# Full setup: SSH key + GPG signing + GitHub CLI
gitswitch add corp "Alice Smith" alice@corp.com \
  --ssh-key ~/.ssh/id_corp \
  --sign-key ABCD1234EF567890 \
  --gh-user alice-corp

Via TUI

Press a in the TUI to open the add-profile form. Navigate fields with Tab. Press Enter to save.

3. Switch profiles

Quick switch (no UI)

gitswitch work

Output:

✓ Switched to 'work' — Alice Smith <alice@company.com>

Interactive TUI

gitswitch

4. Check current identity

gitswitch current

work — Alice Smith <alice@company.com>

5. Set up shell integration

gitswitch install

This runs an interactive wizard that installs:

• Prompt segment — shows active identity when inside a git repo
• Identity nudge — on cd into a repo, prompts you to switch if a different identity is usually used there
• Tab completion — completes gitswitch commands and profile nicknames

After running, reload your shell:

source ~/.zshrc   # zsh
source ~/.bashrc  # bash
# or open a new terminal

6. Pin a repo to an identity

If you always want a specific profile in a repo, pin it:

cd ~/work/my-project
gitswitch pin work

Pinned 'work' to this repo

From now on, gitswitch recommend (used by the shell nudge hook) always returns work for that repo, regardless of usage history.

Remove the pin:

gitswitch unpin

Unpinned — identity recommendation now based on usage history

List all profiles

gitswitch list

✓  personal        Alice Smith <alice@gmail.com>
   work            Alice Smith <alice@company.com>
   corp            Alice Smith <alice@corp.com>

The ✓ marks the currently active profile.

Next steps

• Commit Identity
• SSH Keys
• Shell Integration
• CLI Reference