simple-git

Install simple-git using npm or yarn to use it as a lightweight interface for running git commands in your Node.js application.

System Dependency: You must have git installed on your system and accessible via the git command.

npm install simple-git
# or
yarn add simple-git

The project uses automated processes to close issues that have not received requested additional details within a set timeframe. This is done to ensure the issue tracker remains focused on active investigations.

If your issue has been closed:

• If the issue is not locked: You can simply re-open the issue and add the requested details.
• If the issue is locked: You must create a new issue. To maintain context, link the new issue to the old one by providing its ID or URL in your description.

You can include simple-git in your application using CommonJS, ES Modules, or TypeScript. The main export is a function that initializes a SimpleGit instance.

CommonJS

const simpleGit = require('simple-git');
simpleGit().clean(simpleGit.CleanOptions.FORCE);

ES Modules

import { simpleGit, CleanOptions } from 'simple-git';
simpleGit().clean(CleanOptions.FORCE);

TypeScript

import { simpleGit, SimpleGit, CleanOptions } from 'simple-git';

const git: SimpleGit = simpleGit().clean(CleanOptions.FORCE);

You can terminate git child processes created by simple-git by passing an AbortController.signal to the simpleGit constructor options. This sends a SIGKILL to the underlying processes.

When a task is aborted, it will throw a GitPluginError. You can identify an abort-specific failure by checking if err.plugin === 'abort'.

import { simpleGit, GitPluginError, SimpleGit } from 'simple-git';

const controller = new AbortController();

const git: SimpleGit = simpleGit({
   baseDir: '/some/path', 
   abort: controller.signal,
});

try {
  await git.pull();
}
catch (err) {
    if (err instanceof GitPluginError && err.plugin === 'abort') {
        // task failed because `controller.abort` was called while waiting for the `git.pull`
    }
}

Some simple-git methods return raw stdout (like git.raw()), but others parse the output into structured data (like git.branchLocal() returning a BranchSummary). If your system locale is not set to English, these parsers may fail. To ensure consistent parsing, set the LANG and LC_ALL environment variables to 'C' using the .env() method.

import { simpleGit } from 'simple-git';

const git = simpleGit().env({
   LANG: 'C',
   LC_ALL: 'C',
});
const branches = await git.branchLocal();

By default, the timeout plugin only kills processes that appear to be hanging (it resets the timer on data arrival). To change this to an absolute timeout—where the process is killed after a fixed duration regardless of activity—set both stdOut and stdErr to false in the timeout configuration.

import { simpleGit, SimpleGit } from "simple-git";

// create a simple-git instance that kills any process after 5s
// whether it's still receiving data or not:
const git: SimpleGit = simpleGit({
   timeout: {
      block: 5000,
      stdOut: false,
      stdErr: false
   }
});

Because simple-git passes arguments directly to a git child process, all user-provided input must be validated and sanitized. To prevent arbitrary command execution or credential disclosure, simple-git throws a GitPluginError when it detects high-risk patterns (like custom binaries or protocol overrides) unless you explicitly opt-in using the unsafe configuration object during initialization.

Warning: These opt-in flags are safety nets and do not replace the need for proper input validation.

The simplest way to provide credentials is to include the username and password directly in the remote URL: https://username:password@repository-url.

const USER = 'something';
const PASS = 'somewhere';
const REPO = 'github.com/username/private-repo';
const remote = `https://${USER}:${PASS}@${REPO}`;

simpleGit().clone(remote);