diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 6f0c7ca80f..8d990e92fd 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -103,17 +103,20 @@ INPUT/OUTPUT FORMAT `git credential` reads and/or writes (depending on the action used) credential information in its standard input/output. This information can correspond either to keys for which `git credential` will obtain -the login/password information (e.g. host, protocol, path), or to the -actual credential data to be obtained (login/password). +the login information (e.g. host, protocol, path), or to the actual +credential data to be obtained (username/password). The credential is split into a set of named attributes, with one -attribute per line. Each attribute is -specified by a key-value pair, separated by an `=` (equals) sign, -followed by a newline. The key may contain any bytes except `=`, -newline, or NUL. The value may contain any bytes except newline or NUL. +attribute per line. Each attribute is specified by a key-value pair, +separated by an `=` (equals) sign, followed by a newline. + +The key may contain any bytes except `=`, newline, or NUL. The value may +contain any bytes except newline or NUL. + In both cases, all bytes are treated as-is (i.e., there is no quoting, and one cannot transmit a value with newline or NUL in it). The list of attributes is terminated by a blank line or end-of-file. + Git understands the following attributes: `protocol`:: @@ -123,7 +126,8 @@ Git understands the following attributes: `host`:: - The remote hostname for a network credential. + The remote hostname for a network credential. This includes + the port number if one was specified (e.g., "example.com:8088"). `path`:: @@ -134,7 +138,7 @@ Git understands the following attributes: `username`:: The credential's username, if we already have one (e.g., from a - URL, from the user, or from a previously run helper). + URL, the configuration, the user, or from a previously run helper). `password`:: @@ -146,8 +150,12 @@ Git understands the following attributes: value is parsed as a URL and treated as if its constituent parts were read (e.g., `url=https://example.com` would behave as if `protocol=https` and `host=example.com` had been provided). This - can help callers avoid parsing URLs themselves. Note that any - components which are missing from the URL (e.g., there is no - username in the example above) will be set to empty; if you want - to provide a URL and override some attributes, provide the URL - attribute first, followed by any overrides. + can help callers avoid parsing URLs themselves. + + Note that specifying a protocol is mandatory and if the URL + doesn't specify a hostname (e.g., "cert:///path/to/file") the + credential will contain a hostname attribute whose value is an + empty string. + + Components which are missing from the URL (e.g., there is no + username in the example above) will be left unset. diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 0d0f7149bd..9e481aec85 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -268,16 +268,26 @@ For a `get` operation, the helper should produce a list of attributes on stdout in the same format (see linkgit:git-credential[1] for common attributes). A helper is free to produce a subset, or even no values at all if it has nothing useful to provide. Any provided attributes will -overwrite those already known about by Git. If a helper outputs a -`quit` attribute with a value of `true` or `1`, no further helpers will -be consulted, nor will the user be prompted (if no credential has been -provided, the operation will then fail). +overwrite those already known about by Git's credential subsystem. + +While it is possible to override all attributes, well behaving helpers +should refrain from doing so for any attribute other than username and +password. + +If a helper outputs a `quit` attribute with a value of `true` or `1`, +no further helpers will be consulted, nor will the user be prompted +(if no credential has been provided, the operation will then fail). + +Similarly, no more helpers will be consulted once both username and +password had been provided. For a `store` or `erase` operation, the helper's output is ignored. -If it fails to perform the requested operation, it may complain to -stderr to inform the user. If it does not support the requested -operation (e.g., a read-only store), it should silently ignore the -request. + +If a helper fails to perform the requested operation or needs to notify +the user of a potential issue, it may write to stderr. + +If it does not support the requested operation (e.g., a read-only store), +it should silently ignore the request. If a helper receives any other operation, it should silently ignore the request. This leaves room for future operations to be added (older diff --git a/credential.h b/credential.h index d99ec42b2a..c0e17e3554 100644 --- a/credential.h +++ b/credential.h @@ -177,8 +177,8 @@ void credential_write(const struct credential *, FILE *); * Parse a url into a credential struct, replacing any existing contents. * * If the url can't be parsed (e.g., a missing "proto://" component), the - * resulting credential will be empty but we'll still return success from the - * "gently" form. + * resulting credential will be empty and the function will return an + * error (even in the "gently" form). * * If we encounter a component which cannot be represented as a credential * value (e.g., because it contains a newline), the "gently" form will return @@ -189,7 +189,7 @@ void credential_write(const struct credential *, FILE *); void credential_from_url(struct credential *, const char *url); int credential_from_url_gently(struct credential *, const char *url, int quiet); -int credential_match(const struct credential *have, - const struct credential *want); +int credential_match(const struct credential *want, + const struct credential *have); #endif /* CREDENTIAL_H */