Git Client

1.11.1 · active · verified Tue Apr 21

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.

Common errors

```
Error: spawn git ENOENT
```
cause The `git` executable is not found in the system's PATH.

fix Install Git on your system and ensure its directory is included in your system's PATH environment variable. Verify by running `git --version` in your terminal.
```
ReferenceError: require is not defined
```
cause Attempting to use `require()` in an ES module context (`'type': 'module'` in `package.json` or `.mjs` files).

fix Use the ES module import syntax: `import git from 'git-client';`.
```
TypeError: git.revParse is not a function
```
cause This error is unlikely with `git-client` as it dynamically generates methods. However, if using an older version or trying to call a non-existent git command, this could occur.

fix Ensure the command exists in Git's CLI and that you are calling it correctly. For direct `git('command', ...)` usage, check the command string. For named methods (`git.commandName`), ensure correct casing (e.g., `revParse` not `RevParse`).

Warnings

breaking Since v1.11.0, special options for commands like `$spawn`, `$gitDir`, etc., use a leading `$` prefix. Code relying on these options without the `$` might break or behave unexpectedly.
Fix: Prefix special options with `$` (e.g., change `spawn: true` to `$spawn: true`). Refer to the documentation for the complete list of special options.
gotcha This library directly executes the `git` binary found in your system's PATH. It requires `git` to be installed and accessible. Its behavior is therefore dependent on the version and configuration of the underlying `git` installation.
Fix: Ensure `git` is installed and its executable is discoverable via your system's PATH environment variable. Verify by running `git --version` in your terminal.
gotcha The library requires Node.js version 16.x or higher. Using it with older Node.js versions may lead to unexpected errors or compatibility issues.
Fix: Upgrade your Node.js environment to version 16.x or newer.
gotcha Input sanitization is crucial when executing external binaries. While `git-client` handles many aspects, directly passing unsanitized user input as arguments to `git` commands could pose security risks, especially if shell mode (`$shell: true`) is used.
Fix: Always sanitize or validate user-provided input before passing it as arguments to `git` commands. Avoid using `$shell: true` with untrusted input.

Install

npm install git-client npm
yarn add git-client yarn
pnpm add git-client pnpm

Imports

git
wrong:
```
const git = require('git-client');
```
correct:
```
import git from 'git-client';
```
While CommonJS `require` works, ESM `import` is the preferred pattern for modern Node.js applications. The default export is a function.
Git
wrong:
```
import git from 'git-client/Git';
```
correct:
```
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' })`).
GitCommandOptions
```
import type { GitCommandOptions } from 'git-client';
```
TypeScript users can import type definitions for command options and other structures for enhanced type checking and autocompletion.

Quickstart

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();

view raw JSON →