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);
});