git-client is a lightweight, Promise-based Git client for Node.js, currently at stable version 1.11.1. It distinguishes itself by directly executing the system's `git` binary, offering a robust and comprehensive interface to all Git operations rather than reimplementing them in JavaScript. The library provides a clean, Promise-based API for command execution, supporting automatic method generation for Git commands, flexible option handling (both short and long format), and a 'spawn mode' for streaming operations. It includes full TypeScript support and has minimal dependencies. Recent releases indicate an active development cadence, with improvements and fixes rolled out every few weeks to months. It requires Node.js 16.x or higher and the `git` command-line tool to be installed and accessible in the system PATH.
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
While CommonJS `require` works, ESM `import` is the preferred pattern for modern Node.js applications. The default export is a function.
import git from 'git-client';
The `Git` class is a named export, used for advanced configurations like specifying a custom git directory (`new Git({ gitDir: './my-repo/.git' })`).
import { Git } from 'git-client';
TypeScript users can import type definitions for command options and other structures for enhanced type checking and autocompletion.
import type { GitCommandOptions } from 'git-client';
Demonstrates basic Git command execution using the default function and named methods, and includes a check for Git availability.
import git from 'git-client';
async function runGitCommands() {
try {
// Ensure Git is installed and available
await git('version');
console.log('Git is available and working.');
// Example 1: Get current commit hash using the default function
const hash = await git('rev-parse', 'HEAD');
console.log(`Current commit hash: ${hash}`);
// Example 2: Get status using a named method with options
const status = await git.status({ porcelain: true });
console.log('Git status (porcelain mode):\n' + status);
// Example 3: Initialize a new Git instance for a custom directory
// For a real scenario, you'd ensure this directory exists and is a repo.
// const customRepoPath = process.env.CUSTOM_REPO_PATH ?? '/tmp/my-test-repo';
// if (!fs.existsSync(customRepoPath)) {
// fs.mkdirSync(customRepoPath);
// }
// const customGit = new Git({ gitDir: `${customRepoPath}/.git`, workTree: customRepoPath });
// const customStatus = await customGit.status();
// console.log(`Status of custom repo: ${customStatus}`);
} catch (error) {
console.error('Failed to execute git command:', error);
if (error.message.includes('spawn git ENOENT')) {
console.error('Hint: Make sure Git is installed and in your system PATH.');
}
}
}
runGitCommands();
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.