simple-git

simple-git is a Node.js library that wraps the system git CLI binary behind a typed, chainable, promise-based API, letting applications clone repos, inspect status/logs/diffs, and run arbitrary git commands programmatically without shelling out manually or parsing raw CLI output themselves.

It has no native bindings — every operation ultimately spawns the real git executable as a child process and parses its output — which keeps it lightweight and always compatible with whatever git version is installed, at the cost of requiring git itself to be present on the host.

What You Get

• A chainable, promise-based API covering the full common git command surface (clone, add, commit, push, pull, log, diff, status, branch, tag, and more)
• Structured, typed response objects for commands like status() and log() instead of raw stdout strings
• A plugin system for customizing behavior like timeouts, progress reporting, and command-error handling
• Both callback and promise/async APIs for compatibility with older and modern Node.js codebases
• TypeScript typings shipped in the package for full editor autocompletion

Common Use Cases

• Automating repository setup in CLI scaffolding tools (clone a template, initialize a repo, make an initial commit)
• Building CI/CD or release-automation scripts that need to tag, push, or inspect commit history programmatically
• Powering a backend service that manages many git repositories (e.g. a Git-hosting or deployment platform)
• Reading commit/diff/status information to build dashboards, changelogs, or code-review tooling

Under The Hood

Architecture — The repo is a Yarn-workspaces monorepo with the main simple-git package plus small internal helper packages (@simple-git/args-pathspec, @simple-git/argv-parser) under packages/. Inside simple-git/src, git-factory.ts constructs the root SimpleGit instance, lib/simple-git-api.ts and lib/api.ts define the fluent/chainable method surface, lib/runners handles actually spawning the git child process and streaming its stdout/stderr, lib/tasks implement each individual git subcommand (clone, log, diff, etc.) as isolated task modules, and lib/parsers turn raw CLI output into the library’s structured response objects (lib/responses). Tech Stack — TypeScript compiled via esbuild with esbuild-node-externals, tested with Jest (93+ spec files) and Babel for transform config, linted/formatted with Biome, and versioned/released via Changesets; runtime dependencies are minimal (@kwsites/file-exists, @kwsites/promise-deferred, debug) with the real git binary as the only true external dependency. Code Quality — The task-per-file structure (lib/tasks/) keeps each git subcommand’s argument-building and output-parsing logic isolated and independently testable, and the extensive spec suite covers parser edge cases for commands like log, status, and diff whose CLI output formats vary by git version and locale. API Design — The chainable method-call style (git.add('.').commit('message').push()) combined with both promise and legacy-callback support gives the library a low barrier to entry for simple scripts while still exposing raw/typed access to full command output for more advanced automation, and the plugin system lets consumers hook timeouts or progress events without forking the library.