152 lines
5.5 KiB
Racket
152 lines
5.5 KiB
Racket
#lang scribble/manual
|
|
|
|
@(require (for-label racket/base
|
|
racket/contract
|
|
"../main.rkt"))
|
|
|
|
@title[#:tag "top"]{git-cli}
|
|
@author{Hans Dijkema}
|
|
|
|
@defmodule[git-cli]
|
|
|
|
The @racketmodname[git-cli] module provides a command-line-like Git interface
|
|
implemented by invoking the @tt{git} executable. Commands do not allow Git to
|
|
read credentials or other answers from the terminal.
|
|
|
|
@section{Command interface}
|
|
|
|
@defform[(git command argument ...)]{
|
|
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['branch],
|
|
@racket['clone], @racket['log], @racket['rev-list], @racket['diff],
|
|
@racket['show], @racket['grep], @racket['help], @racket['version], and
|
|
@racket['new-version].
|
|
|
|
Most registered commands invoke the Git command with the same name. Some
|
|
commands process the result into a Racket value, such as @racket['status],
|
|
@racket['grep], @racket['log] with @tt{--list}, @racket['version], and
|
|
@racket['new-version].
|
|
}
|
|
|
|
@section{Provided 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.
|
|
|
|
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
|
|
are @racket['untracked].
|
|
|
|
@racketblock[
|
|
'((modified unchanged "staged.rkt")
|
|
(unchanged modified "working-tree.rkt")
|
|
(modified modified "both.rkt")
|
|
(renamed unchanged "old.rkt -> new.rkt")
|
|
(untracked untracked "new.rkt"))
|
|
]}
|
|
|
|
@defproc[(git-add [argument any/c] ...) boolean?]{
|
|
Adds file contents to the index. Returns @racket[#t] when Git exits with status
|
|
zero; otherwise an exception is raised.
|
|
}
|
|
|
|
@defproc[(git-commit [argument any/c] ...) boolean?]{
|
|
Creates a commit. When @tt{-m} is omitted, a commit message is requested before
|
|
Git is started. A repository with nothing to commit returns @racket[#t]. Other
|
|
non-zero exit statuses, including a rejected commit hook, raise an exception.
|
|
}
|
|
|
|
@defproc[(git-push [argument any/c] ...) boolean?]{
|
|
Pushes changes using @tt{--porcelain}. Returns @racket[#t] when Git exits with
|
|
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 accepted when Git exits successfully.
|
|
}
|
|
|
|
@defproc[(git-log [argument any/c] ...) (or/c boolean? list?)]{
|
|
Displays Git log output and returns @racket[#t] when Git exits successfully.
|
|
|
|
The git-cli-specific option @tt{--list}, or its short form @tt{-l}, changes the
|
|
result to a Racket list. Internally this option is replaced by Git's
|
|
@tt{--oneline} option. Each returned item contains the abbreviated commit id and
|
|
the commit subject.
|
|
|
|
@racketblock[
|
|
(git-log '--list '-5)
|
|
|
|
'(("003f371" "Diverse commando's toegevoegd. Ik weet nog niet of ik ze allemaal ga houden")
|
|
("2cb7e93" "Small changes. git main function is now a real function, not syntax"))
|
|
]
|
|
|
|
Other Git log options are still passed to Git. Consequently, options that add
|
|
extra output lines can also influence how useful @tt{--list} is as a structured
|
|
result.
|
|
}
|
|
|
|
|
|
|
|
@defproc[(git-show [argument any/c] ...) (or/c boolean? string? list?)]{
|
|
Shows a Git object.
|
|
|
|
For a commit that includes a patch, the default git-cli output is HTML. The
|
|
commit information is shown above the diff and the diff is rendered using the
|
|
same Diff2Html presentation as @racket[git-diff].
|
|
|
|
The git-cli-specific output options are @tt{--output=html},
|
|
@tt{--output=-}, and @tt{--output=string}. @tt{--output=html} explicitly
|
|
selects the HTML presentation, @tt{--output=-} keeps Git's normal textual
|
|
output, and @tt{--output=string} returns that textual output as a string.
|
|
Options such as @tt{--stat}, @tt{--name-only}, @tt{--name-status}, and
|
|
@tt{--no-patch} default to textual output because they do not normally contain
|
|
a patch.
|
|
|
|
The git-cli-specific option @tt{--list}, or its short form @tt{-l}, returns a
|
|
Racket value. Without another show-format option it implies @tt{--stat}.
|
|
|
|
@racketblock[
|
|
(git-show '-l "9741b1c")
|
|
]
|
|
|
|
The result of @tt{--stat --list} contains @racket['file] and
|
|
@racket['total] items:
|
|
|
|
@racketblock[
|
|
'((file "README.md" 67 "+++---")
|
|
(file "main.rkt" 532 "++++-------------------------------------------")
|
|
(total 9 124 823))
|
|
]
|
|
|
|
With @tt{--name-only --list}, the result is a list of file names. With
|
|
@tt{--name-status --list}, every result item is the tab-separated Git
|
|
name-status record converted to a list of strings.
|
|
|
|
@tt{--list}/@tt{-l} cannot be combined with @tt{--output=...}. Only one of
|
|
@tt{--stat}, @tt{--name-only}, and @tt{--name-status} can be used with
|
|
@tt{--list}.
|
|
}
|
|
|
|
@defproc[(git-grep [argument any/c] ...) list?]{
|
|
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.
|
|
}
|
|
|
|
@section{Package version}
|
|
|
|
@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.
|
|
}
|