better progress information for git commands

scribblings/git.scrbl

@@ -23,11 +23,11 @@ The short form is intended for build scripts and interactive use:
 (git 'checkout "main")
 ]
 
-@defproc[(git [command symbol?] [argument any/c] ...) any/c]{
-Dispatches @racket[command] to the corresponding Git procedure. For example, @racket[(git 'status)] calls @racket[git-status], and @racket[(git 'commit "message")] calls @racket[git-commit]. Command names are ordinary symbols, so @racket[git] can safely be used inside other macros and DSLs.
+@defproc[(git [command symbol?] [#:quiet quiet any/c #f] [argument any/c] ...) any/c]{
+Dispatches @racket[command] to the corresponding Git procedure. For example, @racket[(git 'status)] calls @racket[git-status], and @racket[(git 'commit "message")] calls @racket[git-commit]. Command names are ordinary symbols, so @racket[git] can safely be used inside other macros and DSLs. For network commands, @racket[#:quiet] suppresses progress output.
 }
 
-@defproc[(dgit [command symbol?] [argument any/c] ...) any/c]{
+@defproc[(dgit [command symbol?] [#:quiet quiet any/c #f] [argument any/c] ...) any/c]{
 Calls @racket[git], displays its result in a compact human-readable form, and returns the original result. Status entries are displayed with labels such as @tt{Modified}, @tt{New}, @tt{Deleted}, and @tt{Renamed}. Ignored files remain omitted, just as with @racket[git-status].
 }
 
@@ -43,8 +43,8 @@ Calls @racket[git], displays its result in a compact human-readable form, and re
 
 @defproc[(git-init [path path-string? (current-directory)] [#:bare? bare? any/c #f]) path?]{Initializes a repository.}
 
-@defproc*[([(git-clone [url string?]) path?]
-           [(git-clone [url string?] [path path-string?]) path?])]{Clones @racket[url]. If @racket[path] is omitted, a directory name is derived from the URL.}
+@defproc*[([(git-clone [url string?] [#:quiet quiet any/c #f]) path?]
+           [(git-clone [url string?] [path path-string?] [#:quiet quiet any/c #f]) path?])]{Clones @racket[url]. If @racket[path] is omitted, a directory name is derived from the URL. Progress is written to the current output port unless @racket[quiet] is true.}
 
 @section{Status and index}
 
@@ -56,8 +56,8 @@ Calls @racket[git], displays its result in a compact human-readable form, and re
 
 @defproc[(git-clean?) boolean?]{Returns @racket[#t] when @racket[git-status] is empty.}
 
-@defproc*([[(git-diff) string?]
-           [(git-diff [option (or/c '--cached)]) string?]])]{Returns a unified patch as a string. With no arguments it compares the index with the worktree, like @tt{git diff}. With @racket['--cached] it compares HEAD with the index, like @tt{git diff --cached}.}
+@defproc*[([(git-diff) string?]
+           [(git-diff [option (or/c '--cached)]) string?])]{Returns a unified patch as a string. With no arguments it compares the index with the worktree, like @tt{git diff}. With @racket['--cached] it compares HEAD with the index, like @tt{git diff --cached}.}
 
 
 @defproc[(git-add [path path-string?] ...) void?]{Stages the given paths. With no paths, stages the whole repository, including tracked removals.}
@@ -105,15 +105,13 @@ Calls @racket[git], displays its result in a compact human-readable form, and re
 
 @defproc[(git-remote-url [name string? "origin"]) string?]{Returns the remote URL.}
 
-@defproc[(git-fetch [remote string? "origin"]) void?]{Fetches the configured refspecs from a remote.}
+@defproc[(git-fetch [remote string? "origin"] [#:quiet quiet any/c #f]) void?]{Fetches the configured refspecs from a remote. Progress is written to the current output port unless @racket[quiet] is true.}
 
-@defproc[(git-pull [remote string? "origin"]) (or/c string? #f)]{Fetches and performs a fast-forward-only update of the current branch. Returns the new OID, or @racket[#f] when already up to date. A non-fast-forward update raises an exception.}
+@defproc[(git-pull [remote string? "origin"] [#:quiet quiet any/c #f]) (or/c string? #f)]{Fetches and performs a fast-forward-only update of the current branch. Returns the new OID, or @racket[#f] when already up to date. A non-fast-forward update raises an exception.}
 
-@defproc*[([(git-push) void?]
-           [(git-push [remote string?]) void?]
-           [(git-push [remote string?] [branch string?]) void?])]{Pushes a branch to a branch with the same name. With no arguments, the current branch is pushed to @tt{origin}; with only @racket[remote], the current branch is pushed there.}
+@defproc[(git-push [remote string? "origin"] [branch (or/c string? #f) #f] [#:quiet quiet any/c #f]) void?]{Pushes a branch to a branch with the same name. With no positional arguments, the current branch is pushed to @tt{origin}; with only @racket[remote], the current branch is pushed there. Progress is written to the current output port unless @racket[quiet] is true.}
 
-@defproc[(git-push-tag [tag string?] [remote string? "origin"]) void?]{Pushes one tag.}
+@defproc[(git-push-tag [tag string?] [remote string? "origin"] [#:quiet quiet any/c #f]) void?]{Pushes one tag. Progress is written to the current output port unless @racket[quiet] is true.}
 
 Remote HTTPS operations automatically use credentials from the @tt{racket-git} credential store when an entry exists for the remote host.
 
@@ -143,6 +141,7 @@ The following command-like forms are supported directly:
 (git 'fetch)
 (git 'pull)
 (git 'push)
+(git 'push #:quiet #t)
 (git 'push-tag "v0.1")
 ]