Profiles

What is a profile?

A profile is a named collection of git identity settings:

• Display name
• Email address
• SSH key (optional)
• GPG signing key (optional)
• GitHub username (optional)

Profile fields

Field	Required	Example	Notes
Nickname	Yes	work	Short name, no spaces. Shown in TUI and CLI.
Full Name	Yes	Alice Smith	Name on commits. Can include spaces.
Email	Yes	alice@company.com	Email on commits. Should match GitHub/git identity.
SSH Key	No	~/.ssh/id_work	Path to SSH private key. Can include ~ or $HOME.
GPG Key	No	1234567890ABCDEF	16-character GPG key ID.
GitHub User	No	alice-work	GitHub username for gh auth switch integration.

Creating profiles

Via TUI

gitswitch
# Press 'a' to add
# Fill in fields with arrow keys + Tab

Via CLI

gitswitch add work "Alice Smith" alice@company.com \
  --ssh-key ~/.ssh/id_work \
  --gpg-key 1234567890ABCDEF \
  --gh-user alice-work

Minimal profile

Only name, email, and nickname are required:

gitswitch add personal "Alice" alice@gmail.com

Profile storage

Profiles are stored at:

~/.config/gitswitch/profiles.json

Example structure:

{
  "profiles": [
    {
      "nickname": "personal",
      "name": "Alice",
      "email": "alice@gmail.com",
      "sshKey": "",
      "gpgKey": "",
      "githubUser": ""
    },
    {
      "nickname": "work",
      "name": "Alice Smith",
      "email": "alice@company.com",
      "sshKey": "~/.ssh/id_work",
      "gpgKey": "1234567890ABCDEF",
      "githubUser": "alice-work"
    }
  ]
}

You can edit this file manually if needed (edit carefully!).

Managing profiles

List all profiles

gitswitch list

Shows all profiles with their email addresses.

Show current profile

gitswitch current

Displays the active profile (nickname and email).

Edit profile

gitswitch
# Select profile, press 'e' to edit

Or CLI (when available):

gitswitch edit work
# (Note: currently only TUI editing is supported)

Delete profile

gitswitch
# Select profile, press Ctrl+D to delete (in edit mode)

Or CLI:

gitswitch remove work

Field specifics

Nickname

• No spaces or special characters (keep it simple)
• Lowercase recommended (easier to type)
• Examples: work, personal, clienta, oss

Full Name

• Can include spaces (e.g., Alice Smith)
• Appears on every commit you make
• Should match GitHub for better attribution

Email

• Must be a valid email address
• Should match your GitHub account (or work/personal accounts)
• Appears on every commit you make
• Can differ from SSH key email (git config and SSH are separate)

SSH Key

• Path to private key (not public key)
• Must be readable by your user
• Can use ~ for home directory
• Optional — if not set, SSH agent handles key selection

Example paths:

• ~/.ssh/id_work
• /Users/alice/.ssh/id_rsa
• $HOME/.ssh/id_custom

GPG Key

• 16-character GPG key ID (from gpg --list-secret-keys --keyid-format LONG)
• Must exist in your keyring (from gpg --list-keys)
• Optional — if not set, no signing key is forced
• Example: 1234567890ABCDEF

To find your GPG key ID:

gpg --list-secret-keys --keyid-format LONG

# Output:
# sec   rsa4096/1234567890ABCDEF 2023-01-15 [SC]
#       1234567890ABCDEF1234567890ABCDEF12345678

Use the 16-character ID after the slash.

GitHub User

• Your GitHub username (not email)
• Used for gh auth switch integration
• Optional — if not set, GitHub CLI is not switched
• Example: alice-work or alice-personal

Check your GitHub username:

gh auth status
# Shows your authenticated accounts

Profile scenarios

Freelancer with multiple clients

gitswitch add clienta "Your Name" you@clienta.com \
  --ssh-key ~/.ssh/id_clienta
gitswitch add clientb "Your Name" you@clientb.com \
  --ssh-key ~/.ssh/id_clientb
gitswitch add personal "Your Name" you@personal.com

Switch before working:

cd ~/clienta-project
gitswitch clienta

cd ~/clientb-project
gitswitch clientb

Developer with work + OSS

gitswitch add work "Alice" alice@company.com \
  --ssh-key ~/.ssh/id_work \
  --gh-user alice-work

gitswitch add oss "Alice" public@github.com \
  --ssh-key ~/.ssh/id_oss \
  --gh-user alice-oss

Contractor with multiple GitHub accounts

gitswitch add personal "Alice" alice@gmail.com \
  --ssh-key ~/.ssh/id_personal \
  --gh-user alice

gitswitch add work "Alice" alice@company.com \
  --ssh-key ~/.ssh/id_work \
  --gh-user alice-corp

Each gitswitch command switches git identity, SSH key, and GitHub account.

Next steps

→ CLI Reference
→ Configuration
→ Quick Start