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

doc: option value may be separate for valid reasons

2024-11-25T05:20:15Z

Even though `git help cli` recommends users to prefer using "--option=value" over "--option value", there can be reasons why giving them separately is a good idea. One reason is that shells do not perform tilde expansion for `--option=~/path/name` but they expand `--options ~/path/name` just fine. This is not a problem for many options whose option parsing is properly written using OPT_FILENAME(), because the value given to OPT_FILENAME() is tilde-expanded internally by us, but some commands take a pathname as a mere string, which needs this trick to have the shell help us. I think the reason we originally decided to recommend the stuck form was because an option that takes an optional value requires you to use it in the stuck form, and it is one less thing for users to worry about if they get into the habit to always use the stuck form. But we should be discouraging ourselves from adding an option with an optional value in the first place, and we might want to weaken the current recommendation. In any case, let's describe this one case where it is necessary to use the separate form, with an example. Reviewed-by: Eric Sunshine Signed-off-by: Junio C Hamano

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