103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# 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.
|
|
|
|
```racket
|
|
(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:
|
|
|
|
```racket
|
|
(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`.
|
|
|
|
```racket
|
|
(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 detected centrally after `run-git`, before
|
|
command-specific result processing. `current-git-authentication-handler`
|
|
contains a callback that receives the command, processed arguments and an
|
|
`exn:fail:git-auth` value. If the callback handles authentication and returns a
|
|
true value, git-cli retries the original command once. The default callback
|
|
returns `#f`, so existing error behavior is preserved until an authentication
|
|
handler is configured.
|
|
|
|
```racket
|
|
(current-git-authentication-handler
|
|
(λ (cmd args e)
|
|
;; Perform credential handling here.
|
|
#t))
|
|
```
|
|
|