Documentation added and extended git log / git diif

scribblings/git.scrbl

@@ -1,8 +1,8 @@
 #lang scribble/manual
 
 @(require (for-label racket/base
+                     racket/contract
                      "../main.rkt"))
-@;git-cli))
 
 @title[#:tag "top"]{git-cli}
 @author{Hans Dijkema}
@@ -10,18 +10,27 @@
 @defmodule[git-cli]
 
 The @racketmodname[git-cli] module provides a command-line-like Git interface
-implemented by invoking the @tt{git} executable. Commands never read from
-standard input.
+implemented by invoking the @tt{git} executable. Commands do not allow Git to
+read credentials or other answers from the terminal.
+
+@section{Command interface}
 
 @defform[(git command argument ...)]{
-Runs a supported Git @racket[command]. The arguments are passed to the Git
-command. Supported commands include @racket['status], @racket['add],
+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['grep], @racket['help], @racket['version], and
 @racket['new-version].
+
+Most registered commands invoke the Git command with the same name. Some
+commands process the result into a Racket value, such as @racket['status],
+@racket['grep], @racket['log] with @tt{--list}, @racket['version], and
+@racket['new-version].
 }
 
+@section{Provided commands}
+
 @defproc[(git-status [argument any/c] ...) list?]{
 Runs @tt{git status --porcelain} with the supplied arguments.
 
@@ -37,11 +46,11 @@ Both statuses are one of @racket['unchanged], @racket['modified],
 are @racket['untracked].
 
 @racketblock[
-((modified unchanged "staged.rkt")
- (unchanged modified "working-tree.rkt")
- (modified modified "both.rkt")
- (renamed unchanged "old.rkt -> new.rkt")
- (untracked untracked "new.rkt"))
+'((modified unchanged "staged.rkt")
+  (unchanged modified "working-tree.rkt")
+  (modified modified "both.rkt")
+  (renamed unchanged "old.rkt -> new.rkt")
+  (untracked untracked "new.rkt"))
 ]}
 
 @defproc[(git-add [argument any/c] ...) boolean?]{
@@ -62,11 +71,27 @@ status zero; otherwise an exception is raised.
 
 @defproc[(git-pull [argument any/c] ...) boolean?]{
 Fetches and integrates changes. Normal progress written by Git to standard
-error is treated as output when Git exits successfully.
+error is accepted when Git exits successfully.
 }
 
-@defproc[(git-log [argument any/c] ...) boolean?]{
+@defproc[(git-log [argument any/c] ...) (or/c boolean? list?)]{
 Displays Git log output and returns @racket[#t] when Git exits successfully.
+
+The git-cli-specific option @tt{--list}, or its short form @tt{-l}, changes the
+result to a Racket list. Internally this option is replaced by Git's
+@tt{--oneline} option. Each returned item contains the abbreviated commit id and
+the commit subject.
+
+@racketblock[
+(git-log '--list '-5)
+
+'(("003f371" "Diverse commando's toegevoegd. Ik weet nog niet of ik ze allemaal ga houden")
+  ("2cb7e93" "Small changes. git main function is now a real function, not syntax"))
+]
+
+Other Git log options are still passed to Git. Consequently, options that add
+extra output lines can also influence how useful @tt{--list} is as a structured
+result.
 }
 
 @defproc[(git-grep [argument any/c] ...) list?]{
@@ -75,6 +100,8 @@ optional match count, and matched text. Exit status one means that no matches
 were found and returns an empty list.
 }
 
+@section{Package version}
+
 @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