Typed git client (easy-git)
State: open/verified · Kind: module · Audience: system
Summary
Section titled “Summary”- A typed git client for TypeScript, in synchronous (
Git) and awaitable (AsyncGit) forms, sharing one verb table so the two surfaces cannot drift. - Each verb declares what absence means for it (an unset config key, a ref that doesn’t resolve);
every other non-zero exit throws
CommandFailed.git.try.*inspects instead of throwing;raw()bypasses the verb table entirely.
Statement
Section titled “Statement”easy-git replaces hand-rolled child_process git invocations with a typed client whose every method
names its declared absence codes versus real failure, so a guard that used to read a broken repo as
“clean” now throws instead. AsyncGit drives a swappable GitBackend (default: the CLI) rather
than argv directly, so a non-subprocess git implementation can back the same client. It is the
project’s mandated seam for git operations from TypeScript (per solutions/ontological/lib/CLAUDE.md:
“Git operations prefer the typed @sksizer/easy-git (Git) client”), and ships with an injectable
CommandRunner/AsyncCommandRunner from @sksizer/command-seam for test fakes.
What it provides
Section titled “What it provides”- Queries, mutations, and merge/rebase integration verbs (worktrees, refs, diff/log, config, merge-tree) with per-verb absence semantics
git.try.*mirror returning{ok, value}outcomes instead of throwingraw()/rawChecked()escape hatches for one-off argv- Git-reference parsing (
parseGitUrl,parseRepoRef,gitSshUrl) and filesystem-only checkout discovery (checkoutRoot) - A
/testingsubpath with throwaway repo fixtures (makeGitFixture,makeOriginAndCheckout,makeBareAndWorker) for suites that assert on shas
Underlying implementation
Section titled “Underlying implementation”- packages/ts/easy-git/ (sync.ts, async.ts, verbs.ts, outcome.ts, backend.ts, client.ts, git-url.ts, checkout-root.ts, testing.ts)
Locations
Section titled “Locations”packages/ts/easy-git/packages/rust/easy-git/packages/rust/fluent-git/