# 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))
```