nodegit-kit: A JavaScript repository from thisconnect

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(repo => {

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

        // git commit -am"commit message"
        return git.commit(repo, {
            'message': 'commit message'
        });
    })
    .then(() => {
        // git log
        return git.log(repo);
    })
    .then(log => {
        console.log(log);
    });
})
.catch(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(repo => {
    // NodeGit repository instance
})
.catch(err => {
    // 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(repo => {
    // git commit -am"a new commit"
    return git.commit(repo, {
        'message': 'a new commit'
    })
    .then(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(repo => {
    // git status
    return git.status(repo)
    .then(status => {
        console.log(status);
    });
});

log (repo[, options])

Returns an Array of all commits.

repo NodeGit repository instance
options
- branch String name of a branch, defaults to 'master'
- 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
- max-count Max number of commits to traverse

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

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

Returns an Array of modified files and their diffs.

repo NodeGit repository instance
options
- name-only Boolean return only filenames, defaults to false

git.open('../repo-path/new/or/existing')
.then(repo => {
    // git diff
    return git.diff(repo, { 'name-only': true })
    .then(filenames => {
        console.log(filenames);
    });
});

Get a diff of a commit

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

Get a diff between 2 commits

Breaking API change in 0.12.0 Changed order of from and to to be aligned with git-cli.

git.open('../repo-path/new/or/existing')
.then(repo => {
    return git.log(repo, { sort: 'reverse' })
    .then(history => {
        var commit1 = history[0].commit;
        var commit2 = history[2].commit;
        // git diff <from> <to>
        return git.diff(repo, commit1, commit2);
    })
    .then(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 johndoe@example.com.

git.open('my/repository')
.then(repo => {
    return git.config.set(repo, {
        'user.name': 'John Doe',
        'user.email': 'johndoe@example.com'
    });
});

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(repo => {
    return git.config.get(repo, ['user.name', 'user.email']);
})
.then(configs => {
    // [ 'John Doe', 'johndoe@example.com' ]
});

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(config => {
    // [ 'John Doe', 'johndoe@example.com' ]
});

config.set (options)

// WARNING: this will change your global git config
git.config.set({
    'user.name': 'John Doe',
    'user.email': 'johndoe@example.com'
});

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(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(err => {
    return git.init('../path/to/repo', {
        'commit': false
    })
    .then(repo => {
        // do something before first commit
        return repo;
    })
    .then(repo => {
        git.init.commit(repo, {
            'message': 'initialize repository'
        });
    });
})
.then(repo => {
    // NodeGit repository instance
});

Test

npm install

npm test

# debug nodegit-kit
DEBUG=kit* npm test

# debug all
DEBUG=* npm test

thisconnect/nodegit-kit