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

vargit=require('nodegit-kit');git.open('../repo-path/new/or/existing').then(repo=>{// git diffreturngit.diff(repo).then(diff=>{console.log(diff);// git commit -am"commit message"returngit.commit(repo,{'message': 'commit message'});}).then(()=>{// git logreturngit.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"returngit.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 statusreturngit.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 logreturngit.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 diffreturngit.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=>{returngit.log(repo).then(history=>{returnhistory[0].commit;}).then(commit=>{// git diff <commit>returngit.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=>{returngit.log(repo,{sort: 'reverse'}).then(history=>{varcommit1=history[0].commit;varcommit2=history[2].commit;// git diff <from> <to>returngit.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=>{returngit.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=>{returngit.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 configgit.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=>{returngit.init('../path/to/repo',{'commit': false}).then(repo=>{// do something before first commitreturnrepo;}).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