remote command added

scribblings/git-cli.scrbl

@@ -19,7 +19,7 @@ read credentials or other answers from the terminal.
 Runs a registered Git @racket[command]. The arguments are passed to the command.
 Registered command symbols are @racket['status], @racket['add],
 @racket['commit], @racket['push], @racket['pull], @racket['fetch],
-@racket['config], @racket['branch], @racket['switch], @racket['clone],
+@racket['config], @racket['branch], @racket['remote], @racket['switch], @racket['clone],
 @racket['tag],
 @racket['log], @racket['rev-list], @racket['diff],
 @racket['show], @racket['grep], @racket['help], @racket['version], and
@@ -134,12 +134,76 @@ appear directly after @racket['config] or directly after @racket['get] /
 @racket['set!]. A successful write returns @racket[#t].
 }
 
-@defproc[(git-branch [argument any/c] ...) boolean?]{
+@defproc[(git-branch [argument any/c] ...) (or/c boolean? list?)]{
 Runs @tt{git branch} with the supplied arguments. This can be used to list,
 create, rename, or delete branches according to the options supported by the
 installed Git executable.
-}
 
+With Git's @tt{-l} or @tt{--list} option, git-cli returns structured branch
+information. Each item starts with one of @racket['current], @racket['local],
+or @racket['remote], followed by the branch name.
+
+@racketblock[
+(git-branch '-l)
+
+'((current "main")
+  (local "develop"))
+]
+
+Git's normal branch selection and sorting options are passed through. For
+example, remote branches can be requested with @tt{-r}, all branches with
+@tt{-a}, and Git's @tt{--sort=<key>} option controls the returned order.
+
+@racketblock[
+(git 'branch '-l '-a "--sort=refname")
+
+'((current "main")
+  (local "develop")
+  (remote "origin/main"))
+]
+
+Without @tt{-l} or @tt{--list}, normal Git output is displayed and the
+procedure returns @racket[#t] when Git exits successfully.
+}
+@defproc[(git-remote [argument any/c] ...) any/c]{
+Runs @tt{git remote} with the supplied arguments and keeps the command's own
+subcommand structure.
+
+With no arguments, the remote names are returned as a Racket list.
+
+@racketblock[
+(git-remote)
+
+'("origin" "upstream")
+]
+
+With top-level @tt{-v} or @tt{--verbose}, each line reported by Git is returned
+as a separate structured item containing the remote name, URL, and the
+@racket['fetch] or @racket['push] role.
+
+@racketblock[
+(git-remote '-v)
+
+'(("origin" "https://example.invalid/project.git" fetch)
+  ("origin" "https://example.invalid/project.git" push))
+]
+
+The two Git lines are deliberately not merged. This keeps the result close to
+the output and semantics of @tt{git remote -v}.
+
+For @tt{get-url}, one URL is returned as a string. With @tt{--all}, a list of
+URLs is returned.
+
+@racketblock[
+(git 'remote 'get-url "origin")
+(git 'remote 'get-url '--all "origin")
+(git 'remote 'get-url '--push '--all "origin")
+]
+
+Other forms, including @tt{add}, @tt{rename}, @tt{remove}, @tt{set-head},
+@tt{show}, @tt{prune}, @tt{update}, @tt{set-branches}, and @tt{set-url}, are
+passed to Git unchanged and use the normal git-cli command result processing.
+}
 @defproc[(git-switch [argument any/c] ...) boolean?]{
 Runs @tt{git switch} with the supplied arguments.