Documentation added and extended git log / git diif

private/git-provider.rkt

@@ -47,6 +47,12 @@
 ;; Provided functions
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; goal   : Find the configured Git executable.
+; pre    : Git is on PATH or a valid executable can be selected interactively.
+; post   : The executable path has been cached.
+; result : The path to git or git.exe.
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (define/contract (git-exe)
   (-> (or/c path? #f))
   (if (eq? cached-git-exe #f)
@@ -64,6 +70,13 @@
         the-git-exe)
       cached-git-exe))
 
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; goal   : Configure the Git executable.
+; pre    : exe-path names an executable path.
+; post   : The path has been stored and cached.
+; result : void.
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (define/contract (set-git-exe! exe-path)
   (-> path? void?)
   (void
@@ -72,6 +85,13 @@
      (set! cached-git-exe exe-path))))
 
 
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; goal   : Run Git without allowing interactive terminal prompts.
+; pre    : args contains the Git command and its arguments.
+; post   : Standard output and error have been read completely.
+; result : The exit code and ordered (source line) output items.
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (define (run-git args)
   (putenv "GIT_TERMINAL_PROMPT" "0")
   (let-values (((process stdout stdin stderr)
@@ -123,6 +143,13 @@
 (define (is-error? e)
   (not (is-output? e)))
 
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; goal   : Separate normal Git output from error output.
+; pre    : output contains (source line) items returned by run-git.
+; post   : output has only been inspected.
+; result : Whether no error occurred and either normal or error lines.
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (define (git-out cmd output)
   (let* ((out (map (λ (e) (cadr e)) (filter (λ (e) (is-output? e)) output)))
          (err (map (λ (e) (cadr e)) (filter (λ (e) (is-error? e)) output)))
@@ -130,6 +157,13 @@
          )
     (values r (if (eq? r #t) out err))))
 
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; goal   : Log and raise a Git exception.
+; pre    : cmd, msg* and outp describe a failed Git command.
+; post   : The message has been logged and an exception has been raised.
+; result : No normal return value.
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (define-syntax git-error
   (syntax-rules ()
     ((_ cmd msg* outp)
@@ -153,6 +187,13 @@
 
 (define re-a #px"~+")
 
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; goal   : Log Git output and optionally display it.
+; pre    : out is a string or a list of displayable lines.
+; post   : Non-empty output has been logged.
+; result : void.
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (define (git-displ out)
   (let ((str (if (string? out) out (string-join out "\n"))))
     (unless (string=? (string-trim str) "")