Import the current Git identity

Use import when Git already resolves the author name and email you want. Import saves that effective author identity under a name you choose. If you still need to type a new name, email, SSH key, or GitHub host, start with Use the right Git identity for this repo and gitrole add instead.

Quick start

In the repository whose identity you want to keep:

gitrole import current --name work

--name is required. This run had a repo-local name and email, so the scope is local:

imported current identity as work
  commit Alex Developer <alex@work.example>
  scope local

If that line shows the name and email you expected, you can stop. Saving the role doesn't switch Git config. Run gitrole use work --local when you want this repository to use the saved role.

How to read the result

The first line is the role name you passed. commit is the name and email that were saved. scope says where gitrole read them.

scope reports the underlying configured author scope. When both fields come from repository-local configuration it is local; when both come from global configuration it is global. A global name and local email produce mixed. System, worktree, command, Git-derived and unset scopes are also possible. Environment overrides affect the saved author values while scope still describes the underlying configuration.

For example, with a global name and a repository-local email:

imported current identity as work
  commit Alex Developer <alex@work.example>
  scope mixed

Import asks Git for its effective author identity, including GIT_AUTHOR_NAME/GIT_AUTHOR_EMAIL, included configuration, and author-specific settings. It does not import the committer or require that the values originate in user.*. Use gitrole doctor --json to inspect each field's source.

Confirm with gitrole current or gitrole list. When the repository should prefer that role, continue with Use repo-local identity policy with .gitrole.

Surprises

Import saves only the name and email. It doesn't infer an SSH key, a GitHub user, or a GitHub host, because those aren't part of the commit identity Git is about to use. Add them later with gitrole add if pushes need them.

If the role name already exists, import replaces that saved role with the current name and email only. SSH and GitHub fields that were stored on the old role are not kept. The command writes the role it read, rather than merging with the previous profile, so a stale host alias can't linger next to a new email.

no-role matches the shape of a role name, and it is still reserved. gitrole status --short writes role=no-role when nothing saved matches, so a real role with that name would look like "no role." The command exits 1, writes this to stderr, and prints nothing on stdout:

error: role name "no-role" is reserved for the status and prompt sentinel when no saved role matches; choose a different name

What it doesn't do

Import doesn't change Git config, switch you to the new role, rewrite origin, or install a hook. It only writes the saved role.

When it fails

The role name uses the same rules as gitrole add: lowercase letters, numbers, -, and _. An invalid name fails before anything is saved. The command exits 1, writes the error to stderr, and prints nothing on stdout:

error: invalid role name "client acme"; use lowercase letters, numbers, "-" or "_"

Git must resolve both an author name and an author email. Configuration or environment values can provide them. If the effective author is incomplete, import exits 1 and prints nothing on stdout:

error: current commit identity is incomplete; user.name and user.email must both be configured