gitrole

Switch your git identity in one command.

Gitrole saves a Git name and email as a named role, applies it locally or globally, and checks Git's effective author and committer. It also observes current default push destinations and supported SSH authentication.

Install and update

Gitrole requires Node.js 20 or newer. Choose one channel:

brew install synthesiseng/tap/gitrole

Or, with Node.js already installed:

npm install -g gitrole

Then check gitrole --version and command -v gitrole. Both channels expose gitrole and gitrole-prompt.

Update Homebrew with brew update, then brew upgrade synthesiseng/tap/gitrole. Update npm with npm install -g gitrole@latest. If both are installed, the first executable on PATH wins.

A source merge does not establish publication, and npm and Homebrew may publish at different times. Check npm view gitrole@latest version or brew info synthesiseng/tap/gitrole for your channel, then compare with gitrole --version. See Install and update for version and optional-asset boundaries.

Agent skill

Install Gitrole’s identity and policy workflows for your coding agent:

npx skills add synthesiseng/gitrole

This installs the skill for the current project by default. Add --agent codex to select Codex, or --global for user-wide installation. Review existing skill files before replacing them. The Gitrole CLI is installed separately; skill updates and CLI updates are separate. Manual installs must include the entire skills/gitrole folder and its references. See agent skill setup, discovery, updates, and migration.

First use

Inside the repository, replace the example identity with yours:

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

add saves the profile; use --local writes this repository's Git user configuration. current matches the effective author to a saved role. The offline check invokes zero SSH commands, including configuration inspection, while retaining local identity, destination, and policy checks.

In an HTTPS repository without a .gitrole pin, the common first result is:

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

The role was applied, but HTTPS identity expectations still warn. If the repository should use this role, save its expected GitHub username and create a matching pin:

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 profile; include any other fields you want to keep. pin refuses to overwrite an existing policy. With a matching role and no other warnings, HTTPS becomes auth=na policy=ok overall=aligned. This expresses a local expectation; it does not verify HTTPS credentials or repository access. Review .gitrole before sharing it.

For SSH prerequisites and a full walkthrough, read Use the right Git identity for this repo.

Human status and doctor output is concise. Each diagnostic warning appears once; doctor lists every push destination, counts ok checks and keeps warn/info. Its next action is the same in both modes and never runs automatically. Use gitrole status --verbose or gitrole doctor --verbose for full explanations. Add --offline to keep diagnosis local. Verbosity does not add checks or change verdicts. status --short and doctor --json retain their exact machine output and exit behavior, including when combined with --verbose.

Interpret results

Command	Purpose
gitrole check commit	Check saved commit identity and policy locally; no remote or SSH check.
gitrole current	Find the saved role matching the effective author.
gitrole status	Read a concise identity and default push check.
gitrole doctor	Explain warnings and each push destination.
gitrole doctor --json	Inspect structured identity, provenance, and check results.
gitrole doctor --offline	Explain local checks without running SSH; combine with --json in either order.

status --short prints eight fields in order: role scope override commit remote auth policy overall. Read fields by name. Exit 0 means overall=aligned; exit 2 means overall=warning with a valid result. Exit 1 means failure, with stderr and empty stdout. na is skipped or inapplicable, not proof of authentication.

Gitrole asks Git for the effective author and committer, including environment overrides and included configuration. current and import current use the author. A mismatched or missing committer warns. Configured scope can be mixed even when effective field sources are env.

Push checks cover the selected default remote and every Git-resolved push URL. HTTPS-only matching pins can yield auth=na; absent or mismatched pins warn, including offline. Mixed SSH/HTTPS warns online. Custom, interactive, or incomplete SSH contexts remain unverified. Online inspection may execute configured Match exec commands or DNS lookups.

doctor --offline skips all SSH execution, including configuration inspection. Skipped authentication is informational; exit 0 means no local warnings, not verified authentication or a guarantee of a future push. Identity, policy, every push host and HTTPS pin checks remain active, including mixed destinations. It reads or saves no authentication history.

For an unverified SSH account, read the specific reason and any manual-check guidance. gitrole doctor --json retains all reported reasons; a separate SSH greeting does not verify the push context. See SSH warnings.

A result is a snapshot. It cannot predict future explicit author/push arguments or changed configuration/environment, and it does not prove refspec readiness, push authorization, or push success.

Explicitly check an SSH account

Run gitrole auth test yourself in a terminal to see the account reported by each default SSH push destination. A mismatch with the effective role's expected account exits 2. This can prompt through SSH and run configured SSH commands; it neither guarantees a future push nor clears diagnostic warnings. No result is stored. See the command reference for effects, limits and exits.

Troubleshoot and continue

Run gitrole doctor to identify a warning, then use Troubleshoot identity warnings.

• Import the current Git identity: save the effective author Git already uses.
• Use repo-local identity policy: choose default and allowed roles.
• Fix pushes using the wrong account: inspect the actual selected push destinations before changing origin.
• Show gitrole in your shell prompt: offline checks require 0.9.0 or newer. Current source examples are in examples/prompt/. Fish and full Starship rendering are not qualified by this documentation pass.
• Enable shell completion: load optional scripts from npm or a checkout.
• Verify identity before an agent commits: use the packaged skill or an optional check-only hook within an authorized workflow.

The optional hooks/pre-commit now runs gitrole check commit. It requires a complete saved author/committer identity even without a pin: save the intended identity as a role, or do not install the hook there. The packaged agent skill uses the same local commit gate and diagnoses pushes separately. Existing copied hooks and skill files retain their old behavior until deliberately reviewed and updated. See the local commit guide for command exits, manual migration, backups, and CLI compatibility. A source change does not establish publication.

The npm package includes skills, hooks, and completions. This guide provides no supported Homebrew path for those assets; Homebrew users can use a source checkout. Installation does not enable them automatically.

Gitrole does not manage browser sessions, run gh auth, store HTTPS credentials, or create GitHub accounts. Role switching does not rewrite history or configure an SSH host alias.

A prompt checkmark means auth was not checked; it does not mean network auth was verified.

Reference

Gitrole warns on violated expectations, not assumptions. Use the command reference for the full surface:

Command	Purpose
gitrole import current --name <role>	Save the effective author.
gitrole pin <role>	Create a strict repository policy.
gitrole resolve / gitrole resolve --json	Read the default role or full policy.
gitrole status --short	Read eight alignment fields.
gitrole remote set <name>	Rewrite origin's fetch URL to a saved host alias.

Commands lists flags and side effects. Machine-readable contracts defines short fields, JSON, source/scope vocabulary, and exit codes. Documentation links the task guides.

License

MIT