Added git-tag and structured listing with -l/--list

scribblings/git.scrbl

@@ -108,17 +108,43 @@ Runs @tt{git switch} with the supplied arguments.
 Runs @tt{git clone} with the supplied arguments.
 }
 
-@defproc[(git-tag [argument any/c] ...) boolean?]{
+@defproc[(git-tag [argument any/c] ...) (or/c boolean? list?)]{
 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")
-]
-}
+When @tt{-l} or @tt{--list} is supplied, the matching tag names are returned
+as a Racket list. Git's sorting options are passed through unchanged, so the
+returned list keeps Git's order.
 
+@racketblock[
+(git-tag '-l)
+(git-tag '--list "--sort=version:refname")
+(git-tag '--list "--sort=-creatordate")
+]
+
+When @tt{-n} or @tt{-n1} is combined with @tt{-l} or @tt{--list}, each result
+item contains the tag name and the subject reported by Git.
+
+@racketblock[
+(git-tag '-l '-n)
+
+'(("v0.3.16" "Release 0.3.16")
+  ("v0.3.17" "Release 0.3.17"))
+]
+
+With @tt{-n<number>} and a number greater than one, git-cli asks Git for that
+many content lines using @tt{%(contents:lines=<number>)}. The returned message
+is kept as one string, including embedded newlines.
+
+For structured tag output git-cli asks Git for an explicit format using
+@tt{%(refname:strip=2)} and either @tt{%(contents:subject)} or
+@tt{%(contents:lines=<number>)}. Generated field and record delimiters are used
+to split the result safely.
+
+Other forms keep the normal command behavior and return @racket[#t] when Git
+exits successfully. Git errors are handled by the standard git-cli result
+processor.
+}
 @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.