Overview

Switch your git identity in one command.

Save named roles, switch per repo, and check that commit identity and push identity are actually aligned.

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.

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.

If you want the full first-time setup, go straight to Use the right Git identity for this repo. If pushes still go through the wrong GitHub account, jump to Fix pushes using the wrong GitHub account.

Status vs doctor

Make this distinction early:

Active role

`gitrole current`

Use this when you want to know which saved role matches the active commit identity in this repo.

Fast daily check

`gitrole status`

Use this before you commit or push. It answers "does this repo look right?" and checks the broader repo alignment.

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.

Install

Install comes after understanding, not before:

npm install -g gitrole

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

Keep reading

Use the main guide when you want the normal setup. Use a focused page when you 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.

Guide: Use repo-local identity policy with .gitrole Declare the preferred role for a repo and the short list of roles that are still valid there.

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.