Simple Git

A lightweight interface for running git commands in any node.js application.

Installation

Use your favourite package manager:

• npm: npm install simple-git
• yarn: yarn add simple-git

System Dependencies

Requires git to be installed and that it can be called using the command git.

Usage

Include into your JavaScript app using common js:

// require the library, main export is a function
const simpleGit = require('simple-git');
simpleGit().clean(simpleGit.CleanOptions.FORCE);

// or use named properties
const { simpleGit, CleanOptions } = require('simple-git');
simpleGit().clean(CleanOptions.FORCE);

Include into your JavaScript app as an ES Module:

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

simpleGit().clean(CleanOptions.FORCE);

Include in a TypeScript app using the bundled type definitions:

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

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

Configuration

Configure each simple-git instance with a properties object passed to the main simpleGit function:

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

const options: Partial<SimpleGitOptions> = {
   baseDir: process.cwd(),
   binary: 'git',
   maxConcurrentProcesses: 6,
   trimmed: false,
};

// when setting all options in a single object
const git: SimpleGit = simpleGit(options);

// or split out the baseDir, supported for backward compatibility
const git: SimpleGit = simpleGit('/some/path', { binary: 'git' });

The first argument can be either a string (representing the working directory for git commands to run in), SimpleGitOptions object or undefined, the second parameter is an optional SimpleGitOptions object.

All configuration properties are optional, the default values are shown in the example above.

Per-command Configuration

To prefix the commands run by simple-git with custom configuration not saved in the git config (ie: using the -c command) supply a config option to the instance builder:

// configure the instance with a custom configuration property
const git: SimpleGit = simpleGit('/some/path', { config: ['http.proxy=someproxy'] });

// any command executed will be prefixed with this config
// runs: git -c http.proxy=someproxy pull
await git.pull();

Configuring Plugins

• AbortController Terminate pending and future tasks in a simple-git instance (requires node >= 16).

• Custom Binary Customise the git binary simple-git uses when spawning git child processes.

• Completion Detection Customise how simple-git detects the end of a git process.

• Error Detection Customise the detection of errors from the underlying git process.

• Progress Events Receive progress events as git works through long-running processes.

• Spawned Process Ownership Configure the system uid / gid to use for spawned git processes.

• Timeout Automatically kill the wrapped git process after a rolling timeout.

• Unsafe Selectively opt out of simple-git safety precautions - for advanced users and use cases.

Using Task Promises

Each task in the API returns the simpleGit instance for chaining together multiple tasks, and each step in the chain is also a Promise that can be await ed in an async function or returned in a Promise chain.

const git = simpleGit();

// chain together tasks to await final result
await git.init().addRemote('origin', '...remote.git');

// or await each step individually
await git.init();
await git.addRemote('origin', '...remote.git');

Catching errors in async code

To catch errors in async code, either wrap the whole chain in a try/catch:

const git = simpleGit();
try {
   await git.init();
   await git.addRemote(name, repoUrl);
} catch (e) {
   /* handle all errors here */
}

or catch individual steps to permit the main chain to carry on executing rather than jumping to the final catch on the first error:

const git = simpleGit();
try {
   await git.init().catch(ignoreError);
   await git.addRemote(name, repoUrl);
} catch (e) {
   /* handle all errors here */
}

function ignoreError() {}

Using Task Callbacks

In addition to returning a promise, each method can also be called with a trailing callback argument to handle the result of the task.

const git = simpleGit();
git.init(onInit).addRemote('origin', 'git@github.com:steveukx/git-js.git', onRemoteAdd);

function onInit(err, initResult) {}
function onRemoteAdd(err, addRemoteResult) {}

If any of the steps in the chain result in an error, all pending steps will be cancelled, see the parallel tasks section for more information on how to run tasks in parallel rather than in series .

Task Responses

Whether using a trailing callback or a Promise, tasks either return the raw string or Buffer response from the git binary, or where possible a parsed interpretation of the response.

For type details of the response for each of the tasks, please see the TypeScript definitions.

Upgrading from Version 2

From v3 of simple-git you can now import as an ES module, Common JS module or as TypeScript with bundled type definitions. Upgrading from v2 will be seamless for any application not relying on APIs that were marked as deprecated in v2 (deprecation notices were logged to stdout as console.warn in v2).

API