Documentation.

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 'log '-l '-5)
-(git 'diff '--cached)
+(git 'fetch '--prune)
-(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 'switch "main")
+(git 'tag "v0.3.16")
+(git 'diff)
+(git 'show 'HEAD)
 
-;; Display-oriented variant:
+(git-status)
-(dgit 'status)
+(git-fetch '--prune)
+(git-switch "main")
+(git-tag "v0.3.16")
 ```
 
-`git` is an ordinary procedure; command names are symbols. `dgit` performs the
+`git` is an ordinary procedure. The first argument is the Git command symbol
-same operation, displays a compact human-readable result, and returns that result.
+and the remaining arguments are passed to that command.
 
-`(git 'help)` opens the locally installed Scribble documentation. A command can
+Several commands provide Racket-oriented output in addition to the normal Git
-be supplied to jump directly to its section, for example `(git 'help 'restore)`
+behavior:
-or `(git 'help 'grep)`.
 
-For `grep`, the natural `(git 'grep '-i "pattern")` spelling is supported even
+- `git-status` uses Git's porcelain status and returns structured status items.
-though Racket's reader represents `-i` as the complex number `0-1i`; in grep
+- `git-log -l` / `git-log --list` returns `(commit subject)` items.
-option position that value is interpreted as Git's `-i` flag.
+- `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
+Most are also exported as direct procedures such as `git-status`, `git-add`,
-documentation cross-reference index:
+`git-fetch`, `git-switch`, `git-tag`, `git-log`, `git-diff`, and `git-show`.
 
-```racket
+See the Scribble documentation for command-specific behavior and return values.
-(git 'help)
-(git 'help 'grep)
-(git 'help 'restore)
-```

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)
 

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.

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['commit], @racket['push], @racket['pull], @racket['fetch],
-@racket['clone], @racket['log], @racket['rev-list], @racket['diff],
+@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