Diverse commando's toegevoegd. Ik weet nog niet of ik ze allemaal ga houden

scribblings/git.scrbl

@@ -1,8 +1,8 @@
 #lang scribble/manual
 
 @(require (for-label racket/base
+                     racket/contract
                      "../main.rkt"))
-@;git-cli))
 
 @title[#:tag "top"]{git-cli}
 @author{Hans Dijkema}
@@ -10,30 +10,42 @@
 @defmodule[git-cli]
 
 The @racketmodname[git-cli] module provides a command-line-like Git interface
-implemented by invoking the @tt{git} executable. Commands never read from
-standard input.
+implemented by invoking the @tt{git} executable. Git never reads credentials or
+other answers from standard input.
+
+@section{Command interface}
 
 @defform[(git command argument ...)]{
-Runs a supported Git @racket[command]. The arguments are passed to the Git
-command. Supported commands include @racket['status], @racket['add],
-@racket['commit], @racket['push], @racket['pull], @racket['branch],
-@racket['clone], @racket['log], @racket['rev-list], @racket['diff],
-@racket['grep], @racket['help], @racket['version], and
+Runs a registered command. Every command is also available as a normal
+procedure. For example, @racket[(git 'fetch '--prune)] and
+@racket[(git-fetch '--prune)] are equivalent.
+
+Registered command symbols are @racket['status], @racket['add],
+@racket['commit], @racket['push], @racket['pull], @racket['fetch],
+@racket['branch], @racket['clone], @racket['log], @racket['rev-list],
+@racket['diff], @racket['grep], @racket['help], @racket['switch],
+@racket['restore], @racket['show], @racket['tag], @racket['stash],
+@racket['remote], @racket['init], @racket['current-branch],
+@racket['branches], @racket['remotes], @racket['tags], @racket['stashes],
+@racket['save], @racket['save-all], @racket['sync],
+@racket['start-branch], @racket['release], @racket['version], and
 @racket['new-version].
 }
 
+@section{Basic commands}
+
 @defproc[(git-status [argument any/c] ...) list?]{
 Runs @tt{git status --porcelain} with the supplied arguments.
 
 Each result item has the form
-@racket[(index-status worktree-status file)]. The index status describes the
-change staged for the next commit. The worktree status describes the change in
-the working tree relative to the index.
+@racket[(index-status worktree-status file)]. The first status describes the
+index: the change already staged for the next commit. The second describes the
+working tree relative to the index: the change that is not staged yet.
 
 Both statuses are one of @racket['unchanged], @racket['modified],
 @racket['type-changed], @racket['added], @racket['deleted], @racket['renamed],
 @racket['copied], @racket['unmerged], @racket['untracked], or
-@racket['ignored]. For an untracked file, Git reports @tt{??}, so both statuses
+@racket['ignored]. Git reports an untracked file as @tt{??}, so both statuses
 are @racket['untracked].
 
 @racketblock[
@@ -62,21 +74,171 @@ status zero; otherwise an exception is raised.
 
 @defproc[(git-pull [argument any/c] ...) boolean?]{
 Fetches and integrates changes. Normal progress written by Git to standard
-error is treated as output when Git exits successfully.
+error is accepted when Git exits successfully.
+}
+
+@defproc[(git-fetch [argument any/c] ...) boolean?]{
+Downloads refs and objects without integrating them into the current branch.
+}
+
+@defproc[(git-branch [argument any/c] ...) boolean?]{
+Passes the arguments to @tt{git branch}. Use @racket[git-branches] when a list
+of local branch names is required.
+}
+
+@defproc[(git-clone [argument any/c] ...) boolean?]{
+Clones a repository. Normal progress on standard error is accepted when Git
+exits successfully.
 }
 
 @defproc[(git-log [argument any/c] ...) boolean?]{
-Displays Git log output and returns @racket[#t] when Git exits successfully.
+Displays the commit log.
 }
 
-@defproc[(git-grep [argument any/c] ...) list?]{
+@defproc[(git-rev-list [argument any/c] ...) boolean?]{
+Lists commit objects reachable from the supplied revisions.
+}
+
+@defproc[(git-diff [argument any/c] ...) boolean?]{
+Renders the Git diff as HTML and opens it in the default browser. Returns
+@racket[#t] when a diff was rendered and @racket[#f] otherwise.
+}
+
+@defproc[(git-grep [argument any/c] ...) (or/c list? #f)]{
 Searches tracked files. Each result contains the file, optional line number,
 optional match count, and matched text. Exit status one means that no matches
 were found and returns an empty list.
 }
 
+@defproc[(git-help [argument any/c] ...) boolean?]{
+Displays help for Git or a supplied Git command.
+}
+
+@defproc[(git-switch [argument any/c] ...) boolean?]{
+Switches branches. @racket[(git-switch '-c "feature")] creates and checks out a
+new branch.
+}
+
+@defproc[(git-restore [argument any/c] ...) boolean?]{
+Restores working-tree or index files. For example,
+@racket[(git-restore '--staged "main.rkt")] removes a file from the index
+without discarding its working-tree changes.
+}
+
+@defproc[(git-show [argument any/c] ...) boolean?]{
+Displays one or more Git objects.
+}
+
+@defproc[(git-tag [argument any/c] ...) boolean?]{
+Lists, creates, verifies or deletes tags. Use @racket[git-tags] when a list of
+tag names is required.
+}
+
+@defproc[(git-stash [argument any/c] ...) boolean?]{
+Stores or restores uncommitted work, for example
+@racket[(git-stash 'push '-m "Temporary work")] and @racket[(git-stash 'pop)].
+}
+
+@defproc[(git-remote [argument any/c] ...) boolean?]{
+Lists or manages remotes. Use @racket[git-remotes] when a list of remote names
+is required.
+}
+
+@defproc[(git-init [argument any/c] ...) boolean?]{
+Creates an empty repository or reinitializes an existing repository.
+}
+
+@section{Repository information}
+
+@defproc[(git-current-branch) (or/c string? #f)]{
+Returns the current local branch name, or @racket[#f] for a detached HEAD.
+}
+
+@defproc[(git-branches) (listof string?)]{
+Returns the local branch names.
+}
+
+@defproc[(git-remotes) (listof string?)]{
+Returns the configured remote names.
+}
+
+@defproc[(git-tags) (listof string?)]{
+Returns the repository tag names.
+}
+
+@defproc[(git-stashes) list?]{
+Returns stash information as @racket[(reference description)] items.
+}
+
+@section{Easy workflows}
+
+@defproc[(git-save [message string?] [file any/c] ...) boolean?]{
+Stages only the supplied files and commits them with @racket[message]. At least
+one file is required.
+}
+
+@defproc[(git-save-all [message string?]) boolean?]{
+Runs @tt{git add -A} and commits every change with @racket[message].
+}
+
+@defproc[(git-start-branch [name any/c] [start-point any/c #f]) boolean?]{
+Creates and switches to a branch with @tt{git switch -c}. When
+@racket[start-point] is supplied, the branch starts there.
+}
+
+@defproc[(git-sync [argument any/c] ...) boolean?]{
+Requires a clean working tree, then pulls and pushes. Supply either no
+arguments, so Git uses the configured upstream, or both a remote and branch.
+The pull behavior remains controlled by Git configuration such as
+@tt{pull.rebase}.
+}
+
+@defproc[(git-release [kind symbol?]) string?]{
+Requires a clean working tree, increments the package version in
+@filepath{info.rkt}, commits it as @tt{Version <version>}, creates a tag, and
+returns the tag name. The release is not pushed automatically.
+}
+
+@section{Package version}
+
+@defproc[(git-version) list?]{
+Returns the version from @filepath{info.rkt} as a list containing major, minor
+and patch.
+}
+
 @defproc[(git-new-version [kind symbol?]) list?]{
 Updates the version in @filepath{info.rkt}. The kind is @racket['major],
 @racket['minor], or @racket['patch], with @racket['maj] and @racket['min] as
 abbreviations. The result is the new version as a list of three integers.
 }
+
+@section{Configuration}
+
+@defproc[(git-exe) (or/c path? #f)]{
+Returns the configured Git executable. Git is first searched on @tt{PATH}. If
+it is absent, the executable is requested interactively and stored in the
+@tt{git-cli} simple-ini file.
+}
+
+@defproc[(set-git-exe! [exe-path path?]) void?]{
+Stores and caches the path to Git.
+}
+
+@defproc[(git-config [key symbol?]) any/c]{
+Returns one of the public settings:
+
+@itemlist[
+ @item{@racket['display-output], default @racket[#t], controls normal Git output.}
+ @item{@racket['display-command], default @racket[#f], displays the command before execution.}
+ @item{@racket['tag-prefix], default @racket["v"], controls tags made by @racket[git-release].}
+]}
+
+The display settings are stored in section @tt{git}; the tag prefix is stored
+in section @tt{release}. Git settings such as remotes, upstream branches,
+@tt{pull.rebase}, credentials and SSH keys remain Git's own configuration.
+}
+
+@defproc[(set-git-config! [key symbol?] [value any/c]) any/c]{
+Validates and stores a public setting, then returns @racket[value]. The display
+settings require booleans and @racket['tag-prefix] requires a string.
+}