Racket

git🔗ℹ

Hans Dijkema

package: git

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 'add "main.rkt" "info.rkt")
(git 'commit "Implement raco support")
(git 'tag "v0.1")
(git 'checkout "main")

procedure
(git command argument ...) → any/c
command : symbol?
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.

procedure
(dgit command argument ...) → any/c
command : symbol?
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) → path?
  url : string?
(git-clone url path) → path?
  url : string?
  path : path-string?

Clones url. If path is omitted, a directory name is derived from the URL.

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-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]) → void?
remote : string? = "origin"

Fetches the configured refspecs from a remote.

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

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) → void?
(git-push remote) → void?
  remote : string?
(git-push remote branch) → void?
  remote : string?
  branch : string?

Pushes a branch to a branch with the same name. With no arguments, the current branch is pushed to origin; with only remote, the current branch is pushed there.

procedure
(git-push-tag tag [remote]) → void?
tag : string?
remote : string? = "origin"

Pushes one tag.

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-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