git-wrapper2-promise

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

$3

Constructor. See git(1) for available options.

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

`` Example:
var git = new Git(options);
`

$3

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.

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

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

$3

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

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

$3

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.

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

$3

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.

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

$3

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.

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

$3

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.

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

$3

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.

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

$3

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.

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

$3

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.

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