Gitty is a Node.js wrapper for the Git CLI. It's syntax closely resembles the Git command line syntax to asynchronously execute common commands, and parses the output into operable objects - depending on the call.
$ npm install gitty
Note: If you encounter an error during installation on Mac OSX, make sure you have the XCode Command Line Tools installed. Gitty depends on pty.js for authenticated operations - which requires GCC compiler.
First, require Gitty.
var git = require('gitty');
The "meat" of the functionality is encapsulated in instances of a Repository object. This object is instantiated with the path to the repository you wish to perform actions on.
var myRepo = git('/path/to/repo');
// sugar for --> new git.Repository('/path/to/repo');
Now you can call this instance of Repository's methods. For example, to execute git log for myRepo, you would do:
myRepo.log(function(err, log) {
if (err) {
// handle error
} else {
// do something with `log`
}
});
A complete list of the available methods is below, as well as other Gitty functions.
Creates an instance of gitty.Repository from the given path. Each instance contains the following properties and has access to the following methods.
Passes a 2-dimensional array to the callback containing data that can be consumed by a UI for generating a network graph
callback
Function(err, graph_data)Type: Boolean
Based on the existence of the .git/ directory under the instance path.
Type: String
Directory name of the instantiated Repository.
Type: String
Normalized copy of the instance path.
Initializes the directory as a Git repository.
callback
Function(err)flags
Array['--bare','--shared']Passes commit history as array to callback. Optionally do this this synchronously - not recommended
callback
Function(err, log)Passes a status object into the callback
callback
Function(err, status)Stages the passed array of files for commit. Optionally do this this synchronously - not recommended
callback
Function(err)Removes the passed array of files for commit
callback
Function(err)Removes passed array of files from staging area
callback
Function(err)Commits the current staged files. Optionally do this this synchronously - not recommended
message
Stringcallback
Function(err, output)Passes object denoting current branch and array of other branches
callback
Function(err, branches)Creates a new branch from the given branch name
callback
Function(err)Performs checkout on given branch
branch
Stringcallback
Function(err, branches)Performs a merge of the current branch with the specified one
branch
Stringcallback
Function(err)Adds a new remote
name
Stringurl
Stringcallback
Function(err)Changes url of an existing remote
name
Stringurl
Stringcallback
Function(err)Removes the specified remote
name
Stringcallback
Function(err)Passes key-value pairs to callback formatted: remote : url
callback
Function(err, remotes)Pushes the specified branch to the specified remote
remote
Stringbranch
Stringcallback
Function(err, success)creds (optional)
Object{ user : 'username', pass : 'password' }Note: This method does not use an instance of
Command(), see Authenticated Repositories
Pulls the specified branch from the specified remote
remote
Stringbranch
Stringcallback
Function(err, success)creds (optional)
Object{ user : 'username', pass : 'password' }Note: This method does not use an instance of
Command(), see Authenticated Repositories
Resets the repository's HEAD to the specified commit and passes commit log to callback
hash
Stringcallback
Function(err, log)Creates an instance of gitty.Command from the given arguments. This is constructor is used primarily internally, for executing Repository methods, however, it is exposed - see Extending Gitty. Each instance contains the following properties and has access to the following methods.
Type: String
Directory path for the instantiated Command object
Type: String
Assembled command string based on the instantiated operation, flags, and options
Executes a child_process by the instance's command property in the directory specified by the instance's path property
callback
Function(err, stdout, stderr)Note: This is a wrapper for Node's
child_process.execthat, first, validates the path as a Git repository before execution. If the path fails validation, anErrorwill be thrown.
Does global Git configuration
key
Stringvalue
Stringcallback (optional)
Function(err)Clones the repository at url into the specified path
path
Stringurl
Stringcallback
Function(err, success)creds (optional)
Object{ user : 'username', pass : 'password' }Note: This method does not use an instance of
Command(), see Authenticated Repositories
One challenge that was faced while developing Gitty was performing any authenticated operations. Since OpenSSH does not read input from stdin for authentication, but rather a psuedo-terminal - Gitty uses pty.js (https://github.com/chjj/pty.js/) to spawn a pseudo-terminal for operations that may require authentication, such as pull, push, and clone.
Credentials are always passed as the last argument and are optional. Below is an example of an authenticated Repository.push().
// do authenticated push to origin
myRepo.push('origin', 'master', function(err, succ) {
if (err) {
console.log(err);
} else {
console.log(succ);
}
}, {
user : 'username',
pass : 'password'
});
This format is consistent for all authenticated operations. Keep this in mind if you are extending Gitty with an operation that requires authentication, and be sure to read the pty.js documentation.
Almost all of the Repository methods are simply convenience wrappers around instances of Command. This makes extending the Repository constructor with custom methods easy as pie! Let's run through a quick example. Let's say we want to add a method for creating a new branch and automatically switching to it. What do we need to do?
Repository prototypeCommandThree steps is all it should take to add a new method to the Repository constructor, and below is how you might do it.
// require gitty
var git = require('gitty');
// create new prototype endpoint
// we want to pass a branch name and callback into this method
git.Repository.prototype.branchAndCheckout = function(name, callback) {
// save the scope of the repository
var repo = this
// create a new instance of Command
, cmd = new git.Command(repo.path, 'checkout', ['-b'], name);
// execute the command and determine the outcome
cmd.exec(function(error, stdout, stderr) {
var err = error || stderr;
// call the callback function in the repository scope
// passing it err and stdout
callback.call(repo, err, stdout);
});
};
It's a simple as that. Now you would be able to use this custom method in your application, like so:
myRepo.branchAndCheckout('myBranch', function(err, data) {
if (err) {
// throw error
} else {
console.log(data);
}
});
The output parser is simply a collection of functions that accept the string output of an executed command, and turn it into something that can be operated on. For example, the output from git log gets converted to an array of object-literals before being returned back to the callback for Repository.log().
One of the reasons I have tried to make Gitty so easy to extend is, well, because I want you to extend it! It is not a wrapper for every possible Git operation, but it most certainly could be, and with minimal coding too! Contributions are always welcome and encouraged. However, to keep Gitty clean and healthy, before making additions consider the following:
If you can answer "yes" to these 3 questions, then send a pull request!
Gitty was written by Gordon Hall (gordon@gordonwritescode.com)
Licensed under MIT license
FAQs
A Node.js wrapper for the Git CLI
The npm package gitty receives a total of 483 weekly downloads. As such, gitty popularity was classified as not popular.
We found that gitty demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.