git-client

library1.0.1jsnpmunverified

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.

devops workflow

npm install git-client

github ↗package ↗

INSTALL

IMPORT

SIG · GIT-CLIENT

git-client

devopsjavascriptv1.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

git

✓ import git from 'git-client';

✗ const git = require('git-client');

While CommonJS `require` works, ESM `import` is the preferred pattern for modern Node.js applications. The default export is a function.

Git

✓ import { Git } from 'git-client';

✗ import git from 'git-client/Git';

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.

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

Debug

Known issues

breakingSince 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.

affects: >=1.11.0

gotchaThis 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.

affects: >=1.0.0

gotchaThe 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.

affects: <16.0.0

gotchaInput 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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: spawn git ENOENT

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

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

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`).

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/JarvusInnovations/git-client ↗

packagehttps://www.npmjs.com/package/git-client ↗