git-cli/README.md

git-cli

A small command-line-like Git interface for Racket. The package invokes the installed git executable and exposes commands both through the generic git procedure and through direct procedures.

(require git-cli)

(git 'status)
(git 'log '-l '-5)
(git 'fetch '--prune)
(git 'switch "main")
(git 'tag "v0.3.16")
(git 'diff)
(git 'show 'HEAD)

(git-status)
(git-fetch '--prune)
(git-switch "main")
(git-tag "v0.3.16")

git is an ordinary procedure. The first argument is the Git command symbol and the remaining arguments are passed to that command.

Several commands provide Racket-oriented output in addition to the normal Git behavior:

• git-status uses Git's porcelain status and returns structured status items.
• git-log -l / git-log --list returns (commit subject) items.
• git-tag -l / git-tag --list returns tag names; with -n it returns (tag subject) items and -n<number> supports multiple content lines.
• git-diff renders HTML by default; --output=- selects stdout and --output=string returns a string.
• git-show renders a commit and its diff as HTML by default. -l / --list provides structured variants for --stat, --name-only, and --name-status.

Git is searched on PATH. Git itself remains responsible for remotes, credentials, SSH keys, pull strategy, and other repository configuration.

Commands

The package currently registers commands including status, add, commit, push, pull, fetch, config, branch, switch, clone, tag, log, rev-list, diff, show, grep, help, version, and new-version.

Most are also exported as direct procedures such as git-status, git-add, git-fetch, git-config, git-switch, git-tag, git-log, git-diff, and git-show.

See the Scribble documentation for command-specific behavior and return values.

Git configuration

git config has a small Racket-oriented interface:

(git 'config '--all)
(git 'config 'get '--all)
(git 'config '--global 'get '--all)
(git 'config 'get '--global "user.email")
(git 'config 'get '--all "credential.helper")
(git 'config 'get "credential.helper")
(git 'config 'set! "user.email" "hans@example.invalid")
(git 'config '--global 'set! "user.email" "hans@example.invalid")
(git 'config 'set! '--global "user.email" "hans@example.invalid")

get --all without a key returns (key value) items. get --all key returns all values for one key. get key returns one string or #f when the key is absent. set! returns #t after a successful write.

Low-level Git execution

run-git can be used when direct access to Git's stdin/stdout protocol is needed. Optional text can be supplied to Git with #:input.

(run-git '(credential fill)
         #:input "protocol=https\nhost=git.dijkewijk.nl\n\n")

The result remains two values: Git's exit code and the ordered (source line) output items.

Authentication retry

Authentication failures are recognized centrally after run-git. The recognizer covers common authentication/authorization errors, including HTTP 401 and 403 responses.

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.

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.

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.