What is simple-git?
The simple-git npm package is a light-weight interface for running git commands in any node.js application. It provides a chainable git API for node and supports TypeScript types.
What are simple-git's main functionalities?
Checking out branches
This feature allows you to checkout different branches within your git repository.
const simpleGit = require('simple-git');
const git = simpleGit();
git.checkout('some-branch-name');
Pulling from a remote repository
This feature is used to pull the latest changes from a remote repository.
const simpleGit = require('simple-git');
const git = simpleGit();
git.pull('origin', 'master');
Committing changes
This feature allows you to stage changes and commit them to your local repository.
const simpleGit = require('simple-git');
const git = simpleGit();
git.add('./*').commit('Commit message');
Pushing to a remote repository
This feature enables you to push your committed changes to a remote repository.
const simpleGit = require('simple-git');
const git = simpleGit();
git.push('origin', 'master');
Listing remote repositories
This feature allows you to list all the remote repositories your local repo is connected to.
const simpleGit = require('simple-git');
const git = simpleGit();
git.getRemotes(true).then(remotes => console.log(remotes));
Other packages similar to simple-git
nodegit
NodeGit is a more comprehensive Git library for Node.js, providing a 1-to-1 mapping of Git concepts. It is more complex and has a steeper learning curve compared to simple-git, but it offers more detailed control over the Git operations.
isomorphic-git
Isomorphic-git is a pure JavaScript implementation of Git that works in both Node.js and browser environments. It is similar to simple-git but can be used for front-end projects as well, making it more versatile in different environments.
gitty
Gitty is another simple Git command wrapper for Node.js. It has a simpler API than simple-git but is not as actively maintained and lacks some of the more advanced features found in simple-git.
Simple Git
A light weight interface for running git commands in any node.js application.
Installation
Easiest through npm: npm install simple-git
Dependencies
Relies on git already having been installed on the system, and that it can be called
using the command git
.
Usage
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.
.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
.checkout(checkoutWhat, handlerFn)
checks out the supplied tag, revision or 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
.push(remote, branch, handlerFn)
pushes to a named remote and named branch
.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
.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
string.
Examples
// 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');