]>
Commit | Line | Data |
---|---|---|
e30b2feb JRI |
1 | git-credential(1) |
2 | ================= | |
3 | ||
4 | NAME | |
5 | ---- | |
fa0aad4f | 6 | git-credential - Retrieve and store user credentials |
e30b2feb JRI |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
10 | ------------------ | |
b7bf32b0 | 11 | 'git credential' (fill|approve|reject) |
e30b2feb JRI |
12 | ------------------ |
13 | ||
14 | DESCRIPTION | |
15 | ----------- | |
16 | ||
17 | Git has an internal interface for storing and retrieving credentials | |
18 | from system-specific helpers, as well as prompting the user for | |
19 | usernames and passwords. The git-credential command exposes this | |
20 | interface to scripts which may want to retrieve, store, or prompt for | |
2de9b711 | 21 | credentials in the same manner as Git. The design of this scriptable |
f3b90556 | 22 | interface models the internal C API; see credential.h for more |
e30b2feb JRI |
23 | background on the concepts. |
24 | ||
25 | git-credential takes an "action" option on the command-line (one of | |
26 | `fill`, `approve`, or `reject`) and reads a credential description | |
27 | on stdin (see <<IOFMT,INPUT/OUTPUT FORMAT>>). | |
28 | ||
29 | If the action is `fill`, git-credential will attempt to add "username" | |
30 | and "password" attributes to the description by reading config files, | |
31 | by contacting any configured credential helpers, or by prompting the | |
32 | user. The username and password attributes of the credential | |
33 | description are then printed to stdout together with the attributes | |
34 | already provided. | |
35 | ||
36 | If the action is `approve`, git-credential will send the description | |
37 | to any configured credential helpers, which may store the credential | |
38 | for later use. | |
39 | ||
40 | If the action is `reject`, git-credential will send the description to | |
41 | any configured credential helpers, which may erase any stored | |
6c26da84 | 42 | credentials matching the description. |
e30b2feb JRI |
43 | |
44 | If the action is `approve` or `reject`, no output should be emitted. | |
45 | ||
46 | TYPICAL USE OF GIT CREDENTIAL | |
47 | ----------------------------- | |
48 | ||
49 | An application using git-credential will typically use `git | |
50 | credential` following these steps: | |
51 | ||
52 | 1. Generate a credential description based on the context. | |
53 | + | |
54 | For example, if we want a password for | |
55 | `https://example.com/foo.git`, we might generate the following | |
56 | credential description (don't forget the blank line at the end; it | |
57 | tells `git credential` that the application finished feeding all the | |
e1c3bf49 | 58 | information it has): |
e30b2feb JRI |
59 | |
60 | protocol=https | |
61 | host=example.com | |
62 | path=foo.git | |
63 | ||
64 | 2. Ask git-credential to give us a username and password for this | |
65 | description. This is done by running `git credential fill`, | |
2d6dc182 MM |
66 | feeding the description from step (1) to its standard input. The complete |
67 | credential description (including the credential per se, i.e. the | |
68 | login and password) will be produced on standard output, like: | |
e30b2feb | 69 | |
2d6dc182 MM |
70 | protocol=https |
71 | host=example.com | |
e30b2feb JRI |
72 | username=bob |
73 | password=secr3t | |
74 | + | |
2d6dc182 | 75 | In most cases, this means the attributes given in the input will be |
2de9b711 | 76 | repeated in the output, but Git may also modify the credential |
2d6dc182 MM |
77 | description, for example by removing the `path` attribute when the |
78 | protocol is HTTP(s) and `credential.useHttpPath` is false. | |
79 | + | |
e30b2feb JRI |
80 | If the `git credential` knew about the password, this step may |
81 | not have involved the user actually typing this password (the | |
82 | user may have typed a password to unlock the keychain instead, | |
83 | or no user interaction was done if the keychain was already | |
84 | unlocked) before it returned `password=secr3t`. | |
85 | ||
86 | 3. Use the credential (e.g., access the URL with the username and | |
87 | password from step (2)), and see if it's accepted. | |
88 | ||
89 | 4. Report on the success or failure of the password. If the | |
90 | credential allowed the operation to complete successfully, then | |
91 | it can be marked with an "approve" action to tell `git | |
92 | credential` to reuse it in its next invocation. If the credential | |
93 | was rejected during the operation, use the "reject" action so | |
94 | that `git credential` will ask for a new password in its next | |
95 | invocation. In either case, `git credential` should be fed with | |
2d6dc182 MM |
96 | the credential description obtained from step (2) (which also |
97 | contain the ones provided in step (1)). | |
e30b2feb JRI |
98 | |
99 | [[IOFMT]] | |
100 | INPUT/OUTPUT FORMAT | |
101 | ------------------- | |
102 | ||
103 | `git credential` reads and/or writes (depending on the action used) | |
3e5f29e8 | 104 | credential information in its standard input/output. This information |
e30b2feb | 105 | can correspond either to keys for which `git credential` will obtain |
1aed817f CMAB |
106 | the login information (e.g. host, protocol, path), or to the actual |
107 | credential data to be obtained (username/password). | |
e30b2feb | 108 | |
3e5f29e8 | 109 | The credential is split into a set of named attributes, with one |
1aed817f CMAB |
110 | attribute per line. Each attribute is specified by a key-value pair, |
111 | separated by an `=` (equals) sign, followed by a newline. | |
112 | ||
113 | The key may contain any bytes except `=`, newline, or NUL. The value may | |
114 | contain any bytes except newline or NUL. | |
115 | ||
5f2117b2 MJC |
116 | Attributes with keys that end with C-style array brackets `[]` can have |
117 | multiple values. Each instance of a multi-valued attribute forms an | |
118 | ordered list of values - the order of the repeated attributes defines | |
119 | the order of the values. An empty multi-valued attribute (`key[]=\n`) | |
120 | acts to clear any previous entries and reset the list. | |
121 | ||
122 | In all cases, all bytes are treated as-is (i.e., there is no quoting, | |
e30b2feb JRI |
123 | and one cannot transmit a value with newline or NUL in it). The list of |
124 | attributes is terminated by a blank line or end-of-file. | |
1aed817f | 125 | |
3e5f29e8 | 126 | Git understands the following attributes: |
e30b2feb JRI |
127 | |
128 | `protocol`:: | |
129 | ||
130 | The protocol over which the credential will be used (e.g., | |
131 | `https`). | |
132 | ||
133 | `host`:: | |
134 | ||
1aed817f CMAB |
135 | The remote hostname for a network credential. This includes |
136 | the port number if one was specified (e.g., "example.com:8088"). | |
e30b2feb JRI |
137 | |
138 | `path`:: | |
139 | ||
140 | The path with which the credential will be used. E.g., for | |
141 | accessing a remote https repository, this will be the | |
142 | repository's path on the server. | |
143 | ||
144 | `username`:: | |
145 | ||
146 | The credential's username, if we already have one (e.g., from a | |
1aed817f | 147 | URL, the configuration, the user, or from a previously run helper). |
e30b2feb JRI |
148 | |
149 | `password`:: | |
150 | ||
151 | The credential's password, if we are asking it to be stored. | |
9c183a70 | 152 | |
d208bfdf H |
153 | `password_expiry_utc`:: |
154 | ||
155 | Generated passwords such as an OAuth access token may have an expiry date. | |
156 | When reading credentials from helpers, `git credential fill` ignores expired | |
157 | passwords. Represented as Unix time UTC, seconds since 1970. | |
158 | ||
a5c76569 H |
159 | `oauth_refresh_token`:: |
160 | ||
161 | An OAuth refresh token may accompany a password that is an OAuth access | |
162 | token. Helpers must treat this attribute as confidential like the password | |
163 | attribute. Git itself has no special behaviour for this attribute. | |
164 | ||
9c183a70 JK |
165 | `url`:: |
166 | ||
167 | When this special attribute is read by `git credential`, the | |
168 | value is parsed as a URL and treated as if its constituent parts | |
169 | were read (e.g., `url=https://example.com` would behave as if | |
170 | `protocol=https` and `host=example.com` had been provided). This | |
1aed817f | 171 | can help callers avoid parsing URLs themselves. |
0d9cdbc5 MÅ |
172 | + |
173 | Note that specifying a protocol is mandatory and if the URL | |
174 | doesn't specify a hostname (e.g., "cert:///path/to/file") the | |
175 | credential will contain a hostname attribute whose value is an | |
176 | empty string. | |
177 | + | |
178 | Components which are missing from the URL (e.g., there is no | |
179 | username in the example above) will be left unset. | |
cafd9828 | 180 | |
5f2117b2 MJC |
181 | `wwwauth[]`:: |
182 | ||
183 | When an HTTP response is received by Git that includes one or more | |
184 | 'WWW-Authenticate' authentication headers, these will be passed by Git | |
185 | to credential helpers. | |
186 | + | |
187 | Each 'WWW-Authenticate' header value is passed as a multi-valued | |
188 | attribute 'wwwauth[]', where the order of the attributes is the same as | |
189 | they appear in the HTTP response. This attribute is 'one-way' from Git | |
190 | to pass additional information to credential helpers. | |
191 | ||
7fd54b62 H |
192 | Unrecognised attributes are silently discarded. |
193 | ||
cafd9828 ÆAB |
194 | GIT |
195 | --- | |
196 | Part of the linkgit:git[1] suite |