git-promise
Simple wrapper that allows you to run any git
command using a more intuitive syntax.
Getting Started
npm install git-promise --save
Once installed, you can use it in your JavaScript files like so:
const git = ; const branch = await ;console; // This is your current branch
The module will handle git exit code automatically, so
const git = ; try await ; // Everything was fine catch err // Something went bad, maybe merge conflict? console;
err
is an Error
object augmented with code
property. The following code:
try await ; catch err console; console; console; console;
will log:
MESSAGE
Cloning into 'notExistingExample'...
fatal: remote error: Repository does not exist
The requested repository does not exist, or you do not have permission to
access it.
}
ERROR CODE
128
Advanced usage
The git
command accepts a second parameter that can be used to parse the output or to deal with non 0 exit code.
const git = ; const branch = await ;console; // This is your current branch
The callback accepts 2 parameters, (stdout, error)
, where stdout
is the output of the git command and error
is either null
or an Error
in case the git command fails.
The return value of this function will be the resolved value of the promise.
If the error
parameter is not specified, it'll be handled automatically and the promise will be rejected in case of non 0 error codes.
const git = ; ;
Argument parsing
Version 1.0 changes the way the input command is parsed, so instead of executing anything that gets passed as the first parameter, it makes sure that git
is the only executable used.
git("status | grep hello")
won't be executed as a shell command, but everything will be passed as arguments to git
, likely resulting in an error in this specific case.
If your git
command stops working after upgrading to version 1.0
- Make sure you're only executing git commands.
- Try passing an array of arguments instead of a string. For instance:
git(["merge-base", "--is-ancestor", "master", "HEAD"]);
.
Chaining commands
Imagine to be on a local branch which is not fast forward with master and you want to know which commit were pushed on master after the forking point:
const git = ; { return ;} { return ;} const forkCommit = await ;const commits = await ;
Working directory
By default all git commands run in the current working directory (i.e. process.cwd()
).
You can use the following syntax to run a git command in different folder
const git = ; await ;
Custom git executable
By default any command tries to use git
in $PATH
, if you have installed git
in a funky location you can override this value using gitExec
.
const git = ; await ;
Utility methods
This module comes with some utility methods to parse the output of some git commands
const util = ;
util.extractStatus(output [, lineSeparator])
Parse the output of git status --porcelain
and returns an object with
{
branch: "current branch name, only if git status -b is used",
index: {
modified: ["list of files modified in the index"],
added: ["list of files added in the index"],
deleted: ["list of files deleted in the index"],
renamed: ["list of files renamed in the index"],
copied: ["list of files copied in the index"]
},
workingTree: {
modified: ["list of files modified in the local working tree"],
added: ["list of files added / renamed / copied in the local working tree"],
deleted: ["list of files deleted in the local working tree"]
}
}
The method works both with or without option -z
.
util.hasConflict(output)
Try to determine if there's a merge conflict from the output of git merge-tree
const git = ;const util = ; ;
Release History
- 1.0.0
BREAKING CHANGE: The returned value is now a standard JavaScript
Promise
, not anymore aQ
promise. BREAKING CHANGE: Internally the library switches fromshell
toexecFile
to avoid problems with non sanitized input commands. BREAKING CHANGE: Callbacks using 2 parameters now receive an error as second parameter instead of an error code. - 0.3.1 Fix current working directory not switching back when command exits with error
- 0.3.0 Custom git executable with
gitExec
option - 0.2.0 Change current working directory
- 0.1.0 Just started