Configuration

Configuration file

gitswitch stores configuration and user data in:

~/.config/gitswitch/
├── config.json       # UI preferences, settings
├── profiles.json     # Profile definitions
└── history.json      # Repo usage history

config.json

Stores UI preferences and feature settings.

{
  "theme": "Nord",
  "nudge_on_cd": true,
  "learning": {
    "min_uses": 3,
    "confidence_threshold": 0.6
  }
}

Fields

Field	Type	Default	Description
theme	string	"Nord"	Active color theme (see Themes section)
nudge_on_cd	boolean	true	Show identity suggestions on cd
learning.min_uses	number	3	Uses before nudging (min)
learning.confidence_threshold	number	0.6	Consistency %age before nudging

Themes

Available themes:

• Nord
• Dracula
• Catppuccin
• Tokyo Night
• Gruvbox
• One Dark
• Solarized
• Monokai
• Material
• Ayu Dark
• Everforest
• Synthwave

Change theme in TUI:

• Press c to cycle through themes

Or edit config.json:

{
  "theme": "Gruvbox"
}

profiles.json

Stores all profile definitions.

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

You can edit manually, but use the CLI when possible:

gitswitch add work "Name" email@example.com
gitswitch remove personal

history.json

Tracks which identity you use in each repo.

{
  "/Users/alice/projects/work-repo": {
    "work": 12,
    "personal": 1
  },
  "/Users/alice/projects/personal-repo": {
    "personal": 8
  }
}

Used for:

• Identity suggestions on cd
• Learning which identity you prefer per-repo

Clear to reset learning:

rm ~/.config/gitswitch/history.json

Environment variables

Custom config directory

export GITSWITCH_CONFIG_DIR=~/.gitswitch
gitswitch  # Uses ~/.gitswitch instead of ~/.config/gitswitch

Integration with git config

gitswitch reads/writes global git config:

~/.gitconfig

Keys modified:

• user.name
• user.email
• user.signingkey (if GPG key set)
• core.sshCommand (if SSH key set)

View active config:

git config --global --list

Or gitswitch:

gitswitch current

SSH key paths

gitswitch expands paths:

• ~ → home directory
• $HOME → home directory
• Absolute paths work as-is

Examples:

gitswitch add work "Alice" alice@company.com \
  --ssh-key ~/.ssh/id_work          # Expands to /Users/alice/.ssh/id_work
  --ssh-key $HOME/.ssh/id_work      # Same
  --ssh-key /Users/alice/.ssh/id_work  # Absolute path

GPG key configuration

gitswitch uses GPG key IDs from your keyring:

# List available keys
gpg --list-secret-keys --keyid-format LONG

# Setup profile
gitswitch add work "Alice" alice@company.com \
  --gpg-key 1234567890ABCDEF

The key must exist in your keyring. If not found, gitswitch will warn but still create the profile (in case you add the key later).

Backup configuration

All gitswitch data is in ~/.config/gitswitch/:

# Backup
cp -r ~/.config/gitswitch ~/backups/gitswitch-backup

# Restore
cp -r ~/backups/gitswitch-backup ~/.config/gitswitch

Troubleshooting

Config not found

Error: config directory not found

Create it:

mkdir -p ~/.config/gitswitch
gitswitch init

Can’t read config file

Error: failed to read config: permission denied

Check permissions:

ls -la ~/.config/gitswitch/
chmod 700 ~/.config/gitswitch
chmod 600 ~/.config/gitswitch/*.json

Profile not found after editing

If you edit profiles.json manually, ensure valid JSON:

cat ~/.config/gitswitch/profiles.json | jq .
# Should not show errors

SSH key not found

Error: ssh key not found

Check path:

ls -la ~/.ssh/id_work
# If not found, the path is wrong or key doesn't exist

Next steps

→ CLI Reference
→ Profiles
→ Quick Start