Overview

Switch Git identities without guessing

gitrole helps you keep work, personal, and client commits from bleeding into each other. Save a role, switch to it, and check the repo before you commit or push.

See the workflow Install after you understand it

What problem it solves

If you move between work, personal, freelance, or client repositories, it is easy to use the wrong Git identity without noticing.

Wrong commits

Wrong-author commits

You meant to commit as your work identity, but Git used your personal name and email.

Wrong pushes

Wrong-account pushes

The repo looks right locally, but your SSH setup pushes through the wrong GitHub account.

Too much manual setup

Too much Git config switching

You keep editing user.name, user.email, or remotes by hand every time you change codebases.

What gitrole does

One small workflow

Save a role, switch the repo to it, then run a quick check before you commit or push.

How it works

Do not think of gitrole as a system first. Think of it as a simple workflow:

Step 1

Save a role

Create one saved role per identity, such as work, personal, or client-acme.

Step 2

Switch to it

Apply that role globally or only in the repository you are working in.

Step 3

Check before you push

Run gitrole status for the fast daily check. Run gitrole doctor when something looks wrong.

Tiny real example

This is the smallest useful flow for a repo that should use a local override:

gitrole add work --name "Alex Developer" --email "alex@work.example"
gitrole use work --local
gitrole status

What that does:

Saves a role named work
Applies it only to the current repository
Shows what this repo will actually use before the next commit

If status looks clean, you have the basic setup working.

Status vs doctor

Make this distinction early:

Fast daily check

`gitrole status`

Use this before you commit or push. It answers "does this repo look right?" without a lot of detail.

Full explanation

`gitrole doctor`

Use this when the repo looks wrong, pushes use the wrong account, or you need to understand what is out of sync.

gitrole warns on violated expectations, not assumptions. githubUser checks SSH auth, githubHost checks the remote host, and remote owner/repository is context by default.

Install

Install comes after understanding, not before:

npm install -g gitrole

Then create your first role and run the three-command example above.

Command quick reference

The current 0.3.0 command surface is small:

gitrole use <name> [--global | --local]: Apply a saved role globally or to the current repository.
gitrole current: Show the effective identity right now.
gitrole status: Show the fast human-readable alignment check.
gitrole status --short: Show the one-line machine-friendly alignment check.
gitrole doctor: Explain identity, remote, and SSH auth alignment in more detail.
gitrole doctor --json: Return the full diagnostic result as JSON.
gitrole remote set <name>: Rewrite origin to the saved role's GitHub SSH host alias.

Guides and use cases

Use the guide when you want the standard setup. Use a use case when you already know the basic workflow and need help with one specific problem.

Guide: Use the right Git identity for this repo Start here if you want the normal setup for one repository.

Use case: Fix pushes using the wrong GitHub account Work through the repo, remote, and SSH checks when pushes go to the wrong account.

Use case: Use gitrole as an identity preflight for agents and automation Check repo identity state before an agent commits or pushes under an existing role.

Use case: Give an agent its own Git identity Keep automated commits and pushes separate from human identities.