Better documentation for git* and handling strings for symbols because of git*.

README.md

@@ -43,9 +43,17 @@ pass-through wrapper.
 
 `git*` is the compact command-style syntax. Bare arguments are converted to
 strings, so `(git* remote get-url origin)` is equivalent to
-`(git 'remote "get-url" "origin")`. Use `(eval expression)` when an argument
-must come from a Racket expression. `gt` remains available as a compatibility
-alias for `git*`.
+`(git 'remote "get-url" "origin")`. A bare identifier is therefore command-line
+text, not the value of a Racket variable or procedure with the same name. Use
+`(eval expression)` when an argument must come from a Racket expression.
+
+For example, `(git* switch branch)` passes the text `"branch"`, while
+`(git* switch (eval branch))` passes the value of the Racket variable `branch`.
+git-cli-specific wrappers should accept the textual arguments produced by
+`git*`; `new-version` accepts both symbols and text, so both
+`(git 'new-version 'min)` and `(git* new-version min)` work.
+
+`gt` remains available as a compatibility alias for `git*`.
 
 ```racket
 (git* init)

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.4.0")
+(define version "0.4.2")
 (define pkg-authors '("Hans Dijkema"))
 (define license 'MIT)
 

main.rkt

@@ -1351,7 +1351,7 @@
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ; goal   : Increment the package version in info.rkt.
-; pre    : kind is 'maj, 'major, 'min, 'minor or 'patch.
+; pre    : kind represents maj, major, min, minor or patch as symbol or text.
 ; post   : The version definition in info.rkt has been updated.
 ; result : The new version as a list containing major, minor and patch.
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -1360,7 +1360,7 @@
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ; goal   : Implement the registered new-version command.
-; pre    : args contains a supported version kind.
+; pre    : args contains a supported version kind as symbol or text.
 ; post   : The version definition in info.rkt has been updated.
 ; result : The new version as a list containing major, minor and patch.
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

private/info-handler.rkt

@@ -70,23 +70,24 @@
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ; goal   : Increment a package version.
-; pre    : kind is maj, major, min, minor or patch.
+; pre    : kind represents maj, major, min, minor or patch as symbol or text.
 ; post   : The version definition in info.rkt has been updated.
 ; result : #t after writing the new version.
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (define (info-next-version kind . dir*)
   (let ((dir (if (null? dir*)
                  "."
-                 (car dir*))))
-    (if (memq kind '(maj major min minor patch))
+                 (car dir*)))
+        (kind* (string->symbol (format "~a" kind))))
+    (if (memq kind* '(maj major min minor patch))
         (let ((v (info-version dir)))
           (cond
-            ((or (eq? kind 'maj)
-                 (eq? kind 'major))
+            ((or (eq? kind* 'maj)
+                 (eq? kind* 'major))
              (apply set-info-version! (cons dir
                                             (list (+ (car v) 1) 0 0))))
-            ((or (eq? kind 'min)
-                 (eq? kind 'minor))
+            ((or (eq? kind* 'min)
+                 (eq? kind* 'minor))
              (apply set-info-version! (cons dir
                                             (list (car v) (+ (cadr v) 1) 0))))
             (else

scribblings/git-cli.scrbl

@@ -69,6 +69,30 @@ converted from its literal syntax.
 (git* switch (eval branch))
 ]
 
+@bold{Important:} bare arguments to @racket[git*] are command-line text, not
+Racket values. An identifier is quoted syntactically and converted to a string,
+even when that identifier is also bound to a Racket variable or procedure.
+
+@racketblock[
+(define branch "develop")
+
+(git* switch branch)
+; passes "branch"
+
+(git* switch (eval branch))
+; passes "develop"
+]
+
+This distinction matters most for git-cli commands whose arguments are not
+ordinary Git command-line strings. Such wrappers should accept the textual
+arguments produced by @racket[git*]. For example, @racket[git-new-version] now
+accepts both symbols and text:
+
+@racketblock[
+(git 'new-version 'min)
+(git* new-version min)
+]
+
 Because @racket[git] falls back to direct Git execution for commands without a
 registered wrapper, @racket[git*] can also be used with those commands.
 
@@ -639,6 +663,16 @@ Updates the version in @filepath{info.rkt}. The kind is @racket['major],
 abbreviations. The result is the new version as a list of three integers.
 }
 
+@racketblock[
+(git-new-version 'min)
+(git 'new-version 'min)
+(git* new-version min)
+]
+
+The version kind may be supplied as a symbol or string. This makes the command
+compatible with @racket[git*], whose bare arguments are converted to text.
+
+
 
 @section{Low-level Git execution}