Authentication

README.md

@@ -85,22 +85,25 @@ The result remains two values: Git's exit code and the ordered
 
 ## Authentication retry
 
-Authentication failures are detected centrally after `run-git`, before
-command-specific result processing. `current-git-authentication-handler`
-defaults to `default-git-authentication-handler`.
+Authentication failures are recognized centrally after `run-git`. The
+recognizer covers common authentication/authorization errors, including HTTP
+401 and 403 responses.
 
-The default handler first uses an existing Git `credential.helper`. When no
-helper is configured, it asks for username and password/token with
-`input-prompt`, configures the non-persistent `cache` helper locally, approves
-the credential through `git credential approve`, and retries the original Git
-command once.
+`current-git-authentication-handler` defaults to
+`default-git-authentication-handler`. After an authentication failure the
+default handler rejects the failed credential first. If a Git credential
+helper exists, `git credential fill` is then tried so that helpers such as Git
+Credential Manager can obtain a replacement credential.
 
-A custom handler can still be installed:
+When no usable credential is returned, git-cli asks for a username and
+password/token using `input-prompt`. The `#:loop-until` callbacks validate the
+input and return the final value, as intended by `input-prompt`. If no
+credential helper is configured, git-cli configures the non-persistent `cache`
+helper locally before approving the supplied credential.
 
-```racket
-(current-git-authentication-handler
- (λ (cmd args e)
-   ;; Perform custom credential handling.
-   #t))
-```
+The original Git command is retried once. If authentication fails again, the
+credential used for that retry is rejected before the normal Git error is
+raised. This prevents a bad token from remaining in the credential cache.
 
+A custom handler can still be installed through
+`current-git-authentication-handler`.