docs: discuss caching personal access tokens

Commit Message

M Hickford Jan. 9, 2025, 9:26 p.m. UTC

From: M Hickford <[e-mail]>

Describe problems storing personal access tokens in git-credential-cache
and suggest alternatives.

Research suggests that many users are confused about this:

> the point of passwords is that (ideally) you memorise them [so]
> they're never stored anywhere in plain text. Yet GitHub's personal
> access token system seems to basically force you to store the token in
> plain text?

https://stackoverflow.com/questions/46645843/where-to-store-my-git-personal-access-token#comment89963004_46645843
Signed-off-by: M Hickford <[e-mail]>
---
    docs: discuss caching personal access tokens

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1851%2Fhickford%2Fcache-pat-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1851/hickford/cache-pat-docs-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1851

 Documentation/git-credential-cache.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)


base-commit: 14650065b76b28d3cfa9453356ac5669b19e706e

Patch

diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt
index 487cc557a87..18e9933674a 100644
--- a/Documentation/git-credential-cache.txt
+++ b/Documentation/git-credential-cache.txt
@@ -78,6 +78,23 @@  variable (this example increases the cache time to 1 hour):
 $ git config credential.helper 'cache --timeout=3600'
 -------------------------------------------------------
 
+PERSONAL ACCESS TOKENS
+----------------------
+
+Some remotes accept personal access tokens, which are randomly
+generated and hard to memorise. They typically have a lifetime of weeks
+or months.
+
+git-credential-cache is inherently unsuitable for persistent storage of
+personal access tokens. The credential will be forgotten after the cache
+timeout. Even if you configure a long timeout, credentials will be
+forgotten if the daemon dies.
+
+To avoid frequently regenerating personal access tokens, configure a
+credential helper with persistent storage. Alternatively, configure an
+OAuth credential helper to generate credentials automatically. See
+linkgit:gitcredentials[7].
+
 GIT
 ---
 Part of the linkgit:git[1] suite