git-wrapper2-promise

A wrapper around the git executable with convenience functions for common commands, promisified via child-process-promise.

Built on top of git-wrapper2 version 0.2.5, which provided additional convenience functions to the original git-wrapper, git-wrapper2-promise provides the same functionality with a simpler, promise-based interface. Far from being a simple Promise.promisifyAll solution, this library updates the git-wrapper core by replacing the child-process module with the child-process-promise module (which uses q promises), resulting in a higher-quality promisification implementation.

NOTE In addition to implementing promises, this library removes the event emissions that were present in previous versions (git-wrapper and git-wrapper2). If you desire event emissions, you must therefore implement them yourself.

NOTE Unlike previous versions (git-wrapper and git-wrapper2), this library does not call process.chdir() to change the process current working directory to the repository directory (as provided by the git-dir option). This has various issues if consumer code changes to a different directory (particularly in asynchronous logic). Instead, it relies on proper usage of git-dir and work-tree options. For this to work easily for consumers, if a git-dir option is provided, it is automatically appended with the .git sub-directory, and if a work-tree option is not specified in combination with git-dir, it will automatically be set to the specified base repository directory.

Installation

npm install git-wrapper2-promise

API

var git = new Git(options);

Constructor. See git(1) for available options.

options Object. Examples: { paginate: true } enables pagination. { 'git-dir': '../.git' } specifies a different .git directory.

var git = new Git(options);

git.exec(command [[, options], args]);

Executes a git command and returns a promise for a pre-processed child process object. See the Git Reference for available commands.

command String. Examples: 'init', 'log', 'commit', etc.
options Object. The options for a git command. E.g. { f: true } to force a command (equivalent to adding -f on the command line).
args Array[String]. The arguments for a git command. E.g. some files for git add.

git.exec(command, args).then(function(childProcess) {
	return childProcess.stdout.toString();

}).catch(function(childProcess) {
	console.error(childProcess.stderr);
});

git.isRepo();

Checks to see if the directory is a git repository. Returns a promise for a boolean indicating whether or not it is a repo.

var git = new Git({'git-dir': '/path/to/gitroot'});
git.isRepo().then(function(isRepo) {
	console.log('isRepo:', isRepo);
}).catch(function(err) {
	console.error(err);
});

git.clone(repo, dir);

Clones a repository to the destination dir and returns a promise for a pre-processed child process object.

repo String. Remote repository.
dir String. Local directory to clone into.

git.clone(repo, dir).then(function(childProcess) {
	console.log(childProcess.stdout.toString());
}).catch(function(err) {
	console.error(err);
});

git.pull([remote], [branch])

Performs a git pull command against the repository and returns a promise for a pre-processed child process object. If remote or branch are not provided they will default to origin and master respectively.

remote String. Name of the remote target.
branch String. Branch name to pull.

git.pull(remote, branch).then(function(childProcess) {
	console.log(childProcess.stdout.toString());
}).catch(function(err) {
	console.error(err);
});

git.add(which)

Perform a git add command, staging files for a commit and returns a promise for a pre-processed child process object.

which String. Which files to stage, seperated by spaces.

git.add('/path/to/repo/file').then(function(childProcess) {
	console.log(childProcess.stdout.toString());
}).catch(function(err) {
	console.error(err);
});

git.commit(msg)

Commits staged changes with the given msg as the commit message and returns a promise for a pre-processed child process object.

msg String. Body of the commit message.

git.commit(msg).then(function(childProcess) {
	console.log(childProcess.stdout.toString());
}).catch(function(err) {
	console.error(err);
});

git.push([remote], [branch])

Pushes changes in the local repository to a remote and returns a promise for a pre-processed child process object. If remote or branch are not provided, the defaults will be origin and master respectively.

remote String. Name of the remote target.
branch String. Branch name to pull.

git.push(remote, branch).then(function(childProcess) {
	console.log(childProcess.stdout.toString());
}).catch(function(err) {
	console.error(err);
});

git.save(msg)

Convenience function for performing git.add, git.commit, and git.push in one function call. Returns a promise for the last child process (git push). Using this will automatically stage all unstaged changes, commit, and then push.

msg String. Body of the commit message.

git.save(msg).then(function(childProcess) {
	console.log(childProcess.stdout.toString());
}).catch(function(err) {
	console.error(err);
});

git.log(options)

Performs a git log command and returns a promise for a pre-processed child process object. options are an array of command line options you might want to provide, such as ['-n', 2] to limit the results to only the last 2 commits.

options Array. Command line options for the git log command.

git.log(options).then(function(childProcess) {
	console.log(childProcess.stdout.toString());
}).catch(function(err) {
	console.error(err);
});

TranceGeniK/git-wrapper2-promise