A light weight interface for running git commands in any node.js application.
Easiest through npm: npm install simple-git
Relies on git already having been installed on the system, and that it can be called
using the command git
.
Include into your app using:
var simpleGit = require('simple-git')( workingDirPath );
where the workingDirPath
is optional, defaulting to the current directory.
Use simpleGit
by chaining any of its functions together. Each function accepts an optional final argument which will
be called when that step has been completed. When it is called it has two arguments - firstly an error object (or null
when no error occurred) and secondly the data generated by that call.
init(bare, handlerFn)
initialize a repository, optional bare
parameter makes intialized repository bare.
.clone(repoPath, localPath, handlerFn)
clone a remote repo at repoPath
to a local directory at localPath
.diff(options, handlerFn)
get the diff of the current repo compared to the last commit with a set of options supplied as a string
.diff(handlerFn)
get the diff for all file in the current repo compared to the last commit
.pull(remote, branch, handlerFn)
pull all updates from the repo ('origin'/'master')
.fetch(remote, branch, handlerFn)
update the local working copy database with changes from a remote repo
.fetch(handlerFn)
update the local working copy database with changes from the default remote repo and branch
.tags(handlerFn)
list all tags
.addTag(name, handlerFn)
adds a lightweight tag to the head of the current branch
.addAnnotatedTag(tagName, tagMessage, handlerFn)
adds an annotated tag to the head of the current branch
.log([options], handlerFn)
list commits between options.from
and options.to
tags or branch
(if not specified will show all history). Additionally you can provide options.file
, which is the path to a file in
your repository. Then only this file will be considered.
.checkout(checkoutWhat, handlerFn)
checks out the supplied tag, revision or branch
.checkoutBranch(branchName, startPoint, handlerFn)
checks out a new branch from the supplied start point
.checkoutLocalBranch(branchName, handlerFn)
checks out a new local branch
.checkoutLatestTag(handlerFn)
convenience method to pull then checkout the latest tag
.add([fileA, ...], handlerFn)
adds one or more files to be under source control
.commit(message, handlerFn)
commits changes in the current working directory with the supplied message
.commit(message, [fileA, ...], handlerFn)
commits changes on the named files with the supplied message
.customBinary(gitPath)
sets the command to use to reference git, allows for using a git binary not available on
the path environment variable
.push(remote, branch, handlerFn)
pushes to a named remote and named branch
.pushTags(remote, handlerFn)
pushes tags to a named remote
.silent(isSilent)
sets whether the console should be used for logging errors (defaults to true
when the NODE_ENV
contains the string prod
)
.rm([fileA, ...], handlerFn)
removes any number of files from source control
.rmKeepLocal([fileA, ...], handlerFn)
removes files from source control but leaves them on disk
.addRemote(name, repo, handlerFn)
adds a new named remote to be tracked as name
at the path repo
.removeRemote(name, handlerFn)
removes the named remote
.getRemotes([verbose], handlerFn)
gets a list of the named remotes, when the verbose option is supplied as true,
includes the URLs and purpose of each ref.
.reset(resetMode, handlerFn)
resets the repository (resetMode can be 'hard' or 'soft', handlerFn: (err))
.revparse([options], handlerFn)
wraps git rev-parse. Primarily used to convert friendly commit references (ie branch names) to SHA1 hashes. Options should be an array of string options compatible with the git rev-parse
.status(handlerFn)
gets the status of the current repo
.show([options], handlerFn)
Show various types of objects, for example the file content at a certain commit. options
is the single value string or array of string commands you want to run.
.listRemote([args], handlerFn)
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 args
array of strings eg: git.listRemote(['--heads', '--tags'], console.log.bind(console))
.
outputHandler(handlerFn)
attaches a handler that will be called with the name of the command being run and the
stdout
and stderr
readable streams created by
the child process running that command.
.then(handlerFn)
calls a simple function in the current step
Bumped to a new major revision in the 1.x branch, now uses ChildProcess.spawn
in place of ChildProcess.exec
to
add escaping to the arguments passed to each of the tasks.
Use of these APIs is deprecated and should be avoided as support for them will be removed in future release:
.log([from, to], handlerFn)
list commits between from
and to
tags or branch, switch to supplying the revisions
as an options object instead.
// update repo and get a list of tags
require('simple-git')(__dirname + '/some-repo')
.pull()
.tags(function(err, tags) {
console.log("Latest available tag: %s", tags.latest);
});
// update repo and when there are changes, restart the app
require('simple-git')()
.pull(function(err, update) {
if(update && update.summary.changes) {
require('child_process').exec('npm restart');
}
});
// starting a new repo
require('simple-git')()
.init()
.add('./*')
.commit("first commit!")
.addRemote('origin', 'https://github.com/user/repo.git')
.push('origin', 'master');
// piping to the console for long running tasks
require('simple-git')()
.outputHandler(function (command, stdout, stderr) {
stdout.pipe(process.stdout);
stderr.pipe(process.stderr);
})
.checkout('https://github.com/user/repo.git');
// update repo and print messages when there are changes, restart the app
require('simple-git')()
.then(function() {
console.log('Starting pull...');
})
.pull(function(err, update) {
if(update && update.summary.changes) {
require('child_process').exec('npm restart');
}
})
.then(function() {
console.log('pull done.');
});
// get a full commits list, and then only between 0.11.0 and 0.12.0 tags
require('simple-git')()
.log(function(err, log) {
console.log(log);
})
.log('0.11.0', '0.12.0', function(err, log) {
console.log(log);
})