Identity Awareness

What it does

gitswitch learns which identity you use in each repository. When you switch to a repo, it nudges you if the current identity looks wrong.

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

Why you need this

Identity mistakes are easy to make:

• You forget to switch before committing
• You work on many repos and lose track of which identity each uses
• You only realize the mistake after pushing

Identity awareness prevents these mistakes by:

1. Remembering which identity you use in each repo
2. Suggesting (or auto-switching to) the right identity
3. Making it a one-keypress fix

How it works

Learning phase

Each time you enter a git repo, gitswitch checks:

1. What identity is currently active?
2. Is this a new repo or have I been here before?
3. Record this usage in ~/.config/gitswitch/history.json

After using an identity in a repo ≥3 times with ≥60% consistency, gitswitch recognizes the pattern.

Nudging

Once a pattern is clear, you get a nudge:

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

• Press y to switch
• Press n or just hit enter to skip
• Non-blocking — you can proceed either way

This happens automatically when you:

• Open a new terminal in the repo
• cd into the repo (with shell integration installed)

Pinning

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

cd ~/my-work-repo
gitswitch pin work

Now the nudge becomes a permanent rule — you’ll always get the same suggestion, even if you occasionally use a different identity.

Usage

Install shell integration

For automatic nudges on cd:

gitswitch install

This detects your shell (Starship, oh-my-zsh, Powerlevel10k, raw zsh/bash/fish) and adds the nudge hook.

View history

History is stored at:

~/.config/gitswitch/history.json

Example entry:

{
  "/Users/alice/work-project": {
    "work": 12,
    "personal": 2
  }
}

This repo has been accessed 12 times with work identity and 2 times with personal.

Clear history

To reset learning for a repo:

# Edit the history file manually, or
rm ~/.config/gitswitch/history.json
# Clears all history (starts learning from scratch)

Pinning

Pin an identity to a repo

cd ~/my-work-repo
gitswitch pin work

Creates a .gitswitch file in the repo (gitignore it):

echo .gitswitch >> .gitignore

Remove pin

gitswitch unpin

Falls back to usage-based learning.

Pin with multiple remotes

If you clone the same repo to different locations, each location learns separately:

# Location 1
cd ~/projects/work-project
gitswitch pin work

# Location 2
cd ~/backups/work-project-backup
gitswitch pin work

# Each maintains its own identity preference

Customization

Adjust learning threshold

Currently: ≥3 uses + ≥60% consistency

To change this, edit ~/.config/gitswitch/config.json:

{
  "learning": {
    "min_uses": 3,
    "confidence_threshold": 0.6
  }
}

Disable nudges

To turn off nudges globally, edit ~/.config/gitswitch/config.json:

{
  "nudge_on_cd": false
}

Clear all learning

rm ~/.config/gitswitch/history.json

Examples

Multi-repo workflows

Contractor with 3 client repos:

cd ~/clienta-project
# First time, no nudge (learning)
gitswitch clienta

cd ~/clientb-project
gitswitch clientb

cd ~/clienta-project
# gitswitch now suggests clienta (if on 3rd visit)

cd ~/personal-project
# gitswitch suggests personal

Using pins

Some repos you always want pinned:

# Work repos — pin them
cd ~/company-repo
gitswitch pin work

cd ~/api-project
gitswitch pin work

# Personal repos — pin them
cd ~/github-clone
gitswitch pin personal

Troubleshooting

Nudges not appearing on cd

Check:

1. Did you run gitswitch install?
2. Is your shell supported? (Starship, oh-my-zsh, Powerlevel10k, zsh, bash, fish)
3. Did you reload your shell?

gitswitch install
source ~/.zshrc  # or open new terminal

Wrong nudge suggestions

The learning threshold might be too low. Check ~/.config/gitswitch/history.json to see usage counts.

If a wrong identity has too many uses, manually edit the history or use:

rm ~/.config/gitswitch/history.json

This resets learning for all repos.

Pin file conflicts

If .gitswitch file conflicts with something:

# Edit gitswitch config to use a different filename
# (not currently supported, would need code change)

For now, use the learned nudges instead of pinning.

Next steps

→ Shell Integration
→ Quick Start
→ Real-world Scenarios