git/Documentation/gitcredentials.txt, branch v2.45.2

Merge branch 'mh/doc-credential-helpers'

2023-07-18T14:28:52Z

Doc update. * mh/doc-credential-helpers: doc: gitcredentials: link to helper list

doc: gitcredentials: link to helper list

2023-07-10T17:35:55Z

Link to community list of credential helpers. This is useful information for users. Describe how OAuth credential helpers work. OAuth is a user-friendly alternative to personal access tokens and SSH keys. Reduced setup cost makes it easier for users to contribute to projects across multiple forges. Signed-off-by: M Hickford Signed-off-by: Junio C Hamano

credential: erase all matching credentials

2023-06-15T20:26:41Z

`credential reject` sends the erase action to each helper, but the exact behaviour of erase isn't specified in documentation or tests. Some helpers (such as credential-store and credential-libsecret) delete all matching credentials, others (such as credential-cache) delete at most one matching credential. Test that helpers erase all matching credentials. This behaviour is easiest to reason about. Users expect that `echo "url=https://example.com" | git credential reject` or `echo "url=https://example.com\nusername=tim" | git credential reject` erase all matching credentials. Fix credential-cache. Signed-off-by: M Hickford Signed-off-by: Junio C Hamano

credential: new attribute password_expiry_utc

2023-02-22T23:18:58Z

Some passwords have an expiry date known at generation. This may be years away for a personal access token or hours for an OAuth access token. When multiple credential helpers are configured, `credential fill` tries each helper in turn until it has a username and password, returning early. If Git authentication succeeds, `credential approve` stores the successful credential in all helpers. If authentication fails, `credential reject` erases matching credentials in all helpers. Helpers implement corresponding operations: get, store, erase. The credential protocol has no expiry attribute, so helpers cannot store expiry information. Even if a helper returned an improvised expiry attribute, git credential discards unrecognised attributes between operations and between helpers. This is a particular issue when a storage helper and a credential-generating helper are configured together: [credential] helper = storage # eg. cache or osxkeychain helper = generate # eg. oauth `credential approve` stores the generated credential in both helpers without expiry information. Later `credential fill` may return an expired credential from storage. There is no workaround, no matter how clever the second helper. The user sees authentication fail (a retry will succeed). Introduce a password expiry attribute. In `credential fill`, ignore expired passwords and continue to query subsequent helpers. In the example above, `credential fill` ignores the expired password and a fresh credential is generated. If authentication succeeds, `credential approve` replaces the expired password in storage. If authentication fails, the expired credential is erased by `credential reject`. It is unnecessary but harmless for storage helpers to self prune expired credentials. Add support for the new attribute to credential-cache. Eventually, I hope to see support in other popular storage helpers. Example usage in a credential-generating helper https://github.com/hickford/git-credential-oauth/pull/16 Signed-off-by: M Hickford Reviewed-by: Calvin Wan Signed-off-by: Junio C Hamano

Merge branch 'mh/gitcredentials-generate'

2022-11-23T02:22:25Z

Doc update. * mh/gitcredentials-generate: Docs: describe how a credential-generating helper works

Merge branch 'mh/credential-unrecognized-attrs'

2022-11-18T23:43:59Z

Docfix. * mh/credential-unrecognized-attrs: docs: clarify that credential discards unrecognised attributes

Docs: describe how a credential-generating helper works

2022-11-14T23:18:59Z

Previously the docs only described storage helpers. A concrete example: Git Credential Manager can generate credentials for GitHub and GitLab via OAuth. https://github.com/GitCredentialManager/git-credential-manager Signed-off-by: M Hickford Signed-off-by: Taylor Blau

docs: clarify that credential discards unrecognised attributes

2022-11-13T04:57:34Z

It was previously unclear how unrecognised attributes are handled. Signed-off-by: M Hickford Signed-off-by: Taylor Blau

Documentation/gitcredentials.txt: mention password alternatives

2022-11-08T21:46:54Z

Git asks for a "password", but the user might use a personal access token or OAuth access token instead. Example: Password for 'https://AzureDiamond@github.com': Signed-off-by: M Hickford Signed-off-by: Taylor Blau

doc: uniformize placeholders' case

2021-11-09T17:39:11Z

URL being an acronym, it deserves to be kept uppercase. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano