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

Easiest through npm: npm install simple-git

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

Include into your JavaScript app using:

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

Include in a TypeScript app using:

// Import `SimpleGit` types and the default function exported from `simple-git`
import simpleGit, {SimpleGit} from 'simple-git';
const git: SimpleGit = simpleGit();

// prior to v2.6.0 required importing from `simple-git/promise`
// this import is still available but is now deprecated
import gitP, {SimpleGit} from 'simple-git/promise';
const git: SimpleGit = gitP();

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

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

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

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

Each of the methods in the API listing below can be called in a chain and will be called in series after each other. The result of each task is sent to a trailing callback argument:

const simpleGit = require('simple-git');
const git = simpleGit();
git.init(onInit).addRemote('origin', '[email protected]: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 .

Based on the same API as the callback API detailed below, but instead of returning the simpleGit object for chaining, each task returns a promise to be fulfilled when that task is completed.

const simpleGit = require('simple-git');
const git = simpleGit();

// using promises on each task
git.init()
   then(function onInit (initResult) { })
  .then(() => git.addRemote('origin', '[email protected]:steveukx/git-js.git'))
  .then(function onRemoteAdd (addRemoteResult) { })
  .catch(err => console.error(err));

// using a promise at the end of the chain to check for failures in any task
git.init().addRemote('origin', '[email protected]:steveukx/git-js.git')
  .catch(err => console.error(err));

Whether in TypeScript or JavaScript in node.js version 8 or above the promise API will work automatically with await:

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

const git: SimpleGit = simpleGit();
const initResult = await git.init();
const addRemoteResult = await git.addRemote('origin', '[email protected]:steveukx/git-js.git');

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 () {}

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.

• .clean(mode) clean the working tree. Mode should be "n" - dry run or "f" - force
• .clean(cleanSwitches [,options]) set cleanSwitches to a string containing any number of the supported single character options, optionally with a standard options object

• .checkout(checkoutWhat [, options]) - checks out the supplied tag, revision or branch when supplied as a string, additional arguments supported by git checkout can be supplied as an options object/array.

• .checkout(options) - uses the checks out the supplied options object/array to check out.

• .checkoutBranch(branchName, startPoint) - checks out a new branch from the supplied start point.

• .checkoutLocalBranch(branchName) - checks out a new local branch

• .addConfig(key, value, append = false) add a local configuration property, when append is set to true the configuration setting is appended to rather than set in the local config.
• .listConfig() reads the current configuration and returns a ConfigListSummary

• .init(bare [, options]) initialize a repository using the boolean bare parameter to intialise a bare repository. Any number of other arguments supported by git init can be supplied as an options object/array.

• .init([options]) initialize a repository using any arguments supported by git init supplied as an options object/array.

• .merge(options) runs a merge using any configuration options supported by git merge. Conflicts during the merge result in an error response, the response is an instance of MergeSummary whether it was an error or success. When successful, the MergeSummary has all detail from a the PullSummary along with summary detail for the merge. When the merge failed, the MergeSummary contains summary detail for why the merge failed and which files prevented the merge.

• .mergeFromTo(from, to [, options]) - merge from one branch to another, similar to .merge but with the from and to supplied as strings separately to any additional the options.

• .pull([options]) pulls all updates from the default tracked remote, any arguments supported by git pull can be supplied as an options object/array.

• .pull(remote, branch[, options]) pulls all updates from the specified remote branch (eg 'origin'/'master') along with any custom options object/array

• .push([options]) pushes to a named remote/branch using any supported options from the git push command. Note that simple-git enforces the use of --verbose --porcelain options in order to parse the response. You don't need to supply these options.

• .push(remote, branch[, options]) pushes to a named remote/branch, supports additional options from the git push command.

• .pushTags(remote[, options]) pushes local tags to a named remote (equivalent to using .push([remote, '--tags']))

• .addRemote(name, repo, [options]) adds a new named remote to be tracked as name at the path repo, optionally with any supported options for the git add call.
• .getRemotes([verbose]) gets a list of the named remotes, supply the optional verbose option as true to include the URLs and purpose of each ref
• .listRemote([options]) lists remote repositories - there are so many optional arguments in the underlying git ls-remote call, just supply any you want to use as the optional options eg: git.listRemote(['--heads', '--tags'], console.log)
• .remote([options]) runs a git remote command with any number of options
• .removeRemote(name) removes the named remote

• .reset(resetMode, [resetOptions]) resets the repository, sets the reset mode to one of the supported types (use a constant from the exported ResetMode enum, or a string equivalent: mixed, soft, hard, merge, keep). Any number of other arguments supported by git reset can be supplied as an options object/array.

• .reset(resetOptions) resets the repository with the supplied options

• .reset() resets the repository in soft mode.

-.revparse([options]) sends the supplied options to git rev-parse and returns the string response from git.

• .checkIsRepo() gets whether the current working directory is a descendent of a git repository.
• .checkIsRepo('bare') gets whether the current working directory is within a bare git repo (see either git clone --bare or git init --bare).
• .checkIsRepo('root') gets whether the current working directory is the root directory for a repo (sub-directories will return false).

• .status([options]) gets the status of the current repo, resulting in a StatusResult. Additional arguments supported by git status can be supplied as an options object/array.

• .subModule(options) Run a git submodule command with on or more arguments passed in as an options array or object
• .submoduleAdd(repo, path) Adds a new sub module
• .submoduleInit([options] Initialises sub modules, the optional options argument can be used to pass extra options to the git submodule init command.
• .submoduleUpdate(subModuleName, [options]) Updates sub modules, can be called with a sub module name and options, just the options or with no arguments |

Where the task accepts custom options (eg: pull or commit), these can be supplied as an object, the keys of which will all be merged as trailing arguments in the command string, or as a simple array of strings.

When the value of the property in the options object is a string, that name value pair will be included in the command string as name=value. For example:

// results in 'git pull origin master --no-rebase'
git().pull('origin', 'master', {'--no-rebase': null})

// results in 'git pull origin master --rebase=true'
git().pull('origin', 'master', {'--rebase': 'true'})

Options can also be supplied as an array of strings to be merged into the task's commands in the same way as when an object is used:

// 
git.pull('origin', 'master', ['--no-rebase'])

Major release 2.x changes the way the queue of tasks are handled to use promises internally and makes available the .then and .catch methods for integrating with promise consumers or async await.

TypeScript is used by default for all new code, allowing for auto-generated type definitions and a phased re-write of the library rather than a big-bang.

For a per-release overview of changes, see the changelog.

When upgrading to release 2.x from 1.x, see the changelog for the release 2.0.0

• 2.13.0 .push now returns a PushResult parsed representation of the response.

• 2.11.0 treats tasks chained together as atomic, where any failure in the chain prevents later tasks from executing and tasks called from the root git instance as the origin of a new chain, and able to be run in parallel without failures impacting one anther. Prior to this version, tasks called on the root git instance would be cancelled when another one failed.

• 2.7.0 deprecates use of .silent() in favour of using the debug library - see Enable Logging for further details.

• 2.6.0 introduced .then and .catch as a way to chain a promise onto the current step of the chain. Importing from simple-git/promise instead of just simple-git is no longer required and is actively discouraged.

For the full history see the changelog;

When the methods of simple-git are chained together, they create an execution chain that will run in series, useful for when the tasks themselves are order-dependent, eg:

const git = simpleGit();
git.init().addRemote('origin', 'https://some-repo.git').fetch();

Each task requires that the one before it has been run successfully before it is called, any errors in a step of the chain should prevent later steps from being attempted.

When the methods of simple-git are called on the root instance (ie: git = simpleGit()) rather than chained off another task, it starts a new chain and will not be affected failures in tasks already being run. Useful for when the tasks are independent of each other, eg:

const git = simpleGit();
const results = await Promise.all([
    git.raw('rev-parse', '--show-cdup').catch(swallow),
    git.raw('rev-parse', '--show-prefix').catch(swallow),
]);
function swallow (err) { return null }

Each simple-git instance limits the number of spawned child processes that can be run simultaneously and manages the queue of pending tasks for you. Configure this value by passing an options object to the simpleGit function, eg:

const git = simpleGit({ maxConcurrentProcesses: 10 });

Treating tasks called on the root instance as the start of separate chains is a change to the behaviour of simple-git and was added in version 2.11.0.

When no suitable wrapper exists in the interface for creating a request, it is possible to run a command directly using git.raw([...], handler). The array of commands are passed directly to the git binary:

const git = require('simple-git');
const path = '/path/to/repo';
const commands = [ 'config', '--global', 'advice.pushNonFastForward', 'false' ];

// using an array of commands
git(path).raw(commands, (err, result) => {

  // err is null unless this command failed
  // result is the raw output of this command

});

// using a var-args of strings and awaiting rather than using the callback
const result = await git(path).raw(...commands);

The easiest way to supply a username / password to the remote host is to include it in the URL, for example:

const USER = 'something';
const PASS = 'somewhere';
const REPO = 'github.com/username/private-repo';

const git = require('simple-git');
const remote = `https://${USER}:${PASS}@${REPO}`;

git().silent(true)
  .clone(remote)
  .then(() => console.log('finished'))
  .catch((err) => console.error('failed: ', err));

Be sure to enable silent mode to prevent fatal errors from being logged to stdout.

Pass one or more environment variables to the child processes spawned by simple-git with the .env method which supports passing either an object of name=value pairs or setting a single variable at a time:

const GIT_SSH_COMMAND = "ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no";

const git = require('simple-git');

git()
  .env('GIT_SSH_COMMAND', GIT_SSH_COMMAND)
  .status((err, status) => { /*  */ })

git().env({ ...process.env, GIT_SSH_COMMAND })
  .status()
  .then(status => { })
  .catch(err => {});
  

Note - when passing environment variables into the child process, these will replace the standard process.env variables, the example above creates a new object based on process.env but with the GIT_SSH_COMMAND property added.

To import with TypeScript:

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

const git: SimpleGit = simpleGit();
const status: StatusResult = await git.status();

For each task run, the return is the same SimpleGit instance for ease of building a series of tasks that all run sequentially and are treated as atomic (ie: if any step fails, the later tasks are not attempted).

To work with promises (either directly or as part of async/await), simply call the function as before:

const simpleGit = require('simple-git');
const git = simpleGit();

// async / await
const status = await git.status();

// promise
git.status().then(result => {...});

When the git process exits with a non-zero status (or in some cases like merge the git process exits with a successful zero code but there are conflicts in the merge) the task will reject with a GitError when there is no available parser to handle the error or a GitResponseError for when there is.

See the err property of the callback:

git.merge((err, mergeSummary) => {
   if (err.git) {
      mergeSummary = err.git; // the failed mergeSummary
   }
})

Catch errors with try/catch in async code:

try {
  const mergeSummary = await git.merge();
  console.log(`Merged ${ mergeSummary.merges.length } files`);
}
catch (err) {
  // err.message - the string summary of the error
  // err.stack - some stack trace detail
  // err.git - where a parser was able to run, this is the parsed content

  console.error(`Merge resulted in ${ err.git.conflicts.length } conflicts`);
}

Catch errors with a .catch on the promise:

const mergeSummary = await git.merge()
   .catch(err => {
      if (err.git) { return err.git; } // the unsuccessful mergeSummary
      throw err;                       // some other error, so throw
   });

if (mergeSummary.failed) {
   console.error(`Merge resulted in ${ mergeSummary.conflicts.length } conflicts`);
}

With typed errors available in TypeScript

import simpleGit, { MergeSummary, GitResponseError } from 'simple-git';
try {
  const mergeSummary = await simpleGit().merge();
  console.log(`Merged ${ mergeSummary.merges.length } files`);
}
catch (err) {
  // err.message - the string summary of the error
  // err.stack - some stack trace detail
  // err.git - where a parser was able to run, this is the parsed content
  const mergeSummary: MergeSummary = (err as GitResponseError<MergeSummary>).git;
  const conflicts = mergeSummary?.conflicts || [];
  
  console.error(`Merge resulted in ${ conflicts.length } conflicts`);
}

This library uses debug to handle logging, to enable logging, use either the environment variable:

"DEBUG=simple-git" node ./your-app.js 

Or explicitly enable logging using the debug library itself:

require('debug').enable('simple-git');

If the regular logs aren't sufficient to find the source of your issue, enable one or more of the following for a more complete look at what the library is doing:

• DEBUG=simple-git:task:* adds debug output for each task being run through the library
• DEBUG=simple-git:task:add:* adds debug output for specific git commands, just replace the add with the command you need to investigate. To output multiple just add them both to the environment variable eg: DEBUG=simple-git:task:add:*,simple-git:task:commit:*

There are a few potential reasons:

• git isn't available as a binary for the user running the main node process, custom paths to the binary can be used with the .customBinary(...) api option.

• the working directory passed in to the main simple-git function isn't accessible, check it is read/write accessible by the user running the node process. This library uses @kwsites/file-exists to validate the working directory exists, to output its logs add @kwsites/file-exists to your DEBUG environment variable. eg:

  DEBUG=@kwsites/file-exists,simple-git node ./your-app.js

The properties of git.log are fetched using the character sequence ò as a delimiter. If your commit messages use this sequence, supply a custom splitter in the options, for example: git.log({ splitter: '💻' })

If the simple-git api doesn't explicitly limit the scope of the task being run (ie: git.add() requires the files to be added, but git.status() will run against the entire repo), add a pathspec to the command using trailing options:

const git = simpleGit();
const wholeRepoStatus = await git.status();
const subDirStatusUsingOptArray = await git.status(['--', 'sub-dir']);
const subDirStatusUsingOptObject = await git.status({'--': null, 'sub-dir': null});

async function status (workingDir) {
   const git = require('simple-git');
   
   let statusSummary = null;
   try {
      statusSummary = await git(workingDir).status();
   }
   catch (e) {
      // handle the error
   }
   
   return statusSummary;
}

// using the async function
status(__dirname   '/some-repo').then(status => console.log(status));

const simpleGit = require('simple-git');
const git = simpleGit(__dirname);

git.checkIsRepo()
   .then(isRepo => !isRepo && initialiseRepo(git))
   .then(() => git.fetch());

function initialiseRepo (git) {
   return git.init()
      .then(() => git.addRemote('origin', 'https://some.git.repo'))
}

require('simple-git')(__dirname   '/some-repo')
     .pull()
     .tags((err, tags) => console.log("Latest available tag: %s", tags.latest));

// update repo and when there are changes, restart the app
require('simple-git')()
     .pull((err, update) => {
        if(update && update.summary.changes) {
           require('child_process').exec('npm restart');
        }
     });

require('simple-git')()
     .init()
     .add('./*')
     .commit("first commit!")
     .addRemote('origin', 'https://github.com/user/repo.git')
     .push('origin', 'master');

require('simple-git')()
     .add('./*')
     .commit("first commit!")
     .addRemote('origin', 'some-repo-url')
     .push(['-u', 'origin', 'master'], () => console.log('done'));

require('simple-git')()
     .outputHandler((command, stdout, stderr) => {
        stdout.pipe(process.stdout);
        stderr.pipe(process.stderr);
     })
     .checkout('https://github.com/user/repo.git');

require('simple-git')()
     .exec(() => console.log('Starting pull...'))
     .pull((err, update) => {
        if(update && update.summary.changes) {
           require('child_process').exec('npm restart');
        }
     })
     .exec(() => console.log('pull done.'));

require('simple-git')()
    .log((err, log) => console.log(log))
    .log('0.11.0', '0.12.0', (err, log) => console.log(log));

require('simple-git')()
    .addConfig('user.name', 'Some One')
    .addConfig('user.email', '[email protected]')
    .commit('committed as "Some One"', 'file-one')
    .commit('committed as "Another Person"', 'file-two', { '--author': '"Another Person <[email protected]>"' });

require('simple-git')()
    .listRemote(['--get-url'], (err, data) => {
        if (!err) {
            console.log('Remote url for repository at '   __dirname   ':');
            console.log(data);
        }
    });