Need help with pass-git-helper?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

languitar
171 Stars 11 Forks GNU Lesser General Public License v3.0 81 Commits 1 Opened issues

Description

A git credential helper interfacing with pass, the standard unix password manager.

Services available

!
?

Need anything else?

Contributors list

# 76,472
panoram...
prose
Markdow...
Vim
53 commits
# 6,501
Ruby
Homebre...
robot-f...
pony-la...
4 commits
# 16,193
C++
pcl
pointcl...
c-plus-...
3 commits
# 94,854
Vim
kakoune
c-plus-...
modal-e...
1 commit
# 775,608
Python
1 commit
# 47,951
gnuradi...
Shell
gnu
Ada
1 commit
# 77,465
C
efi
Linux
glibc
1 commit

Actions Status codecov

pass-git-helper

A git credential helper implementation that allows using pass as the credential backend for your git repositories. This is achieved by explicitly defining mappings between hosts and entries in the password store.

Preconditions

It is recommended to configure GPG to use a graphical pinentry program. That way, you can also use this helper when git is invoked via GUI programs such as your IDE. For a configuration example, refer to the ArchWiki. In case you really want to use the terminal for pinentry (via

pinentry-curses
), be sure to appropriately configure the environment variable
GPG_TTY
, most likely by adding the following lines to your shell initialization:
GPG_TTY=$(tty)
export GPG_TTY

If you use this setup for remote work via SSH, also consider the alternative of GPG agent forwarding.

Installation

Official Packages

If possible, use an available package for your Linux distribution or operating system such as the ones linked below.

Packaging status

From Source

sudo pip install .

This might potentially install Python packages without the knowledge of your system's package manager. If all package preconditions are already met, you can also copy the script file to to your system to avoid this problem:

sudo cp passgithelper.py /usr/local/bin/pass-git-helper

Another option is to install the script in an isolated virtualenv:

virtualenv /your/env
/your/env/pip install .

Usage

Create the file

~/.config/pass-git-helper/git-pass-mapping.ini
. This file uses ini syntax to specify the mapping of hosts to entries in the passwordstore database. Section headers define patterns which are matched against the host part of a URL with a git repository. Matching supports wildcards (using the python fnmatch module). Each section needs to contain a
target
entry pointing to the entry in the password store with the password (and optionally username) to use.

Example:

[github.com*]
target=dev/github

[.fooo-bar.] target=dev/fooo-bar

To instruct git to use the helper, set the

credential.helper
configuration option of git to
/full/path/to/pass-git-helper
. In case you do not want to include a full path, a workaround using a shell fragment needs to be used, i.e.
!pass-git-helper [email protected]
must be the option value. The option can be set using the CLI with:
git config credential.helper '!pass-git-helper [email protected]'

If you want to match entries not only based on the host, but also based on the path on a host, set

credential.useHttpPath
to
true
in your git config, e.g. via:
git config credential.useHttpPath true

Afterwards, entries can be matched against

host.com/path/to/repo
in the mapping. This means that in order to use a specific account for a certain Github project, you can then use the following mapping pattern:
[github.com/username/project*]
target=dev/github

Please note that when including the path in the mapping, the mapping expressions need to match against the whole path. As a consequence, in case you want to use the same account for all Github projects, you need to make sure that a wildcard covers the path of the URL, as shown here:

[github.com*]
target=dev/github

The host can be used as a variable to address a pass entry. This is especially helpful for wildcard matches:

[*]
target=git-logins/${host}

The above configuration directive will lead to any host that did not match any previous section in the ini file to being looked up under the

git-logins
directory in your passwordstore.

Using the

includeIf
directive available in git >= 2.13, it is also possible to perform matching based on the current working directory by invoking
pass-git-helper
with a conditional
MAPPING-FILE
. To achieve this, edit your
.gitconfig
, e.g. like this:
[includeIf "gitdir:~/src/user1/"]
    path=~/.config/git/gitconfig_user1
[includeIf "gitdir:~/src/user2/"]
    path=~/.config/git/gitconfig_user2

With the following contents of

gitconfig_user1
(and
gitconfig_user2
repspectively),
mapping_user1.ini
, which could contain a
target
entry to e.g.
github.com/user1
would always be invoked in
~/src/user1
:
[user]
    name = user1
[credential]
    helper=/full/path/to/pass-git-helper -m /full/path/to/mapping_user1.ini

See also the offical documentation for

.gitconfig
.

DEFAULT section

Defaults suitable for all entries of the mapping file can be specified in a special section of the configuration file named

[DEFAULT]
. Everything configure in this section will automatically be available for all further entries in the file, but can be overriden there, too.

Passwordstore Layout and Data Extraction

Password

As usual with pass, this helper assumes that the password is contained in the first line of the passwordstore entry. Though uncommon, it is possible to strip a prefix from the data of the first line (such as

password:
by specifying an amount of characters to leave out in the
skip_password
field for an entry or also in the
[DEFAULT]
section to apply for all entries:
[DEFAULT]
# length of "password: "
skip_password=10

[somedomain]

for some reasons, this entry doesn't have a password prefix

skip_password=0 target=special/noprefix

Username

pass-git-helper
can also provide the username necessary for authenticating at a server. In contrast to the password, no clear convention exists how username information is stored in password entries. Therefore, multiple strategies to extract the username are implemented and can be selected globally for the whole passwordstore in the
[DEFAULT]
section, or individually for certain entries using the
username_extractor
key:
[DEFAULT]
username_extractor=regex_search
regex_username=^user: (.*)$

[differingdomain.com]

use a fixed line here instead of a regex search

username_extractor=specific_line line_username=1

The following strategies can be configured:

Strategy "specific_line" (default)

Extracts the data from a line indexed by its line number. Optionally a fixed-length prefix can be stripped before returning the line contents.

Configuration:

  • line_username
    : Line number containing the username, 0-based. Default: 1 (second line)
  • skip_username
    : Number of characters to skip at the beginning of the line, for instance to skip a
    user:
    prefix. Similar to
    skip_password
    . Default: 0.

Strategy "regex_search"

Searches for the first line that matches a provided regular expressions and returns the contents of that line that are captured in a regular expression capture group.

Configuration:

  • regex_username
    : The regular expression to apply. Has to contain a single capture group for indicating the data to extract. Default:
    ^username: +(.*)$
    .

Strategy "entry_name"

Returns the last path fragment of the passwordstore entry as the username. For instance, if a regular pass call would be

pass show dev/github.com/languitar
, the returned username would be
languitar
.

No configuration options.

File Encoding

By default, passwordstore entries are assumed to use UTF-8 encoding. If all or some of your entries use a different encoding, use the

encoding
key (for instance, in the
DEFAULT
section) to specify the used encoding.

Command Line Options

-l
can be given as an option to the script to produce logging output on stderr. This might be useful to understand how the mapping is applied.

-m MAPPING_FILE
can be specified to use an alternative mapping file location.

Skipping Processing

In some automated contexts it might be necessary to prevent GPG from asking for the passphrase (via the agent). To achieve this, you can disable the complete processing of this helper by defining the environment variable

PASS_GIT_HELPER_SKIP
with any content (or no content at all). pass-git-helper will return immediately in this case, indicating to git that no suitable credentials could be found.

License

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or any later version. This work is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.