You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A [git] credential helper implementation that allows to use[pass] as the credential backend for your git repositories.
7
+
A [git] credential helper implementation that allows using[pass] as the credential backend for your git repositories.
8
8
This is achieved by explicitly defining mappings between hosts and entries in the password store.
9
9
10
10
## Preconditions
11
11
12
12
GPG must be configured to use a graphical pinentry dialog.
13
-
The shell cannot be used due to the interaction required by [git]
13
+
The shell cannot be used due to the interaction required by [git].
14
14
15
15
## Installation
16
16
@@ -31,7 +31,7 @@ Ensure that `~/.local/bin` is in your `PATH` for the single-user installation.
31
31
Create the file `~/.config/pass-git-helper/git-pass-mapping.ini`.
32
32
This file uses ini syntax to specify the mapping of hosts to entries in the passwordstore database.
33
33
Section headers define patterns which are matched against the host part of a URL with a git repository.
34
-
Matching supports wildcards (using the python [fnmatch module](https://docs.python.org/3.4/library/fnmatch.html)).
34
+
Matching supports wildcards (using the python [fnmatch module](https://docs.python.org/3.7/library/fnmatch.html)).
35
35
Each section needs to contain a `target` entry pointing to the entry in the password store with the password (and optionally username) to use.
36
36
37
37
Example:
@@ -81,25 +81,71 @@ target=git-logins/${host}
81
81
```
82
82
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.
83
83
84
-
## Passwordstore Layout
84
+
### DEFAULT section
85
+
86
+
Defaults suitable for all entries of the mapping file can be specified in a special section of the configuration file named `[DEFAULT]`.
87
+
Everything configure in this section will automatically be available for all further entries in the file, but can be overriden there, too.
88
+
89
+
## Passwordstore Layout and Data Extraction
90
+
91
+
### Password
85
92
86
93
As usual with [pass], this helper assumes that the password is contained in the first line of the passwordstore entry.
87
-
Additionally, if a second line is present, this line is interpreted as the username and also returned back to the git process invoking this helper.
88
-
In case you use markers at the start of lines to identify what is contained in this line, e.g. like `Username: fooo`, the options `skip_username` and `skip_password` can be defined in each mapping to skip the given amount of characters from the beginning of the respective line.
89
-
Additionally, global defaults can be configured via the `DEFAULT` section:
94
+
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:
95
+
90
96
```ini
91
97
[DEFAULT]
92
-
# this is actually the default
93
-
skip_password=0
94
-
# Lenght of "Username: "
95
-
skip_username=10
98
+
# length of "password: "
99
+
skip_password=10
96
100
97
101
[somedomain]
98
-
target=special/somedomain
99
-
# somehow this entry does not have a prefix for the username
100
-
skip_username=0
102
+
# for some reasons, this entry doesn't have a password prefix
103
+
skip_password=0
104
+
target=special/noprefix
101
105
```
102
106
107
+
### Username
108
+
109
+
`pass-git-helper` can also provide the username necessary for authenticating at a server.
110
+
In contrast to the password, no clear convention exists how username information is stored in password entries.
111
+
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:
112
+
113
+
```ini
114
+
[DEFAULT]
115
+
username_extractor=regex_search
116
+
regex_username=^user: (.*)$
117
+
118
+
[differingdomain.com]
119
+
# use a fixed line here instead of a regex search
120
+
username_extractor=specific_line
121
+
line_username=1
122
+
```
123
+
124
+
The following strategies can be configured:
125
+
126
+
#### Strategy "specific_line" (default)
127
+
128
+
Extracts the data from a line indexed by its line number.
129
+
Optionally a fixed-length prefix can be stripped before returning the line contents.
130
+
131
+
Configuration:
132
+
*`line_username`: Line number containing the username, **0-based**. Default: 1 (second line)
133
+
*`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.
134
+
135
+
#### Strategy "regex_search"
136
+
137
+
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.
138
+
139
+
Configuration:
140
+
*`regex_username`: The regular expression to apply. Has to contain a single capture group for indicating the data to extract. Default: `^username: +(.*)$`.
141
+
142
+
#### Strategy "entry_name"
143
+
144
+
Returns the last path fragment of the passwordstore entry as the username.
145
+
For instance, if a regular [pass] call would be `pass show dev/github.com/languitar`, the returned username would be `languitar`.
146
+
147
+
No configuration options.
148
+
103
149
## Command Line Options
104
150
105
151
`-l` can be given as an option to the script to produce logging output on stderr.
0 commit comments