git🔗

Hans Dijkema

The git module provides a small command-line-like Git interface implemented on top of the libgit2 package. It does not invoke the git executable.

The short form is intended for build scripts and interactive use:

(require git)

(git 'status)
(git 'diff)
(git 'diff '--cached)
(git 'add "main.rkt" "info.rkt")
(git 'commit "Implement raco support")
(git 'tag "v0.1")
(git 'checkout "main")

procedure
(git command [#:quiet quiet] argument ...) → any/c
  command : symbol?
  quiet : any/c = #f
  argument : any/c

Dispatches command to the corresponding Git procedure. For example, (git 'status) calls git-status, and (git 'commit "message") calls git-commit. Command names are ordinary symbols, so git can safely be used inside other macros and DSLs. For network commands, #:quiet suppresses progress output.

procedure
(dgit command [#:quiet quiet] argument ...) → any/c
  command : symbol?
  quiet : any/c = #f
  argument : any/c

Calls git, displays its result in a compact human-readable form, and returns the original result. Status entries are displayed with labels such as Modified, New, Deleted, and Renamed. Ignored files remain omitted, just as with git-status.

(dgit 'status)

1 Repository🔗

procedure
(git-repository? [path]) → boolean?
path : path-string? = (current-directory)

Returns whether path is inside a Git repository.

procedure
(git-root [path]) → path?
path : path-string? = (current-directory)

Returns the repository worktree root.

procedure
(git-init [path #:bare? bare?]) → path?
path : path-string? = (current-directory)
bare? : any/c = #f

Initializes a repository.

procedure
(git-clone url [#:quiet quiet]) → path?
  url : string?
  quiet : any/c = #f
(git-clone url path [#:quiet quiet]) → path?
  url : string?
  path : path-string?
  quiet : any/c = #f

Clones url. If path is omitted, a directory name is derived from the URL. Progress is written to the current output port unless quiet is true.

2 Status and index🔗

struct
(struct git-status-entry (path code flags))
  path : string?
  code : string?
  flags : list?

Describes one status entry. The code field uses the familiar two-character Git status notation.

procedure
(git-status) → (listof git-status-entry?)

Returns worktree and index status.

procedure
(git-status-lines [entries]) → (listof string?)
entries : (listof git-status-entry?) = (git-status)

Formats status entries as short Git-like lines.

procedure
(git-clean?) → boolean?

Returns #t when git-status is empty.

procedure
(git-diff) → string?
(git-diff option) → string?
option : (or/c '--cached)

Returns a unified patch as a string. With no arguments it compares the index with the worktree, like git diff. With '--cached it compares HEAD with the index, like git diff –cached.

procedure
(git-add path ...) → void?
path : path-string?

Stages the given paths. With no paths, stages the whole repository, including tracked removals.

3 Configuration and commits🔗

procedure
(git-config key) → string?
  key : string?
(git-config key value) → string?
  key : string?
  value : string?

Reads or writes a repository configuration value. The two-argument form returns value.

procedure
(git-head) → (or/c string? #f)

Returns the full OID of HEAD, or #f for a repository without commits.

procedure
(git-commit message) → string?
message : string?

Creates a commit from the index and returns its full OID. The author and committer are read from the repository configuration.

4 Branches, checkout, and tags🔗

procedure
(git-current-branch) → (or/c string? #f)

Returns the current local branch name, or #f for detached HEAD.

procedure
(git-branch) → (listof string?)
(git-branch name) → string?
name : string?

Lists local branches, or creates name at HEAD.

procedure
(git-branch-delete name) → void?
name : string?

Deletes a local branch.

procedure
(git-checkout name) → (or/c string? #f)
name : string?

Checks out a local branch, tag, or commit. A tag or commit produces detached HEAD.

procedure
(git-checkout-new name) → string?
name : string?

Creates and checks out a new branch.

procedure
(git-tag) → (listof string?)
(git-tag name) → string?
name : string?

Lists tags, or creates a lightweight tag at HEAD and returns its OID.

procedure
(git-tag-delete name) → void?
name : string?

Deletes a tag.

5 Log🔗

struct
(struct git-log-entry (id summary time))
  id : string?
  summary : string?
  time : integer?

Describes one commit returned by git-log.

procedure
(git-log [max-count]) → (listof git-log-entry?)
max-count : exact-nonnegative-integer? = 20

Returns commits from HEAD in topological/time order.

procedure
(git-log-lines [entries]) → (listof string?)
entries : (listof git-log-entry?) = (git-log)

Formats log entries as short OID plus summary.

6 Remotes🔗

procedure
(git-remotes) → (listof string?)

Lists remotes.

procedure
(git-remote-add name url) → string?
name : string?
url : string?

Adds a remote.

procedure
(git-remote-url [name]) → string?
name : string? = "origin"

Returns the remote URL.

procedure
(git-fetch [remote #:quiet quiet]) → void?
remote : string? = "origin"
quiet : any/c = #f

Fetches the configured refspecs from a remote. Progress is written to the current output port unless quiet is true.

procedure
(git-pull [remote #:quiet quiet]) → (or/c string? #f)
remote : string? = "origin"
quiet : any/c = #f

Fetches and performs a fast-forward-only update of the current branch. Returns the new OID, or #f when already up to date. A non-fast-forward update raises an exception.

procedure
(git-push [remote branch #:quiet quiet]) → void?
  remote : string? = "origin"
  branch : (or/c string? #f) = #f
  quiet : any/c = #f

Pushes a branch to a branch with the same name. With no positional arguments, the current branch is pushed to origin; with only remote, the current branch is pushed there. Progress is written to the current output port unless quiet is true.

procedure
(git-push-tag tag [remote #:quiet quiet]) → void?
  tag : string?
  remote : string? = "origin"
  quiet : any/c = #f

Pushes one tag. Progress is written to the current output port unless quiet is true.

Remote HTTPS operations automatically use credentials from the racket-git credential store when an entry exists for the remote host.

7 Command form🔗

The following command-like forms are supported directly:

(git 'init)
(git 'clone "https://example/repo.git")
(git 'status)
(git 'add "file.rkt")
(git 'config "user.name" "Name")
(git 'commit "message")
(git 'branch)
(git 'branch "feature")
(git 'branch '-d "feature")
(git 'checkout "main")
(git 'checkout '-b "feature")
(git 'tag)
(git 'tag "v0.1")
(git 'tag '-d "v0.1")
(git 'log 10)
(git 'remote)
(git 'remote 'add "origin" "https://example/repo.git")
(git 'remote 'get-url "origin")
(git 'fetch)
(git 'pull)
(git 'push)
(git 'push #:quiet #t)
(git 'push-tag "v0.1")

8 HTTPS credentials🔗

Git credentials are stored in racket-git.ini in the normal Racket preferences directory. Tokens are encrypted with AES-GCM. The encryption key is derived from the store password with PBKDF2-HMAC-SHA256.

procedure
(git-credentials-init! password
[ #:unlock-for seconds]) → void?
password : string?
seconds : real? = 86400

Creates the credential store and leaves it unlocked for seconds.

procedure
(git-credentials-unlock! password
[ #:for seconds]) → void?
password : string?
seconds : real? = 86400

Unlocks the credential store. The temporary unlock state is stored separately in racket-git-unlock.ini, allowing the unlock to survive restarting DrRacket or starting another Racket process. Both credential INI files use #:private? #t storage from simple-ini, which restricts them to mode 0600 on Unix.

procedure
(git-credentials-lock!) → void?

Locks the credential store immediately.

procedure
(git-credentials-unlocked?) → boolean?

Returns whether a non-expired unlock key is currently available.

procedure
(git-credentials-set! remote username token) → void?
  remote : string?
  username : string?
  token : string?

Stores an HTTPS username and token. Credentials are keyed by host.

procedure
(git-credentials-ref remote) → (or/c #f pair?)
remote : string?

Returns the username/token pair for remote, or #f when none is stored. The store must be unlocked when a credential exists.

procedure
(git-credentials-remove! remote) → void?
remote : string?

Removes credentials for the host represented by remote.

1	Repository
2	Status and index
3	Configuration and commits
4	Branches, checkout, and tags
5	Log
6	Remotes
7	Command form
8	HTTPS credentials