Quick Start

Two commands. That's the whole thing.

gitswitch            # 1. first run — sets up git/gh, connects your account
gitswitch pin work   # 2. claim a repo

Below is what actually happens, in case you like knowing.

1. First run

gitswitch

On a machine with no profiles yet, this checks for git and gh before anything else and offers to install whichever's missing, then opens a short wizard — it scans your gh logins and ~/.ssh/ keys and offers to import what it finds, or log in with GitHub fresh.

You can also do the login step directly, any time, instead of through the wizard:

gitswitch login

Opens a GitHub login in your browser (device flow — you paste a short code, GitHub does the rest):

  Open this URL in your browser:

    https://github.com/login/device

  Then enter the code:

    A1B2-C3D4

  Waiting for authorization...

  ✓  Logged in as alice-corp (github.com)
  ✓  Profile "alice-corp" created
  ✓  Token stored in keychain

Your name, email, and GitHub username are filled in for you. Run it again for each account you have:

gitswitch login                      # personal
gitswitch login --profile work       # work, with a nicer nickname
gitswitch login --host github.acme.com   # GitHub Enterprise

No SSH keys to generate, nothing to paste into a settings page. If you'd rather bring your own keys, see SSH Keys — or type a profile in by hand:

gitswitch add work "Alice Smith" alice@company.com --gh-user alice-corp

See them all:

gitswitch list

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

The ✓ is your current global identity.

2. Claim your repos

cd ~/work/api
gitswitch pin work

✓ Pinned 'work' to this repo — Alice Smith <alice@company.com> (local git config; global identity unchanged)

Every commit in that repo now uses work. Every push uses work's token. Every gh pr create acts as work. Your global identity — and every other repo — is left exactly as it was.

Do it once per repo and you are finished thinking about this:

cd ~/personal/blog     && gitswitch pin personal
cd ~/clients/acme/api  && gitswitch pin acme

Changed your mind? gitswitch unpin.

Already configured a repo by hand years ago? Run gitswitch pin with no name. gitswitch reads the repo's existing user.email, matches it to one of your accounts, and fills in the rest.

Shell integration (optional, but worth it)

gitswitch shell

A short wizard with three steps, each one explaining itself and each one skippable:

Then reload your shell:

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

Everything gitswitch writes lives between # gitswitch markers in your rc file. Re-running shell replaces that block in place — it never appends a second copy.

Switching by hand

Pins cover the repos you own. For everything else:

gitswitch work        # switch global identity, right now
gitswitch current     # who am I in here?

work — Alice Smith <alice@company.com>  (pinned to this repo)

That parenthetical matters — it tells you why you're that person. See Scopes.

The interactive UI

gitswitch

Three tabs — Accounts, Utilities, Settings — switched with 1 2 3, tab, or a mouse click. Yes, the mouse works.

First launch with no accounts runs a short onboarding wizard — it scans your gh logins and ~/.ssh/ keys and offers to import what it finds.

Where next

• Scopes — global, repo, and terminal identities, and who wins
• Multi-account GitHub — the full two-account walkthrough
• Identity Awareness — the nudges, and how they're learned
• Troubleshooting — when a push still goes out wrong