]>
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 | ------------------ | |
11 | git credential <fill|approve|reject> | |
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 | |
42 | credential matching the description. | |
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 | ||
e30b2feb JRI |
116 | In both cases, all bytes are treated as-is (i.e., there is no quoting, |
117 | and one cannot transmit a value with newline or NUL in it). The list of | |
118 | attributes is terminated by a blank line or end-of-file. | |
1aed817f | 119 | |
3e5f29e8 | 120 | Git understands the following attributes: |
e30b2feb JRI |
121 | |
122 | `protocol`:: | |
123 | ||
124 | The protocol over which the credential will be used (e.g., | |
125 | `https`). | |
126 | ||
127 | `host`:: | |
128 | ||
1aed817f CMAB |
129 | The remote hostname for a network credential. This includes |
130 | the port number if one was specified (e.g., "example.com:8088"). | |
e30b2feb JRI |
131 | |
132 | `path`:: | |
133 | ||
134 | The path with which the credential will be used. E.g., for | |
135 | accessing a remote https repository, this will be the | |
136 | repository's path on the server. | |
137 | ||
138 | `username`:: | |
139 | ||
140 | The credential's username, if we already have one (e.g., from a | |
1aed817f | 141 | URL, the configuration, the user, or from a previously run helper). |
e30b2feb JRI |
142 | |
143 | `password`:: | |
144 | ||
145 | The credential's password, if we are asking it to be stored. | |
9c183a70 JK |
146 | |
147 | `url`:: | |
148 | ||
149 | When this special attribute is read by `git credential`, the | |
150 | value is parsed as a URL and treated as if its constituent parts | |
151 | were read (e.g., `url=https://example.com` would behave as if | |
152 | `protocol=https` and `host=example.com` had been provided). This | |
1aed817f | 153 | can help callers avoid parsing URLs themselves. |
0d9cdbc5 MÅ |
154 | + |
155 | Note that specifying a protocol is mandatory and if the URL | |
156 | doesn't specify a hostname (e.g., "cert:///path/to/file") the | |
157 | credential will contain a hostname attribute whose value is an | |
158 | empty string. | |
159 | + | |
160 | Components which are missing from the URL (e.g., there is no | |
161 | username in the example above) will be left unset. |