jeffmo / nodegit-kit

Complementary NodeGit helpers returning native Promises, helps with git commands such as init, add, commit, status, diff

NodeGit-Kit

Promises for git commands such as git init, git status, git add *, git diff, git log and git commit -am"commit message".

Comments are welcome at nodegit-kit/issues

Install

npm i --save nodegit-kit

Usage

var git = require('nodegit-kit');

git.open('../repo-path/new/or/existing')
.then(function(repo){

     // git diff
    return git.diff(repo)
    .then(function(diff){
        console.log(diff);

        // git commit -am"commit message"
        return git.commit(repo, {
            'message': 'commit message'
        });
    })
    .then(function(){
        // git log
        return git.log(repo);
    })
    .then(function(log){
        console.log(log);
    });
})
.catch(function(error){
    console.error(error);
});

API

• open
• commit
• status
• log
• diff
• config
• init
• init.commit

open (path[, options])

Returns repository, if no repo is found, tries to create the directory and initializes the repository. Initializing is using init internally.

• path String
• options Object
  • init Boolean whether to create a first commit, defaults to true

git.open('../repo-path/new/or/existing', {
    'init': false
})
.then(function(repo){
    // NodeGit repository instance
})
.catch(function(){
    // no repo here
});

commit (repo[, options])

Checks if status has pending changes, commits, returns Oid else returns null.

• repo NodeGit repository instance
• options
  • message String defaults to 'update'

git.open('../repo-path/new/or/existing')
.then(function(repo){
    // git commit -am"a new commit"
    return git.commit(repo, {
        'message': 'a new commit'
    })
    .then(function(oid){
        console.log(oid);
    });
});

status (repo)

Returns an Array of changed files and their status.

• repo NodeGit repository instance

git.open('../repo-path/new/or/existing')
.then(function(repo){
    // git status
    return git.status(repo)
    .then(function(status){
        console.log(status);
    });
});

log (repo[, options])

Returns an Array of all commits.

• repo NodeGit repository instance
• options
  • sort String can be 'none', 'topological', 'time' or 'reverse'
  • abbrev-commit Boolean if true shortens checksum, defaults to false
  • abbrev Number to specify a custom number of digits in combination with abbrev-commit, otherwise uses 'core.abbrev' config

git.open('../repo-path/new/or/existing')
.then(function(repo){
    // git log
    return git.log(repo)
    .then(function(log){
        console.log(log);
    });
});

diff (repo[, commit[, commit]])

Returns an Array of modified files and their diffs.

• repo NodeGit repository instance

git.open('../repo-path/new/or/existing')
.then(function(repo){
    // git diff
    return git.diff(repo)
    .then(function(diff){
        console.log(diff);
    });
});

Get a diff of a commit

git.open('../repo-path/new/or/existing')
.then(function(repo){
    return git.log(repo)
    .then(function(history){
        return history[0].commit;
    })
    .then(function(commit){
        // git diff <commit>
        return git.diff(repo, commit);
    })
    .then(function(diff){
        console.log(diff);
    });
});

Get a diff between 2 commits

git.open('../repo-path/new/or/existing')
.then(function(repo){
    return git.log(repo)
    .then(function(history){
        var commit1 = history[0].commit;
        var commit2 = history[2].commit;
        // git diff <from> <to>
        return git.diff(repo, commit1, commit2);
    })
    .then(function(diff){
        console.log(diff);
    });
});

config

Allows to write/read global and local git config values. Local values are stored in the Git directory ./git/config and overrule global configurations. Note: Git locks the config when changing configurations, therefore writing multiple configs can not be done in parallel. e.g. Promise.all multiple individual git.config.set calls will throw a "Failed to lock file for writing" error, nodegit/issues/757.

See also 8.1 Customizing Git - Git Configuration (Git SCM Documentation)

config.set (repo, options)

Example setting user.name and user.email for a specific repository

Set user name and email similar to cd repo then git config user.name "John Doe" and git config user.email [email protected].

git.open('my/repository')
.then(function(repo){
    return git.config.set(repo, {
        'user.name': 'John Doe',
        'user.email': '[email protected]'
    });
});

config.get (repo, options)

Example reading user.name and user.email

Similar to cd repo thengit config user.name returns config for a repository if there any or else the global Git configuration.

git.open('my/repository')
.then(function(repo){
    return git.config.get(repo, ['user.name', 'user.email']);
})
.then(function(configs){
    // [ 'John Doe', '[email protected]' ]
});

global git configuration

config.get (options)

When no repo is given, setting and getting config will operate in --global mode and read and write to ~/.gitconfig (or ~/.config/git/config).

git.config.get(['user.name', 'user.email'])
.then(function(config){
    // [ 'John Doe', '[email protected]' ]
});

config.set (options)

// WARNING: this will change your global git config
git.config.set({
    'user.name': 'John Doe',
    'user.email': '[email protected]'
});

init (path[, options])

Ensures directory exists, initializes, creates a first commit and returns repo. This is optional and only useful to control the first commit.

• path String
• options Object
  • bare Number defaults to 0
  • commit Boolean defaults to true
  • message String defaults to 'initial commit'

git.init('../repo-path/new/or/existing', {
    'bare': 0,
    'commit': true,
    'message': 'my first commit'
})
.then(function(repo){
    // NodeGit repository instance
});

init.commit (repo[, options])

Can be used to in combination with suppressing commit on init.

• repo NodeGit Repository instance
• options
  • message String defaults to 'initial commit'

git.open('../path/to/repo', {
    'init': false
})
.catch(function(){
    return git.init('../path/to/repo', {
        'commit': false
    })
    .then(function(repo){
        // do something before first commit
        return repo;
    })
    .then(function(repo){
        git.init.commit(repo, {
            'message': 'initialize repository'
        });
    });
})
.then(function(repo){
    // NodeGit repository instance
});

Test

npm install

npm test

# debug nodegit-kit
DEBUG=kit* npm test

# debug all
DEBUG=* npm test