Skip to content
Native Node bindings to Git.
JavaScript C++ Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Node.js libgit2 bindings

Created by Tim Branyen @tbranyen

Currently under active development (and seeking contributors), nodegit provides asynchronous native bindings to the libgit2 C API.

Building and installing


To run nodegit you need Node.js and to run unit tests you will need to have git installed and accessible from your PATH to fetch any vendor/ addons.

Easy install (Recommended)

This will install and configure everything you need to use nodegit.

$ sudo npm install nodegit

Mac OS X/Linux/Unix

Install nodegit by cloning source from GitHub and running the configure, make, and make install commands:

*Note: nodegit assumes your library path exists at ~/.node_libraries you can change this by specifying a new path*

$ git clone git://
$ cd nodegit

$ ./configure
$ make
$ make install

$ make install NODE_LIB_PATH=/path/to/your/libraries

*Updating to a new version*

$ make update

$ make update NODE_LIB_PATH=/path/to/your/libraries

Windows via Cygwin

nodegit has a build issue under Windows that current makes it impossible to use.

Instructions on compiling Node.js on a Windows platform can be found here: [](\))

API Example Usage

Git Log Emulation

Convenience API

var git = require( 'nodegit' );

// Read a repository
git.repo( '.git', function( err, repo ) {
    // Success is always 0, failure is always an error string
    if( err ) { throw err; }

    // Use the master branch
    repo.branch( 'master', function( err, branch ) {
        if( err ) { throw err; }

        // Iterate over the revision history
        branch.history.each( function( i, commit ) {

            // Print out `git log` emulation
            console.log( 'commit ' + commit.sha );
            console.log( + '<' + + '>' );
            console.log( commit.time );
            console.log( '\n' );
            console.log( commit.message );
            console.log( '\n' );


var git = require( 'nodegit' ).raw;

// Create instance of Repo constructor
var repo = new git.Repo();

// Read a repository '.git', function( err ) {
    // Err is an integer, success is 0, use strError for string representation
    if( err ) {
        var error = new git.Error();
        throw error.strError( err );

    // Create instance of Ref constructor with this repository
    var ref = new git.Ref( repo );

    // Find the master branch
    repo.lookupRef( ref, '/refs/heads/master', function( err ) {
        if( err ) {
          var error = new git.Error();
          throw error.strError( err );

        // Create instance of Commit constructor with this repository
        var commit = new git.Commit( repo ),
            // Create instance of Oid constructor
            oid = new git.Oid();

        // Set the oid constructor internal reference to this branch reference
        ref.oid( oid );

        // Lookup the commit for this oid
        commit.lookup( oid, function() {
            if( err ) {
              var error = new git.Error();
              throw error.strError( err );

            // Create instance of RevWalk constructor with this repository
            var revwalk = new git.RevWalk( repo );

            // Push the commit as the start to walk
            revwalk.push( commit );

            // Recursive walk
            function walk() {
                // Each revision walk iteration yields a commit
                var revisionCommit = new git.Commit( repo );

       revisionCommit, function( err ) {
                    // Finish recursion once no more revision commits are left
                    if( err ) { return; }

                    // Create instance of Oid for sha
                    var oid = new git.Oid();

                    // Set oid to the revision commit
           oid );

                    // Create instance of Sig for author
                    var author = new git.Sig();

                    // Set the author to the revision commit author
           author );

                    // Convert timestamp to milliseconds and set new Date object
                    var time = new Date( revisionCommit.time() * 1000 );

                    // Print out `git log` emulation
                    console.log( oid.toString( 40 ) );
                    console.log( + '<' + + '>' );
                    console.log( time );
                    console.log( '\n' );
                    console.log( revisionCommit.message() );
                    console.log( '\n' );

                    // Recurse!

            // Initiate recursion

Running tests

__ nodegit library code is written adhering to a modified JSHint. Run these checks with make lint in the project root. __

__ To run unit tests ensure the submodules nodeunit and rimraf are located in the vendor/ subdirectory. __

If they are not, cd into the nodegit dir and run the following git commands to automatically fetch them: $ cd nodegit $ git submodule init vendor/ $ git submodule update vendor/

Then simply run make unittest in the project root.

Release information

__ Can keep track of current method coverage at: __


* More methods implemented
* More unit tests
* More API development
* Tree and Blob support
* Updated libgit2 to version 0.8.0


* Some useful methods implemented
* Some unit tests
* Some documented source code
* Useable build/code quality check tools
* Node.js application that can be configured/built/installed via source and NPM
* An API that can be easily extended with convenience methods in JS
* An API that offers a familiar clean syntax that will make adoption and use much more likely
* Open for public testing
* GitHub landing page
* Repo, Oid, Commit, Error, Ref, and RevWalk support
* Built on libgit2 version 0.3.0

Getting involved

If you find this project of interest, please document all issues and fork if you feel you can provide a patch. Testing is of huge importance; by simply running the unit tests on your system and reporting issues you can contribute!

__ Before submitting a pull request, please ensure both unit tests and lint checks pass. __

Something went wrong with that request. Please try again.