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

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

command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers'

2020-08-05T01:34:01Z

The guides 'gitcredentials' and 'gitremote-helpers' do not currently appear in command-list.txt. 'gitcredentials' was forgotten back when guides were added to command-list.txt in 1b81d8cb19 (help: use command-list.txt for the source of guides, 2018-05-20). 'gitremote-helpers' was moved to section 7 in 439cc74632 (docs: move gitremote-helpers into section 7, 2019-03-25), but command-list.txt was not updated at the time. Add these two guides to the list of guides in 'command-list.txt', so that they appear in the output of 'git help --guides', and capitalize the first word of the description of 'gitcredentials', as was done in 1b81d8c (help: use command-list.txt for the source of guides, 2018-05-20) for the other guides. While at it, add a comment in Documentation/Makefile to remind developers to update command-list.txt if they add a new guide. Signed-off-by: Philippe Blain Signed-off-by: Junio C Hamano

Merge branch 'cb/credential-doc-fixes'

2020-05-13T19:19:19Z

Minor in-code comments and documentation updates around credential API. * cb/credential-doc-fixes: credential: document protocol updates credential: update gitcredentials documentation credential: correct order of parameters for credential_match credential: update description for credential_from_url_gently

credential: update gitcredentials documentation

2020-05-07T21:01:54Z

Clarify the expected effect of all attributes and how the helpers are expected to handle them and the context where they operate. While at it, space the descriptions for clarity, and add a paragraph mentioning the early termination in the list processing of helpers, to complement the one about the special "quit" attribute. Signed-off-by: Carlo Marcelo Arenas Belón Signed-off-by: Junio C Hamano