Use the right Git identity for this repo

Start with Install and update gitrole if gitrole is not installed. Run the following commands inside the repository you want to configure. Replace the example name and email with yours.

1. Save a role

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

add saves a named profile. It does not change this repository's Git configuration. If Git already uses the author you want, you can import the current Git identity instead.

2. Apply the role to this repository

gitrole use work --local

The success output is:

switched to work
  scope local
  commit Alex Developer <alex@work.example>

An additional repo note may ask you to run gitrole status. Local scope writes this repository's user.name and user.email. Environment overrides or higher-precedence Git settings can still change the effective author or committer; the next check reads what Git actually resolves.

3. Check the result

gitrole current
gitrole status --short --offline

current shows the saved role matching Git's effective author. The status line checks the author and committer, default push destinations, and repo policy. --offline runs no SSH commands, including configuration inspection.

A common first-use result in an HTTPS repository with no .gitrole policy is:

role=work scope=local override=true commit=ok remote=ok auth=warn policy=na overall=warning

This exits 2. The role was applied successfully; auth=warn means the HTTPS identity expectation still needs attention. Offline mode retains that local HTTPS check.

4. Decide the HTTPS identity policy

Gitrole does not inspect or manage HTTPS credentials. If this repository should use work, save the expected GitHub username and pin the role:

gitrole add work --name "Alex Developer" --email "alex@work.example" --github-user alex-work
gitrole pin work
gitrole status --short --offline

Use your actual username. add replaces the saved profile, so include any SSH or host fields you intend to keep. pin creates a strict .gitrole policy and refuses to overwrite an existing one. Review an existing policy instead of rerunning pin.

For the HTTPS destination above, with a matching role and no other warning, the result becomes:

role=work scope=local override=true commit=ok remote=ok auth=na policy=ok overall=aligned

This exits 0. Here auth=na means the matching pin allows the role and its saved GitHub username is present. It does not verify your HTTPS account, credentials, repository access, or push success. Decide whether to share .gitrole with your team before committing it.

If you use SSH

An SSH key, GitHub account, and host alias must already be configured outside gitrole. To save those expectations, include --ssh, --github-user, and --github-host in gitrole add; see Fix pushes using the wrong GitHub account.

Run gitrole status or gitrole doctor for an online check of supported SSH authentication. Online configuration inspection may execute configured Match exec commands or DNS lookups. Custom wrappers, interactive authentication, and incomplete SSH contexts remain unverified and warn.

If a warning remains

gitrole doctor

Read the warning labels, then use Troubleshoot identity warnings. Inspect repository.push.remoteName and every repository.push.targets entry in gitrole doctor --json before changing remotes. The selected push remote or an explicit push URL can differ from origin's fetch URL. gitrole remote set work changes origin's fetch URL only; use it only when that URL supplies the effective push destination you intend to change.

An older author in the history line

The last non-merge commit describes existing history. Applying a role does not rewrite it. Check the current commit identity separately.

Local and global scope

Use gitrole use work --local for this repository. gitrole use work --global changes your global Git identity; use work defaults to global scope. Local/worktree settings and environment overrides may still take precedence.

Daily use and reference

Run gitrole status before work that needs an identity check and gitrole doctor to explain warnings. An aligned result is a snapshot; future --author, explicit push arguments, or changed configuration/environment require reconsidering the check. It does not prove refspec readiness or authorize a commit or push.

Continue with repo-local identity policy, Commands, or Machine-readable contracts.