Use the right Git identity for this repo

What this guide does

Use this guide if you are new to gitrole and want one clear setup flow for a repository.

If the repository also needs an explicit policy for which roles are preferred or allowed, continue with Use repo-local identity policy with .gitrole after this setup works.

By the end, you will know how to:

• save a role
• switch this repository to that role
• check whether the repo is aligned
• fix the remote if pushes still use the wrong GitHub account

Current vs status

These two commands answer different questions:

• gitrole current = "which saved role am I here?"
• gitrole status = "does this repo look right for commit and push?"

Use current when you want to know which role matches the active commit identity. Use status when you want the broader repo-alignment check.

Step 1: Save a role

Start by saving the identity you want to use in this repository.

Minimum version:

gitrole add work \
  --name "Work Name" \
  --email "you@work.example"

If this identity also has its own SSH key and GitHub account, use the fuller version instead:

gitrole add work \
  --name "Work Name" \
  --email "you@work.example" \
  --ssh ~/.ssh/id_work \
  --github-user your-work-user \
  --github-host github.com-work

What those extra flags mean:

• --ssh points to the SSH key for that identity
• --github-user is the GitHub user you expect SSH auth to resolve to
• --github-host is the SSH host alias you expect the repo remote to use

Step 2: Switch this repo to that role

Use --local when you want this repository to use that role without changing the rest of your machine:

gitrole use work --local

Example output:

switched to work
  scope local
  name  Work Name
  email you@work.example

That means the repository now uses the selected role for its local Git identity.

Step 3: Check the repo

Run:

gitrole status

This is the fast daily check.

Clean example:

work  Work Name <you@work.example>  local override  aligned
last non-merge commit  Work Name <you@work.example> - fix login form

That tells you:

• this repository is using the work role
• the role is applied locally in this repo
• the repo currently looks aligned
• the most recent non-merge commit was also authored with that identity

If status shows warning

Run:

gitrole doctor

Use doctor when you want the full explanation for the repo, remote, and SSH auth state.

A common first-time case looks like this:

• the commit identity was switched correctly
• the remote still points at the old SSH host alias
• SSH auth still resolves to the old GitHub account

In that case, update the remote:

gitrole remote set work

That rewrites origin to the GitHub host alias configured for the role.

Then run the checks again:

gitrole status
gitrole doctor

If you want the full wrong-account walkthrough, use Fix pushes using the wrong GitHub account.

Why status can still mention the old identity

Sometimes the repository is configured correctly now, but status still mentions the previous identity in the last commit line.

That usually means:

• the repo is using the new role now
• the most recent non-merge commit in history was created before you switched

That is normal. Make your next commit with the new identity, then run gitrole status again.

When to use local vs global

Use local scope for repositories that should stay isolated:

gitrole use work --local

Use global scope only when you want to change your machine-wide default identity:

gitrole use work

If you work across personal, work, client, or open-source repositories, --local is usually the safer default.

Simple mental model

Think of gitrole as four small checks in order:

1. save a role
2. switch this repo to it
3. run gitrole status
4. if something looks wrong, run gitrole doctor and possibly gitrole remote set <role>

That is the basic workflow for a new user.

If the repository also needs an explicit policy for which roles are preferred or allowed, continue with Use repo-local identity policy with .gitrole after this setup works.