agent-os-git

Git CLI packaged as AgentOS/RivetKit WASI software.

import { AgentOs } from "@rivet-dev/agent-os-core";
import git from "agent-os-git";

const vm = await AgentOs.create({
  software: [git],
});

await vm.exec("git version");

The npm package ships one WASI Preview 1 binary at wasm/git.

Purpose

The package exposes a git command that can run inside AgentOS/RivetKit VMs. It is backed by go-git, built with the standard Go WASI Preview 1 target, and supports local repositories plus HTTP and HTTPS remotes. SSH remotes are not supported by the AgentOS WASI build.

The default export is a meta-package that includes AgentOS coreutils, so AgentOs.exec("git ...") works without separately installing shell support.

Installation

npm install agent-os-git @rivet-dev/agent-os-core

Exports

import git, { commandDir, gitCommands } from "agent-os-git";

• git: default AgentOS software input for software: [git]
• gitCommands: only the git WASM command descriptor
• commandDir: host temp directory containing the materialized git command

Supported Scope

High-value porcelain and plumbing covered by tests includes:

• git init, add, config, commit, clone
• git branch, checkout, status, log, rev-parse
• git worktree add, worktree list, worktree remove
• local repositories, local smart HTTP, and public HTTPS clone paths

This is not full native Git parity. Unsupported areas may include SSH remotes and porcelain not implemented by this go-git CLI fork.

HTTP Authentication

HTTP and HTTPS remotes can authenticate with GIT_USERNAME and GIT_TOKEN. The token is sent as the HTTP Basic Auth password for the current command:

GIT_USERNAME=YOUR_USERNAME GIT_TOKEN=YOUR_TOKEN git clone https://github.com/org/private.git /tmp/repo
GIT_USERNAME=YOUR_USERNAME GIT_TOKEN=YOUR_TOKEN git -C /tmp/repo fetch
GIT_USERNAME=YOUR_USERNAME GIT_TOKEN=YOUR_TOKEN git -C /tmp/repo pull
GIT_USERNAME=YOUR_USERNAME GIT_TOKEN=YOUR_TOKEN git -C /tmp/repo push

Both variables must be set together. If only one is set, the command fails before opening the remote connection. This package does not print the token or write it to .git/config; keep the remote URL free of embedded credentials.

Commit identity is separate from remote authentication:

git -C /tmp/repo config user.name "Your Name"
git -C /tmp/repo config user.email "[email protected]"

Interactive credential prompts, credential helpers, and SSH authentication are not supported by the AgentOS WASI build.

Build

Prerequisites:

• Go with GOOS=wasip1 GOARCH=wasm support
• Node.js/npm
• wasm-tools on PATH for validation

npm ci
npm run validate

Useful scripts:

npm run build          # TypeScript only
npm run build:wasm     # Build wasm/git
npm run check-types    # Typecheck package and usage tests
npm run test           # Build and run Vitest
npm run release:check  # Full validation plus npm dry-run pack

Publishing

The package is configured so npm pack and npm publish run prepack, which rebuilds dist/ and validates wasm/git before creating the tarball.

Before publishing:

npm ci
npm run release:check
npm publish

The files allowlist intentionally publishes only:

• dist/
• wasm/
• npm's default package metadata files (package.json, README.md, LICENSE)

Bridging gaps in go-git

When upstream Git tests require a feature that go-git does not yet expose, the gap is filled temporarily in internal/<package>/. This directory is a staging area whose layout mirrors the eventual go-git home (e.g. internal/plumbing/format/idxfile is shaped for upstream's plumbing/format/idxfile). Not everything that lives here belongs in go-git — some bits are test-only shims — but the layering keeps upstream tests that exercise the bulk of go-git unblocked while the upstreaming conversation is in progress.

Conformance testing

make conformance runs a curated set of upstream Git tests against gogit, using upstream's own t/ harness. The runner (conformance/run.sh) builds gogit, symlinks it as git in a staging directory, and points GIT_TEST_INSTALLED there so the upstream framework picks our binary up unchanged.

The upstream test source comes from either:

• A local checkout pointed at by $GIT_SRC (e.g. GIT_SRC=$HOME/git/go-git/git make conformance), or
• A shallow clone of github.com/git/git's default branch, re-fetched on every run so upstream behaviour drift surfaces immediately.

The set of curated tests is conformance/tests.txt — one filename per line, # comments are ignored:

t2008-checkout-subdir.sh
t5308-pack-detect-duplicates.sh
t5325-reverse-index.sh

Individual tests can be run directly:

./conformance/run.sh t2008-checkout-subdir.sh        # one test, all cases
./conformance/run.sh t2008-checkout-subdir.sh 1,3    # one test, selected cases

$GO_GIT_REF (commit SHA, tag, or branch) overrides the go.mod pin for a single run so the gate can be evaluated against an in-flight go-git change.

License

This project is licensed under the Apache License 2.0. See LICENSE.