Shell Integration

What it does

One command sets up three features at once:

gitswitch install

1. Prompt segment — shows your active git identity in your shell prompt
2. Identity nudge — suggests the right identity when you cd into a repo
3. Tab completion — completes gitswitch commands and profile names

Installation

gitswitch install

Detects your shell automatically and configures:

Shell	Configuration
Starship	Adds [custom.gitswitch] block to ~/.config/starship.toml
oh-my-zsh	Creates plugin at ~/.oh-my-zsh/custom/plugins/gitswitch/
Powerlevel10k	Prints manual step for ~/.p10k.zsh
Raw zsh/bash/fish	Appends directly to rc file

Reload shell

After running gitswitch install:

source ~/.zshrc   # zsh
source ~/.bashrc  # bash
source ~/.config/fish/config.fish  # fish

Or simply open a new terminal.

Prompt segment

Shows your active git identity in your shell prompt.

Example

Before:

~/my-project $

After (with gitswitch):

~/my-project [work: alice@company.com] $

The segment only appears when you’re inside a git repo.

Format

The prompt shows:

• Profile nickname (e.g., work)
• Email address (e.g., alice@company.com)

Customization

With Starship

Edit ~/.config/starship.toml:

[custom.gitswitch]
command = "gitswitch current --short"
when = "git rev-parse --git-dir 2>/dev/null"
symbol = "🔑 "
format = "[$symbol$output]($style) "
style = "bold 208"  # Orange

Change the symbol, color, or format as desired.

With oh-my-zsh

Edit ~/.oh-my-zsh/custom/plugins/gitswitch/gitswitch.plugin.zsh:

# Customize the prompt function
GITSWITCH_PROMPT_SYMBOL="🔑 "
GITSWITCH_PROMPT_COLOR="%F{208}"

With raw zsh/bash/fish

Edit your rc file directly:

# In ~/.zshrc or ~/.bashrc
PROMPT='%F{208}[$(gitswitch current)]%f $ '  # Zsh
PS1='\[$(gitswitch current)\] $ '             # Bash

Identity nudge

When you cd into a repo, gitswitch suggests the identity you usually use there.

Example

$ cd ~/work-project
gitswitch: this repo usually uses work <alice@company.com> — switch? [y/N]

Press y to switch, or just hit enter to skip. Non-blocking.

How it learns

Nudges appear after you’ve used an identity in a repo:

• ≥3 times with ≥60% consistency

gitswitch records each cd into a repo and remembers which identity was active.

Disable nudges

If you find nudges annoying:

# Edit ~/.config/gitswitch/config.json
{
  "nudge_on_cd": false
}

Or disable per-shell:

oh-my-zsh:

# Comment out or remove the nudge call in the plugin

Starship:

# Remove the nudge hook from starship.toml

Tab completion

Completes gitswitch commands and profile names.

Usage

$ gitswitch <TAB>
add      current  help     install  list     pin      remove   switch   version

$ gitswitch w<TAB>
work     # (if you have a 'work' profile)

Supported shells

• zsh — automatic if installed
• bash — automatic if installed
• fish — automatic if installed

Troubleshooting

Prompt segment not showing

Check:

1. Is gitswitch install complete?
2. Did you reload your shell?
3. Are you in a git repo?

# Test manually
gitswitch current

# Should show your active profile

Nudges not appearing

Check:

1. Is shell integration installed? (gitswitch install)
2. Are you in a git repo?
3. Have you used an identity in this repo ≥3 times?

# Check history
cat ~/.config/gitswitch/history.json

Starship doesn’t show the segment

Starship might not have loaded the config. Reload:

# Force starship to reload
pkill starship

# Or restart your terminal

Completion not working

Ensure you’re using a supported shell version:

bash --version  # Bash 4+
zsh --version   # Zsh 5+
fish --version  # Fish 3+

If upgrading doesn’t help, reinstall:

gitswitch install
source ~/.zshrc  # or .bashrc

Advanced customization

Custom prompt function

You can write your own prompt function:

# In ~/.zshrc
gitswitch_prompt() {
  local current=$(gitswitch current)
  if [ -n "$current" ]; then
    echo "[$current]"
  fi
}

PROMPT='$(gitswitch_prompt) $ '

Conditional nudge

Only nudge in certain directories:

# In shell plugin
if [[ $PWD == *"work"* ]]; then
  gitswitch nudge  # (if this command existed)
fi

Next steps

→ Quick Start
→ Real-world Scenarios
→ CLI Reference