Deprecation notice: Git now has includeIf option, so you won’t need this package any longer. The author no longer maintains the package, so it may not work as expected with a recent version of magit.
This Emacs package lets you manage local Git identities, i.e. user.name and user.email options in .git/config, from inside Emacs.
It is primarily intended for users who meet all of the following assumptions:
- You use Emacs.
- You (almost always) use magit for Git operations on your machine(s).
- You have to handle multiple Git identities on the same machine(s).
I found a CLI tool for the same purpose named karn, but since Emacs users are likely to run Git operations from inside Emacs (and the interface is probably Magit),
it would be better if you had a solution integrated into Emacs.
You only need to set a name and an email address before you perform git-commit, and if you use Emacs and Magit, it can be implemented by advising magit-commit. This package solves the problem. Now you don’t need a global Git configuration file to set your name and email address.
- You can configure multiple identities in your
custom-fileor in your init file. No extra dotfile is needed. If you work on multiple machines with different set of identities, you can maintain per-host configuration by just having separate custom files. - You can associate identities with repository host names and/or local working tree locations.
git-identity-magit-modeadds a:beforehook tomagit-committo ensure that a given repository gets an expected identity beforegit-commitis run.- For manual operation, it provides a command to select an identity in the current repository interactively.
- It provides a command (actually a hydra) to review your identity quickly and set a new one if necessary.
Install git-identity from MELPA.
- Set
git-identity-default-username, which is used as the default user name for all repositories. - Configure
git-identity-listvariable. You can usecustomize-variable. Each entry consists of a mandatory e-mail address and options. The user name is optional, and if it is omitted, the default user name is set along with the e-mail address. You can associate repository hosts and/or local repository locations with the identity, which are used to pick an identity for a given repository. - Optionally, you can start
git-identity-magit-modein your~/.emacs.d/.init.el, which turns on the hook run beforemagit-status.
Below is an example configuration using use-package:
(use-package git-identity
:after magit
:config
(git-identity-magit-mode 1)
;; Bind I to git-identity-info in magit-status
(define-key magit-status-mode-map (kbd "I") 'git-identity-info)
:custom
;; Warn if the global identity setting violates your policy
(git-identity-verify t)
;; The default user name
(git-identity-default-username "Akira Komamura"))
;; And set git-identity-list in your custom-file or init file
(setq git-identity-list
'(("my.personal.address@gmail.com"
:domains ("github.com")
;; The identity is applied if the remote URL contains this organization as directory
:exclude-organizations ("my-company-org")
:dirs ("~/.emacs.d" "~/personal"))
("my.personal.address@mycompanyorg.com"
:domains ("github.com")
;; The identity is applied if the remote URL contains this organization as directory
:organizations ("my-company-org"))
("my.name@mycompany.com"
:domains ("mycompany.com")
:dirs ("~/work"))
("liuwenbin@xxx12345.cn"
;; Chinese name for cool Chinese sites!
:name "刘文彬")))Note: The format of git-identity-list is going to be changed in an upcoming version. See #2 for details.
You can restrict an identity to a certain organization (by setting :organizations) and prevent it from setting in an organization (by setting :exclude-organizations), but those options are effective if and only if you set correct :domains. For example, you can have separate identities on GitHub both for personal and for your company, but you have to include github.com in :domains of both identities. Note: Organization names are case-insensitive.
Caveat: These settings are only effective in your local repositories. Let’s assume you join a GitHub organization with your personal account and make commits for the organization locally using an alternative e-mail address. If you approve and merge PRs on the web application, GitHub will make merge commits on behalf of your personal account with your primary e-mail address. If you really want to use separate identities on the same service, you will need mutliple accounts.
If you turn on git-identity-magit-mode, git-identity checks for an identity every time magit-commit is invoked.
If there is no local identity setting but a global one, the latter is used, so it won’t prompt for an identity.
You can also set the identity manually through git-identity-set-identity command.
To check what name and e-mail address are set on the repository, use git-identity-info command.
This package also exposes functions, which you can use as a library for writing your functions.
You can use the following functions from the package to extract a components from a Git URL:
git-identity-git-url-hostreturns the host name of a URL.git-identity-git-url-directoryreturns the path, excluding the name.
See below for examples:
(git-identity-git-url-host "git@github.com:owner/repo.git") => "github.com" (git-identity-git-url-host "git@gist.github.com:1234123412341234.git") => "gist.github.com" (git-identity-git-url-directory "git@github.com:owner/repo.git") => "owner" (git-identity-git-url-directory "https://github.com:22/owner/repo.git/") => "owner" (git-identity-git-url-directory "ssh://user-13@github.com:22/path/to/repo.git/") => "path/to"
The functions support most of the Git URLs defined in the man page of git-push (1).
Below are examples:
ssh://github.com/path/to/repo.git git://github.com/owner/repo.git ftps://github.com:22/owner/repo.git/ git@github.com:owner/repo.git github.com:owner/repo.git git@gist.github.com:1234123412341234.git xxx@yyy.host.com:/owner/repo.git hg::https://hg.sr.ht/~geyaeb/haskell-pdftotext
It also supports URLs of Git repositories created using git-remote-hg, which means you can use the package on Mercurial repositories.
You can use git-identity-guess-identity function to detect an identity of the repository.
When it is run without arguments, it returns an identity of the current repository.
Furthermore, there is git-identity-ancestor-directories-from-url function,
which returns a list of ancestor directories of an identity in your configuration
matching a Git URL.
This can be used to determine the clone destination of a repository
respecting your configuration.
- Add: Make several functions public by renaming.
git-identity-username,git-identity-email,git-identity-guess-identity,git-identity-git-url-host, andgit-identity-git-url-directory. - Add
git-identity-ancestor-directories-from-urlfunction. - Change: If there are multiple identities matching the same domain of a URL, pick one without organizations.
- Add support for organizations and multiple identities on the same hosts
- Fix the bug of duplicate confirmation in setting an expected identity.
- Fix the bug of trying to set an identity when the global identity is the same as an expected identity.
- Add a separate
git-identity-magit.elfor a linting reason.
GPL v3