Move util-git documentation to duck.

This commit is contained in:
Dominik Pantůček 2023-07-05 18:22:06 +02:00
parent 342eebba7e
commit d6be9ece08
6 changed files with 103 additions and 48 deletions

View file

@ -25,8 +25,11 @@
(declare (unit util-git))
(module
(import duck)
(module*
util-git
#:doc ("This module provides basic git repository querying functionality.")
(
git
git-status
@ -39,13 +42,14 @@
util-io
util-dict-list
util-parser
util-time)
util-time
racket-kwargs)
;; Valid git operating modes
(define git-modes
'((#:exit exit)
(#:output output)
(#:exit+output exit+output)))
'((exit exit)
(output output)
(exit+output exit+output)))
;; Used for actual invocation of git binary, returns two values: exit
;; code and output lines
@ -57,11 +61,20 @@
args))
;; Curried git repo command wrapper
(define (git repo . defargs)
(let ((defmode (if (null? defargs)
'output
;; Raises an error if not valid
(cadr (assq (car defargs) git-modes)))))
(define*/doc (git repo (defmodesym 'output))
("
* ```repo``` - a path to repository
* ```mode``` - return values mode for operations
Returns a procedure that allows invocation of git in given ```repo```
repository returning one or two values based on ```mode``` given:
* ```#:exit``` - returns exit code
* ```#:output``` - returns the output lines (default)
* ```#:exit+output``` - returns both exit code and output lines
")
;; Raises an error if not valid
(let ((defmode (cadr (assq defmodesym git-modes))))
(case defmode
((exit)
(lambda args
@ -83,7 +96,16 @@
("??" untracked)))
;; Returns a dictionary of unknown, modified, deleted and added files
(define (git-status repo)
(define/doc (git-status repo)
("
* ```repo``` - git repository
Returns a dictionary with the following keys:
* ```'modified``` - list of modified files
* ```'untracked``` - list of untracked files
* ```'unknown``` - list of files with unknown status
")
(let* ((lines ((git repo) 'status '--porcelain))
(clean? (null? lines)))
(let loop ((lines lines)
@ -105,7 +127,14 @@
;; Returns detailed file annotation with each line being represented
;; by dictionary with keys from git output
(define (git-blame repo fname)
(define/doc (git-blame repo fname)
("
* ```repo``` - git repository
* ```fname``` - file name (path) relative to the git repository
Returns annotated source with information about originating commits
for each line.
")
(let loop ((lines ((git repo) 'blame '--line-porcelain fname))
(blame (make-ldict))
(blames '()))