{"id":15625,"library":"git-client","title":"Git Client","description":"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.","status":"active","version":"1.11.1","language":"javascript","source_language":"en","source_url":"https://github.com/JarvusInnovations/git-client","tags":["javascript","git","promise","typescript"],"install":[{"cmd":"npm install git-client","lang":"bash","label":"npm"},{"cmd":"yarn add git-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add git-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` works, ESM `import` is the preferred pattern for modern Node.js applications. The default export is a function.","wrong":"const git = require('git-client');","symbol":"git","correct":"import git from 'git-client';"},{"note":"The `Git` class is a named export, used for advanced configurations like specifying a custom git directory (`new Git({ gitDir: './my-repo/.git' })`).","wrong":"import git from 'git-client/Git';","symbol":"Git","correct":"import { Git } from 'git-client';"},{"note":"TypeScript users can import type definitions for command options and other structures for enhanced type checking and autocompletion.","symbol":"GitCommandOptions","correct":"import type { GitCommandOptions } from 'git-client';"}],"quickstart":{"code":"import git from 'git-client';\n\nasync function runGitCommands() {\n  try {\n    // Ensure Git is installed and available\n    await git('version');\n    console.log('Git is available and working.');\n\n    // Example 1: Get current commit hash using the default function\n    const hash = await git('rev-parse', 'HEAD');\n    console.log(`Current commit hash: ${hash}`);\n\n    // Example 2: Get status using a named method with options\n    const status = await git.status({ porcelain: true });\n    console.log('Git status (porcelain mode):\\n' + status);\n\n    // Example 3: Initialize a new Git instance for a custom directory\n    // For a real scenario, you'd ensure this directory exists and is a repo.\n    // const customRepoPath = process.env.CUSTOM_REPO_PATH ?? '/tmp/my-test-repo';\n    // if (!fs.existsSync(customRepoPath)) {\n    //   fs.mkdirSync(customRepoPath);\n    // }\n    // const customGit = new Git({ gitDir: `${customRepoPath}/.git`, workTree: customRepoPath });\n    // const customStatus = await customGit.status();\n    // console.log(`Status of custom repo: ${customStatus}`);\n\n  } catch (error) {\n    console.error('Failed to execute git command:', error);\n    if (error.message.includes('spawn git ENOENT')) {\n      console.error('Hint: Make sure Git is installed and in your system PATH.');\n    }\n  }\n}\n\nrunGitCommands();","lang":"typescript","description":"Demonstrates basic Git command execution using the default function and named methods, and includes a check for Git availability."},"warnings":[{"fix":"Prefix special options with `$` (e.g., change `spawn: true` to `$spawn: true`). Refer to the documentation for the complete list of special options.","message":"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.","severity":"breaking","affected_versions":">=1.11.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 16.x or newer.","message":"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.","severity":"gotcha","affected_versions":"<16.0.0"},{"fix":"Always sanitize or validate user-provided input before passing it as arguments to `git` commands. Avoid using `$shell: true` with untrusted input.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The `git` executable is not found in the system's PATH.","error":"Error: spawn git ENOENT"},{"fix":"Use the ES module import syntax: `import git from 'git-client';`.","cause":"Attempting to use `require()` in an ES module context (`'type': 'module'` in `package.json` or `.mjs` files).","error":"ReferenceError: require is not defined"},{"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`).","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.","error":"TypeError: git.revParse is not a function"}],"ecosystem":"npm"}