Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 1 | git-credential(1) |
| 2 | ================= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
Matthieu Moy | fa0aad4 | 2012-08-08 09:58:27 +0200 | [diff] [blame] | 6 | git-credential - Retrieve and store user credentials |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 21 | credentials in the same manner as Git. The design of this scriptable |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 22 | interface models the internal C API; see |
Sebastian Schuberth | d5ff3b4 | 2013-09-06 22:03:22 +0200 | [diff] [blame] | 23 | link:technical/api-credentials.html[the Git credential API] for more |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 24 | background on the concepts. |
| 25 | |
| 26 | git-credential takes an "action" option on the command-line (one of |
| 27 | `fill`, `approve`, or `reject`) and reads a credential description |
| 28 | on stdin (see <<IOFMT,INPUT/OUTPUT FORMAT>>). |
| 29 | |
| 30 | If the action is `fill`, git-credential will attempt to add "username" |
| 31 | and "password" attributes to the description by reading config files, |
| 32 | by contacting any configured credential helpers, or by prompting the |
| 33 | user. The username and password attributes of the credential |
| 34 | description are then printed to stdout together with the attributes |
| 35 | already provided. |
| 36 | |
| 37 | If the action is `approve`, git-credential will send the description |
| 38 | to any configured credential helpers, which may store the credential |
| 39 | for later use. |
| 40 | |
| 41 | If the action is `reject`, git-credential will send the description to |
| 42 | any configured credential helpers, which may erase any stored |
| 43 | credential matching the description. |
| 44 | |
| 45 | If the action is `approve` or `reject`, no output should be emitted. |
| 46 | |
| 47 | TYPICAL USE OF GIT CREDENTIAL |
| 48 | ----------------------------- |
| 49 | |
| 50 | An application using git-credential will typically use `git |
| 51 | credential` following these steps: |
| 52 | |
| 53 | 1. Generate a credential description based on the context. |
| 54 | + |
| 55 | For example, if we want a password for |
| 56 | `https://example.com/foo.git`, we might generate the following |
| 57 | credential description (don't forget the blank line at the end; it |
| 58 | tells `git credential` that the application finished feeding all the |
Stefano Lattarini | e1c3bf4 | 2013-04-12 00:36:10 +0200 | [diff] [blame] | 59 | information it has): |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 60 | |
| 61 | protocol=https |
| 62 | host=example.com |
| 63 | path=foo.git |
| 64 | |
| 65 | 2. Ask git-credential to give us a username and password for this |
| 66 | description. This is done by running `git credential fill`, |
Matthieu Moy | 2d6dc18 | 2012-06-24 13:40:00 +0200 | [diff] [blame] | 67 | feeding the description from step (1) to its standard input. The complete |
| 68 | credential description (including the credential per se, i.e. the |
| 69 | login and password) will be produced on standard output, like: |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 70 | |
Matthieu Moy | 2d6dc18 | 2012-06-24 13:40:00 +0200 | [diff] [blame] | 71 | protocol=https |
| 72 | host=example.com |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 73 | username=bob |
| 74 | password=secr3t |
| 75 | + |
Matthieu Moy | 2d6dc18 | 2012-06-24 13:40:00 +0200 | [diff] [blame] | 76 | In most cases, this means the attributes given in the input will be |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 77 | repeated in the output, but Git may also modify the credential |
Matthieu Moy | 2d6dc18 | 2012-06-24 13:40:00 +0200 | [diff] [blame] | 78 | description, for example by removing the `path` attribute when the |
| 79 | protocol is HTTP(s) and `credential.useHttpPath` is false. |
| 80 | + |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 81 | If the `git credential` knew about the password, this step may |
| 82 | not have involved the user actually typing this password (the |
| 83 | user may have typed a password to unlock the keychain instead, |
| 84 | or no user interaction was done if the keychain was already |
| 85 | unlocked) before it returned `password=secr3t`. |
| 86 | |
| 87 | 3. Use the credential (e.g., access the URL with the username and |
| 88 | password from step (2)), and see if it's accepted. |
| 89 | |
| 90 | 4. Report on the success or failure of the password. If the |
| 91 | credential allowed the operation to complete successfully, then |
| 92 | it can be marked with an "approve" action to tell `git |
| 93 | credential` to reuse it in its next invocation. If the credential |
| 94 | was rejected during the operation, use the "reject" action so |
| 95 | that `git credential` will ask for a new password in its next |
| 96 | invocation. In either case, `git credential` should be fed with |
Matthieu Moy | 2d6dc18 | 2012-06-24 13:40:00 +0200 | [diff] [blame] | 97 | the credential description obtained from step (2) (which also |
| 98 | contain the ones provided in step (1)). |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 99 | |
| 100 | [[IOFMT]] |
| 101 | INPUT/OUTPUT FORMAT |
| 102 | ------------------- |
| 103 | |
| 104 | `git credential` reads and/or writes (depending on the action used) |
Jeff King | 3e5f29e | 2012-07-18 08:04:02 -0400 | [diff] [blame] | 105 | credential information in its standard input/output. This information |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 106 | can correspond either to keys for which `git credential` will obtain |
| 107 | the login/password information (e.g. host, protocol, path), or to the |
| 108 | actual credential data to be obtained (login/password). |
| 109 | |
Jeff King | 3e5f29e | 2012-07-18 08:04:02 -0400 | [diff] [blame] | 110 | The credential is split into a set of named attributes, with one |
| 111 | attribute per line. Each attribute is |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 112 | specified by a key-value pair, separated by an `=` (equals) sign, |
| 113 | followed by a newline. The key may contain any bytes except `=`, |
| 114 | newline, or NUL. The value may contain any bytes except newline or NUL. |
| 115 | In both cases, all bytes are treated as-is (i.e., there is no quoting, |
| 116 | and one cannot transmit a value with newline or NUL in it). The list of |
| 117 | attributes is terminated by a blank line or end-of-file. |
Jeff King | 3e5f29e | 2012-07-18 08:04:02 -0400 | [diff] [blame] | 118 | Git understands the following attributes: |
Javier Roucher Iglesias | e30b2fe | 2012-06-24 13:39:59 +0200 | [diff] [blame] | 119 | |
| 120 | `protocol`:: |
| 121 | |
| 122 | The protocol over which the credential will be used (e.g., |
| 123 | `https`). |
| 124 | |
| 125 | `host`:: |
| 126 | |
| 127 | The remote hostname for a network credential. |
| 128 | |
| 129 | `path`:: |
| 130 | |
| 131 | The path with which the credential will be used. E.g., for |
| 132 | accessing a remote https repository, this will be the |
| 133 | repository's path on the server. |
| 134 | |
| 135 | `username`:: |
| 136 | |
| 137 | The credential's username, if we already have one (e.g., from a |
| 138 | URL, from the user, or from a previously run helper). |
| 139 | |
| 140 | `password`:: |
| 141 | |
| 142 | The credential's password, if we are asking it to be stored. |
Jeff King | 9c183a7 | 2012-07-18 08:06:26 -0400 | [diff] [blame] | 143 | |
| 144 | `url`:: |
| 145 | |
| 146 | When this special attribute is read by `git credential`, the |
| 147 | value is parsed as a URL and treated as if its constituent parts |
| 148 | were read (e.g., `url=https://example.com` would behave as if |
| 149 | `protocol=https` and `host=example.com` had been provided). This |
| 150 | can help callers avoid parsing URLs themselves. Note that any |
| 151 | components which are missing from the URL (e.g., there is no |
| 152 | username in the example above) will be set to empty; if you want |
| 153 | to provide a URL and override some attributes, provide the URL |
| 154 | attribute first, followed by any overrides. |