From 14be30dfacc748855ef9df204b002acbfddd6e89 Mon Sep 17 00:00:00 2001
From: Hans Dijkema <hans@dijkewijk.nl>
Date: Thu, 13 Aug 2026 13:55:52 +0200
Subject: [PATCH] Documentation.

---
 README.md             | 67 ++++++++++++++++++------------------
 info.rkt              |  2 +-
 main.rkt              | 27 +++++++++++++++
 scribblings/git.scrbl | 80 +++++++++++++++++++++++++++++++++++++++++--
 4 files changed, 140 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index fc21cc5..f166d87 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1,50 @@
-# git
+# git-cli
 
-A small command-line-like Git module for Racket, implemented directly on top of the `libgit2` package.
+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)
+(require git-cli)
 
-(git 'help)
-(git 'help 'grep)
 (git 'status)
-(git 'diff)
-(git 'diff '--cached)
-(git 'add "main.rkt" "info.rkt")
-(git 'restore '--staged "scratch.rkt")
-(git 'reset 'HEAD "--" "main.rkt")
-(git 'grep '-i '-n "todo")
-(git 'commit "Implement raco support")
-(git 'tag "v0.2")
-(git 'branch-current)
+(git 'log '-l '-5)
+(git 'fetch '--prune)
 (git 'switch "main")
+(git 'tag "v0.3.16")
+(git 'diff)
+(git 'show 'HEAD)
 
-;; Display-oriented variant:
-(dgit 'status)
+(git-status)
+(git-fetch '--prune)
+(git-switch "main")
+(git-tag "v0.3.16")
 ```
 
-`git` is an ordinary procedure; command names are symbols. `dgit` performs the
-same operation, displays a compact human-readable result, and returns that result.
+`git` is an ordinary procedure. The first argument is the Git command symbol
+and the remaining arguments are passed to that command.
 
-`(git 'help)` opens the locally installed Scribble documentation. A command can
-be supplied to jump directly to its section, for example `(git 'help 'restore)`
-or `(git 'help 'grep)`.
+Several commands provide Racket-oriented output in addition to the normal Git
+behavior:
 
-For `grep`, the natural `(git 'grep '-i "pattern")` spelling is supported even
-though Racket's reader represents `-i` as the complex number `0-1i`; in grep
-option position that value is interpreted as Git's `-i` flag.
+- `git-status` uses Git's porcelain status and returns structured status items.
+- `git-log -l` / `git-log --list` returns `(commit subject)` items.
+- `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`.
 
-The same operations are available as normal procedures such as `git-status`, `git-add`, `git-commit`, `git-tag`, `git-current-branch`, `git-switch`, and `git-checkout`.
+Git is searched on `PATH`. Git itself remains responsible for remotes,
+credentials, SSH keys, pull strategy, and other repository configuration.
 
+## Commands
 
-## Help
+The package currently registers commands including `status`, `add`, `commit`,
+`push`, `pull`, `fetch`, `branch`, `switch`, `clone`, `tag`, `log`,
+`rev-list`, `diff`, `show`, `grep`, `help`, `version`, and `new-version`.
 
-Open the locally installed Scribble documentation through Racket's
-documentation cross-reference index:
+Most are also exported as direct procedures such as `git-status`, `git-add`,
+`git-fetch`, `git-switch`, `git-tag`, `git-log`, `git-diff`, and `git-show`.
 
-```racket
-(git 'help)
-(git 'help 'grep)
-(git 'help 'restore)
-```
+See the Scribble documentation for command-specific behavior and return values.
diff --git a/info.rkt b/info.rkt
index b11abba..d767dd1 100644
--- a/info.rkt
+++ b/info.rkt
@@ -2,7 +2,7 @@
 
 (define collection "git-cli")
 (define pkg-desc "Command-line-like Git operations for Racket, interface to the git cli command")
-(define version "0.3.15")
+(define version "0.3.16")
 (define pkg-authors '("Hans Dijkema"))
 (define license 'MIT)
 
diff --git a/main.rkt b/main.rkt
index 2e157c4..4f80283 100644
--- a/main.rkt
+++ b/main.rkt
@@ -17,6 +17,9 @@
          git-commit
          git-pull
          git-push
+         git-fetch
+         git-switch
+         git-tag
          git-log
          git-grep
          git-branch
@@ -215,6 +218,14 @@
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (def-cmd git-pull cmd-git-pull 'pull)
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; goal   : Download refs and objects from a remote repository.
+; pre    : The supplied arguments are valid for git fetch.
+; post   : Git fetch has completed successfully or an exception has been raised.
+; result : #t after a successful fetch.
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+(def-cmd git-fetch cmd-git-fetch 'fetch)
+
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ; goal   : List, create or delete branches.
@@ -224,6 +235,14 @@
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (def-cmd git-branch cmd-git-branch 'branch)
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; goal   : Switch branches.
+; pre    : The supplied arguments are valid for git switch.
+; post   : Git switch has completed successfully or an exception has been raised.
+; result : #t after a successful switch.
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+(def-cmd git-switch cmd-git-switch 'switch)
+
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ; goal   : Clone a repository into a new directory.
@@ -233,6 +252,14 @@
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (def-cmd git-clone cmd-git-clone 'clone)
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; goal   : List, create, delete or verify tags.
+; pre    : The supplied arguments are valid for git tag.
+; post   : Git tag has completed successfully or an exception has been raised.
+; result : #t after a successful tag command.
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+(def-cmd git-tag cmd-git-tag 'tag)
+
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ; goal   : Display the Git commit log or return it as a Racket list.
 ; pre    : The supplied arguments are valid for git log; --list and -l are git-cli options.
diff --git a/scribblings/git.scrbl b/scribblings/git.scrbl
index dc7035a..bdbeaf3 100644
--- a/scribblings/git.scrbl
+++ b/scribblings/git.scrbl
@@ -18,8 +18,9 @@ read credentials or other answers from the terminal.
 @defform[(git command argument ...)]{
 Runs a registered Git @racket[command]. The arguments are passed to the command.
 Registered command symbols are @racket['status], @racket['add],
-@racket['commit], @racket['push], @racket['pull], @racket['branch],
-@racket['clone], @racket['log], @racket['rev-list], @racket['diff],
+@racket['commit], @racket['push], @racket['pull], @racket['fetch],
+@racket['branch], @racket['switch], @racket['clone], @racket['tag],
+@racket['log], @racket['rev-list], @racket['diff],
 @racket['show], @racket['grep], @racket['help], @racket['version], and
 @racket['new-version].
 
@@ -74,6 +75,70 @@ Fetches and integrates changes. Normal progress written by Git to standard
 error is accepted when Git exits successfully.
 }
 
+@defproc[(git-fetch [argument any/c] ...) boolean?]{
+Downloads refs and objects from a remote repository without integrating them
+into the current branch. Arguments are passed directly to @tt{git fetch}.
+
+For example:
+
+@racketblock[
+(git-fetch)
+(git-fetch '--prune)
+(git 'fetch '--prune)
+]
+}
+
+@defproc[(git-branch [argument any/c] ...) boolean?]{
+Runs @tt{git branch} with the supplied arguments. This can be used to list,
+create, rename, or delete branches according to the options supported by the
+installed Git executable.
+}
+
+@defproc[(git-switch [argument any/c] ...) boolean?]{
+Runs @tt{git switch} with the supplied arguments.
+
+@racketblock[
+(git-switch "main")
+(git-switch '-c "feature")
+(git 'switch "main")
+]
+}
+
+@defproc[(git-clone [argument any/c] ...) boolean?]{
+Runs @tt{git clone} with the supplied arguments.
+}
+
+@defproc[(git-tag [argument any/c] ...) boolean?]{
+Runs @tt{git tag} with the supplied arguments. It can list, create, delete, or
+verify tags according to the options supported by Git.
+
+@racketblock[
+(git-tag)
+(git-tag "v0.3.16")
+(git-tag '-d "old-tag")
+]
+}
+
+@defproc[(git-rev-list [argument any/c] ...) boolean?]{
+Runs @tt{git rev-list} with the supplied arguments and displays Git's normal
+output. It returns @racket[#t] when Git exits successfully.
+}
+
+@defproc[(git-diff [argument any/c] ...) (or/c boolean? string?)]{
+Shows differences between Git objects or the working tree and index.
+
+By default a successful diff is rendered as HTML in the default browser. The
+git-cli-specific option @tt{--output=-} keeps Git's textual output on standard
+output. @tt{--output=string} returns the textual diff as a string.
+
+@racketblock[
+(git-diff)
+(git-diff '--cached)
+(git-diff '--output=-)
+(git-diff '--output=string)
+]
+}
+
 @defproc[(git-log [argument any/c] ...) (or/c boolean? list?)]{
 Displays Git log output and returns @racket[#t] when Git exits successfully.
 
@@ -142,8 +207,19 @@ optional match count, and matched text. Exit status one means that no matches
 were found and returns an empty list.
 }
 
+@defproc[(git-help [argument any/c] ...) boolean?]{
+Runs @tt{git help} with the supplied arguments and returns @racket[#t] when Git
+exits successfully.
+}
+
 @section{Package version}
 
+@defproc[(git-version) list?]{
+Reads the package version from @filepath{info.rkt} and returns it as a list
+containing major, minor, and patch.
+}
+
+
 @defproc[(git-new-version [kind symbol?]) list?]{
 Updates the version in @filepath{info.rkt}. The kind is @racket['major],
 @racket['minor], or @racket['patch], with @racket['maj] and @racket['min] as